<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/2.x/2026-02-27-3-saas-tracker-integration-via-existing-connectors-journey/">
  <id>https://docs.spec-kitty.ai/adr/2.x/2026-02-27-3-saas-tracker-integration-via-existing-connectors-journey/</id>
  <title>SaaS Tracker Integration via Existing Connectors Journey</title>
  <updated>2026-02-27T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/2.x/2026-02-27-3-saas-tracker-integration-via-existing-connectors-journey/"/>
  <summary>Folds tracker binding, snapshot ingestion, and drift reporting into the established connectors and dashboard journey instead of building a parallel hosted surface.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Tracker integration requires team binding, work-package mapping, sync telemetry, drift reporting, and snapshot ingestion. A separate disconnected SaaS surface would duplicate navigation and break established user flows.&lt;/p&gt;
&lt;p&gt;SpecKitty SaaS already has connector patterns, dashboards, and activity feed conventions that users rely on.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Preserve coherent user journey in existing app information architecture.&lt;/li&gt;
&lt;li&gt;Reuse mature connectors domain and webhook style patterns.&lt;/li&gt;
&lt;li&gt;Minimize regression risk in production dashboards/nav.&lt;/li&gt;
&lt;li&gt;Enable phased rollout with team-scoped flags.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Build standalone tracker app area/navigation.&lt;/li&gt;
&lt;li&gt;Integrate tracker capability into existing &lt;code dir=&quot;auto&quot;&gt;apps/connectors&lt;/code&gt; + dashboard views (chosen).&lt;/li&gt;
&lt;li&gt;Delay SaaS integration and keep tracker entirely CLI-local.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option:&lt;/strong&gt; integrate tracker binding, snapshot ingestion, and tracker projections into existing connectors + dashboard flow.&lt;/p&gt;
&lt;h3 id=&quot;required-behavior&quot;&gt;Required Behavior&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;Add tracker binding and mapping models inside &lt;code dir=&quot;auto&quot;&gt;apps/connectors&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Expose tracker APIs under &lt;code dir=&quot;auto&quot;&gt;/api/v1/connectors/trackers/...&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Add snapshot ingestion endpoint (&lt;code dir=&quot;auto&quot;&gt;/api/v1/connectors/trackers/snapshots/&lt;/code&gt;) with idempotency receipts.&lt;/li&gt;
&lt;li&gt;Render tracker health/state in existing project/work-package detail surfaces.&lt;/li&gt;
&lt;li&gt;Render tracker sync/drift events in existing activity feed patterns.&lt;/li&gt;
&lt;li&gt;Roll out via team-scoped waffle flag for SaaS tracker capability.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ol&gt;
&lt;li&gt;Faster adoption through familiar navigation and pages.&lt;/li&gt;
&lt;li&gt;Lower implementation risk through reuse of established domain boundaries.&lt;/li&gt;
&lt;li&gt;Better observability consistency with existing event rows/cards.&lt;/li&gt;
&lt;/ol&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ol&gt;
&lt;li&gt;Requires careful migration/test coverage in existing pages.&lt;/li&gt;
&lt;li&gt;Some model growth in connectors domain.&lt;/li&gt;
&lt;/ol&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ol&gt;
&lt;li&gt;v1 is read/map/observe on SaaS side; outbound writes are deferred.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;This decision is validated when:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Connectors pages show tracker binding status without separate app navigation.&lt;/li&gt;
&lt;li&gt;Project detail includes tracker health summary.&lt;/li&gt;
&lt;li&gt;Work-package detail shows mapped external issue state.&lt;/li&gt;
&lt;li&gt;Snapshot ingestion is idempotent by receipt key.&lt;/li&gt;
&lt;li&gt;Existing GitHub webhook behavior remains unchanged.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;option-1-standalone-tracker-app-surface&quot;&gt;Option 1: Standalone tracker app surface&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Strong functional separation.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Fragmented UX and duplicate navigation.&lt;/li&gt;
&lt;li&gt;Higher delivery/regression risk.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;option-2-existing-connectorsdashboard-integration-chosen&quot;&gt;Option 2: Existing connectors/dashboard integration (Chosen)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Cohesive user journey.&lt;/li&gt;
&lt;li&gt;Maximum reuse of existing patterns.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Tighter coupling to current page architecture.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;option-3-cli-only-tracker-with-no-saas-journey&quot;&gt;Option 3: CLI-only tracker with no SaaS journey&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Lowest SaaS implementation effort.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;No team-level visibility or centralized operations.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Connectors models and endpoints:
&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;spec-kitty-saas-repo&gt;/apps/connectors/models.py&lt;/code&gt;
&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;spec-kitty-saas-repo&gt;/apps/connectors/urls.py&lt;/code&gt;
&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;spec-kitty-saas-repo&gt;/apps/connectors/views.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Dashboard integrations:
&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;spec-kitty-saas-repo&gt;/apps/web/views.py&lt;/code&gt;
&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;spec-kitty-saas-repo&gt;/templates/web/dashboards/project_detail.html&lt;/code&gt;
&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;spec-kitty-saas-repo&gt;/templates/web/dashboards/wp_detail.html&lt;/code&gt;&lt;/li&gt;
&lt;/ol&gt;</content>
</entry>
