AI Code Migration Assistant — Architecture (Deployment‑Ready)

1) Topology

• Frontend/BFF: Next.js 14 (App Router) on Vercel; Server Actions for clone tokens & exports; SSR dashboards.
• API Gateway: NestJS (Node 20) — REST /v1, OpenAPI 3.1, Zod validation, Problem+JSON, RBAC (Casbin), RLS, Idempotency‑Key, Request‑ID (ULID).
• Workers (Python 3.11 + FastAPI control):
  • clone-worker: git clone (sparse), submodules, LFS.
  • scan-worker: lang detect, framework probes, dep audit (advisories).
  • graph-worker: AST/symbol/import/call graphs (libcst/Bowler for Py; ts-morph/jscodeshift for JS/TS).
  • codemod-worker: deterministic rules (parallel), formatter pass (black/prettier).
  • agent-worker: LangGraph (Plan→Search(RAG)→Patch→Self‑Review→Test‑Hints), AST‑constrained edits.
  • build-worker: containerized build/type‑check/lint/test; coverage; flaky detector.
  • report-worker: metrics, risk burndown, type trend; PDF/JSON.
  • pr-worker: branch/commit signing/PR; topic splitting.
• Execution: sandboxed containers (Docker‑in‑Docker or Firecracker), cached toolchains (pyenv, nvm, pnpm, pip), read‑only tokens until PR step.
• Event Bus: NATS topics repo.clone, repo.scan, graph.make, codemod.apply, agent.patch, build.run, pr.open, report.make + Redis Streams for progress.
• Data:
  • Postgres 16 + pgvector (findings, plan steps, doc embeddings, code chunks).
  • S3/R2 (repo snapshots, patch bundles, reports).
  • Redis (job state/cache). Optional OpenSearch (code search).

2) Data Model (Postgres + pgvector)

-- Tenancy
CREATE TABLE orgs (id UUID PRIMARY KEY, name TEXT, plan TEXT DEFAULT 'pro', created_at TIMESTAMPTZ DEFAULT now());
CREATE TABLE users (id UUID PRIMARY KEY, org_id UUID, email CITEXT UNIQUE, role TEXT DEFAULT 'maintainer', created_at TIMESTAMPTZ DEFAULT now());
CREATE TABLE projects (id UUID PRIMARY KEY, org_id UUID, name TEXT, repo_url TEXT, default_branch TEXT, created_by UUID, created_at TIMESTAMPTZ DEFAULT now());

-- RAG docs
CREATE TABLE docs (id UUID PRIMARY KEY, project_id UUID, title TEXT, source TEXT, s3_key TEXT, meta JSONB);
CREATE TABLE doc_chunks (id UUID PRIMARY KEY, doc_id UUID, text TEXT, embedding VECTOR(1536), meta JSONB);
CREATE INDEX ON doc_chunks USING hnsw (embedding vector_cosine_ops);

-- Snapshots & graphs
CREATE TABLE snapshots (id UUID PRIMARY KEY, project_id UUID, commit_sha TEXT, branch TEXT, s3_tar TEXT, created_at TIMESTAMPTZ DEFAULT now());
CREATE TABLE modules (id UUID PRIMARY KEY, snapshot_id UUID, path TEXT, lang TEXT, framework TEXT, lines INT, meta JSONB);
CREATE TABLE dep_edges (id UUID PRIMARY KEY, snapshot_id UUID, src TEXT, dst TEXT, kind TEXT, weight NUMERIC, meta JSONB);
CREATE TABLE risk_flags (id UUID PRIMARY KEY, snapshot_id UUID, file TEXT, kind TEXT, detail TEXT, severity TEXT, meta JSONB);

-- Plans, codemods, patches
CREATE TABLE plans (id UUID PRIMARY KEY, project_id UUID, target_stack JSONB, estimate JSONB, rationale TEXT, created_at TIMESTAMPTZ DEFAULT now());
CREATE TABLE codemods (id UUID PRIMARY KEY, project_id UUID, name TEXT, lang TEXT, rule JSONB, deterministic BOOLEAN, meta JSONB);
CREATE TABLE patches (id UUID PRIMARY KEY, snapshot_id UUID, codemod_id UUID, file TEXT, diff TEXT, status TEXT, explanation TEXT, created_at TIMESTAMPTZ DEFAULT now());

-- Builds/tests
CREATE TABLE builds (id UUID PRIMARY KEY, project_id UUID, snapshot_id UUID, image TEXT, status TEXT, logs_s3 TEXT, started_at TIMESTAMPTZ, finished_at TIMESTAMPTZ, meta JSONB);
CREATE TABLE metrics (id UUID PRIMARY KEY, build_id UUID, name TEXT, value NUMERIC, unit TEXT, meta JSONB);

