Step 1: Project Scaffolding - Task Breakdown

Step 1: Project Scaffolding

Status: Ready to Start

Checklist

Monorepo Setup

• Root package.json with workspaces
• turbo.json pipeline config
• .gitignore (node_modules, dist, .env)
• .env.example with all required vars

Core Package (packages/core)

• src/types/index.ts — All shared interfaces
• src/constants/index.ts — Error codes, API endpoints
• src/utils/index.ts — Shared helpers
• package.json with build scripts

Docker Infrastructure

• docker/Dockerfile.sandbox — Bun + test deps
• docker/docker-compose.yml — PostgreSQL + Redis
• Health checks for all services

Verification

• bun install succeeds
• bun run build compiles all packages
• bun run test runs (even if no tests yet)
• docker compose up starts all services

Files to Create

driftlock/
├── package.json              # workspaces: ["packages/*", "apps/*"]
├── turbo.json                # build, dev, test pipelines
├── .gitignore
├── .env.example
├── packages/
│   └── core/
│       ├── package.json
│       └── src/
│           ├── types/index.ts
│           ├── constants/index.ts
│           └── utils/index.ts
└── docker/
    ├── Dockerfile.sandbox
    └── docker-compose.yml

Questions

1. Should we add ESLint + Prettier in Step 1 or later?
2. Database schema — when to introduce Drizzle?

---

Assignee: @NalinDalal
Target: Complete by end of day

[NalinDalal]

Implementation Log 001: Project Scaffolding and Initial Components

Date: 2026-09-13
Baseline: main, merge commit 73ce555
Related PR: #6: fix configs
Status: Core scaffolding implemented; local service setup remains outstanding.

Step 1: What is complete