-- PRs/Exports
CREATE TABLE pull_requests (id UUID PRIMARY KEY, project_id UUID, branch TEXT, pr_url TEXT, status TEXT, meta JSONB, created_at TIMESTAMPTZ DEFAULT now());
CREATE TABLE exports (id UUID PRIMARY KEY, project_id UUID, kind TEXT, s3_key TEXT, meta JSONB, created_at TIMESTAMPTZ DEFAULT now());

-- Audit
CREATE TABLE audit_log (id BIGSERIAL PRIMARY KEY, org_id UUID, user_id UUID, action TEXT, target TEXT, meta JSONB, created_at TIMESTAMPTZ DEFAULT now());

Invariants

• RLS by project_id across all tables.
• Deterministic codemods must pass AST roundtrip + formatter.
• Agent patches require green type‑check/tests; otherwise quarantined.
• Every patch stores an explanation and any citations used (in explanation JSON).

3) APIs (REST /v1)

• Projects/Repo
  • POST /projects {name, repo_url, default_branch}
  • POST /projects/:id/clone
  • GET /projects/:id/graph
• Plan & RAG
  • POST /plans {project_id, target_stack}
  • GET /search?project_id=...&q=unicode+py2+pitfalls
• Codemods & Agent
  • GET /codemods?lang=python
  • POST /codemods/apply {project_id, codemod_id, scope:["src/**/*.py"]}
  • POST /agent/patch {project_id, goal:"convert callbacks to async/await in auth/"}
• Build & PR
  • POST /builds {project_id, snapshot_id}
  • POST /pull_requests {project_id, branch, title}
• Reports/Exports
  • POST /exports/report {project_id, format:"pdf|json"} Conventions: Idempotency‑Key; Problem+JSON; SSE for long jobs.

4) Pipelines

1. Clone → sparse checkout, submodules, LFS; snapshot tar to S3.
2. Scan → lang & framework probes; dep audit (advisories/EOL); collect README/Wikis/ADRs/JIRA for RAG.
3. Graph → AST/symbol/import/call graphs; dead code; risk flags (dynamic import, monkey patching, metaprogramming).
4. Plan → target stacks; codemod queue; effort & risk estimates with citations.
5. Codemods (deterministic) → parallel rules; formatter enforce; snapshot.
6. Agent refine → LangGraph plan→search→patch→self‑review; AST‑constrained edits; explanations; quarantine if unsafe.
7. Build/Verify → type‑check (mypy/pyright/tsc), lint, tests; coverage; flaky detector; smoke tests.
8. PR/Report → topic branches with commit signing; PR descriptions; PDF/JSON export.

5) Algorithms & Rule Packs

• Py2→3 essentials: print callization, unicode/bytes handling (sixless), iteritems()→items(), range/xrange, urllib2→requests, pathlib, f‑strings.
• JS→TS: .js→.ts rename, JSDoc migration, CommonJS→ESM (require→import; module.exports→export default), usage‑site type inference to minimize any, React class→FC + hooks, callback→async/await.
• Safety: AST pattern guards; semantic checks (e.g., isinstance(bytes) cases); property‑based mutation tests where feasible.
• Risk flags: reflective eval, dynamic imports, metaclasses, monkey‑patches, global singletons, implicit dtype/locale use.

6) Guardrails

• Deterministic first, AI last.
• All AI patches must compile + type‑check + test before PR.
• Diff budget per patch; large diffs force topic split.
• Sensitive files (secrets, migrations) read‑only unless explicitly whitelisted.
• SBOM/License check for any new deps; PR comment with findings.

7) Observability & Security

• OTel spans across stages (repo.clone, graph.make, codemod.apply, agent.patch, build.run, pr.open).
• Metrics: scan latency, codemod throughput, green‑PR rate, type coverage delta, risk burndown, flake rate.
• Sentry: formatter crashes, AST failures, flaky spikes.
• Security: SSO (SAML/OIDC), scoped tokens, sandbox egress allow‑lists, per‑project encryption, immutable audit.

8) Frontend Highlights

• RiskRadar (spider chart), DepMap (Cytoscape), CodemodPlanner, DiffViewer with type overlays, TypeCoverageMeter, BuildTimeline, PRComposer.
• Design: shadcn/ui + Tailwind; glassmorphism; color‑blind safe diffs; Framer Motion micro‑animations.

9) SLOs & Tests

• SLOs per plan: scan <6m, codemods <12m/5k files, build <8m, PR <30s.
• Golden fixtures for Py2→3, JS→TS; assert identical outputs.
• Mutation tests to catch semantic regressions.
• Load/Chaos: >1M LoC repos, submodule outages, VCS rate limits; retries with jitter.

10) Rollout

• Pilot on two real repos (Py monolith, JS SPA).
• Gated “AI agent” flag; expand after green‑PR rate ≥70%.
• Enterprise features: on‑prem runners, custom rule packs, private registry mirrors.