• Bun monorepo with workspaces

  • Configured apps/* and packages/* workspaces with Bun 1.3.11.
  • Established shared packages for core types, parsing, Git tracking, sandbox execution, agent functionality, and tests, plus the CLI application.
  • Why: Keep related components together while maintaining separate responsibilities and reusable internal packages.
  • Reference: package.json:5.

• Turborepo pipeline configuration

  • Defined build, development, test, lint, and typecheck tasks.
  • Builds declare upstream build dependencies and dist/** outputs; development tasks are persistent and uncached.
  • Why: Provide consistent task orchestration and dependency-aware build caching across workspaces.
  • Reference: turbo.json:4.
  • Note: Pipeline declarations do not, by themselves, mean every package implements every task.

• Shared core types

  • CallSite: where and how application code calls an API.
  • Snapshot: captured request/response shapes and execution metadata.
  • DriftEvent: differences between snapshots, confidence, and resolution status.
  • Fix: a proposed correction, its diff, affected files, and confidence.
  • Added supporting types for repositories, diff summaries, analysis, test classification, and coverage.
  • Why: Give components consistent data contracts before connecting the full detection and remediation workflow.
  • References: packages/core/types.ts:1, :17, :29, and :65.

• Docker Compose for PostgreSQL + Redis

  • Not present in the merged repository.
  • The quick-start guide references a Compose file that does not exist.
  • CI provisions PostgreSQL 16, but that is not equivalent to local PostgreSQL + Redis setup.
  • Intended role: PostgreSQL for persistent application data; Redis for queued/background work.
  • References: QUICKSTART.md:19, .github/workflows/ci.yml:12.

Additional implementation already started

These are partial implementations, not completed blueprint milestones:

Area	Present today	Still outstanding
Parser	TypeScript AST traversal, basic stripe.* detection, endpoint mappings, initial request-shape extraction	Complete shape inference and response-field extraction
Git tracker	File change detection, explicit base comparisons, basic Git operations	Historical call-site comparison and API snapshot comparison
Sandbox	Docker execution scaffold with resource limits, timeout handling, and cleanup	Integrated traffic capture, endpoint restrictions, and test classification
Agent	Initial change-analysis and fix-suggestion methods	Robust response validation and integration into the end-to-end workflow
CLI	Initial analyze, test, diff, and init commands	Snapshot-based drift analysis and working fix command

The CLI currently reports Git file changes rather than API snapshot differences. Its fix command explicitly reports that it is unavailable instead of claiming success.

The web dashboard and automated PR generation remain outstanding.

Stabilization included in PR #6

• Corrected workspace entrypoints, runtime dependencies, and test/coverage command paths.
• Improved analysis-response parsing and explicit Git base comparisons.
• Removed credential collection and plaintext credential storage from initialization.
• Disabled networking in CLI-launched sandboxes until endpoint restrictions are enforced.
• Removed premature database configuration and the inactive CI lint step.
• Added tests and improved isolation of external network and Docker dependencies.

Why: Make the initial components more reliable while avoiding unsafe defaults, broken configuration, and misleading success messages.

Validation

The CI job on PR #6 completed successfully before merge.

This confirms the configured CI checks passed, not that the complete drift-detection system is implemented or production-ready.

Follow-up

• Add and verify PostgreSQL + Redis Compose setup.
• Correct the blueprint checklist and setup documentation to match the repository.
• Complete parser request/response extraction and validate against real Stripe integrations.
• Implement snapshot persistence and comparison before connecting automated fixes.

Milestone conclusion: The shared project foundation is in place, and several later components have initial implementations. Step 1 should remain partially complete until local PostgreSQL + Redis setup is delivered.

[NalinDalal]

Install is the signup

DriftLock isn't a normal SaaS with accounts, it's a GitHub App that acts on your repos. So the model mirrors CodeRabbit/Renovate, not Vercel:

Two identities, not one:

	Who	Acts as	Entrance
The App	machine, per-org/repo	opens PRs, gets webhooks	"Install on GitHub"
The human	you, per-GitHub-account	reads dashboard, approves/merges PRs, config	"Sign in with GitHub" (OAuth)

install = signup. When a user installs the app on an org/repo, that is the account being created — we already persist it (installations + repositories tables, real webhooks). There is no password, no separate signup form, nothing to build for "creating an account."

signin = OAuth. Connecting their GitHub identity so the dashboard knows who's looking, shows only their org's installs, and attributes actions ("you merged the driftlock PR").

The resulting loop:

1. Visit site → Install on GitHub (repo scope, like we defined)
2. First run onboarding per repo: pick test command, paste sk_test_*-typed secret, run baseline capture
3. App schedules re-probes → on drift, opens a driftlock/ PR
4. Human gets the PR, sign in via OAuth to see the dashboard: call sites × monitored/blind/untested, drift history, PR status
5. CLI stays as the local/dev face of the same loop

[NalinDalal]

Current plan (2026-09-16 to 2026-09-17)

App split

• apps/webhook (Bun native server, :3001): owns /webhooks/* (GitHub
  events), /auth/* (GitHub OAuth), and the JSON API the dashboard reads
  and writes. One deployable.
• apps/fe (React, Vite, TanStack Router): the customer dashboard. It only
  calls the webhook JSON API. Install and PR work stays in GitHub and the
  webhook server.

Two GitHub identities

Identity	What it is	What it grants
App installation (machine)	Installed per account (user or org)	Read repo contents, write PRs, scoped to installed repos
OAuth (human)	Person signs into the dashboard	read:user + read:org, only lists the accounts they belong to

Scopes, human sign-in:

• read:user: the human's profile and own account.
• read:org: which orgs the human belongs to.
• No repo scope on the OAuth token. Repo data flows through the
  installation token, not the human's token.

Dashboard model

First screen is the accounts where DriftLock is installed (own account plus
each org). Then it drills down:

Account -> Repo -> Call sites, drift events, PRs

Account-first, not repo-first. Installs are per-account, and that is what the
human controls.

What humans do in the dashboard

PRs always land in GitHub. The dashboard never merges or applies code; it is
the control plane:

• Pick which orgs and repos are watched.
• Read/write permissions per repo or org, CodeRabbit-style.
• Store API keys and probe credentials; set preferences and schedules.
• See what drift was found, which PRs opened, and their status.

Humans act on PRs in GitHub, not in the dashboard.

[NalinDalal]

Abhi tak yeh hua hai:

Working features:

1. Webhook capture — Stripe/Twilio jaise vendors ke webhooks capture karta hai
2. Schema drift detection — Jab payload change hota hai, detect karta hai (field added/removed/type changed)
3. Auto PR creation — Code scan karta hai, affected files dhundhta hai, GitHub PR khud create karta hai
4. GitHub OAuth login — User GitHub se login kar sakta hai
5. GitHub App install — Repos select karke install kar sakta hai
6. Settings dashboard — Config save hoti hai database mein (token, repo path, etc.)
7. Rollback detection — Jab schema wapas aata hai, detect karta hai

What it does end-to-end:

Stripe webhook aata hai
        ↓
Schema capture hota hai
        ↓
Drift detect hota hai (e.g., "source" field gaya)
        ↓
Repo scan hota hai (payment.js, webhook.js)
        ↓
Fix lagta hai (/* TODO: field removed */)
        ↓
GitHub PR create hota hai

Demo proof:

• ~/repos/stripe-test pe PR Implementation Blueprint - Full System Architecture #1 bana hai
• driftlock: Fix payment_intent.succeeded webhook handler NalinDalal/stripe-test#1
• source field removed, payment_method added
• Auto-fix apply hua

What's NOT done:

• Parser (code ko deeply samajhna)
• AI agent (actual code fix likhna)
• CLI/UI
• Git tracker
• Test sandbox

Ab kya karna hai — AI agent ya parser?

[NalinDalal]

Step 1: Final Status

Complete:

• ✅ Bun monorepo with workspaces
• ✅ Turborepo pipeline config
• ✅ Core types (CallSite, Snapshot, DriftEvent, Fix)
• ✅ PostgreSQL schema (repositories, call_sites, snapshots, drift_events)
• ✅ Drizzle ORM + migrations
• ✅ Docker Compose for PostgreSQL
• ✅ Database workspace package (@driftlock/db)

Moved to Step 2 (webhook capture):

• Webhook server (apps/webhook)
• Schema capture and drift detection
• PR creation pipeline
• GitHub OAuth + App installation

Still pending (not Step 1 scope):

• Redis (not needed for MVP)
• Sandbox testing (Step 4)
• Parser AST analysis (Step 2)

Conclusion: Step 1 is complete. The foundation is in place and the webhook capture system (which was originally planned for later steps) is already working end-to-end.