AI Code Migration Assistant — Architecture (Deployment‑Ready)

# 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)
```sql
-- 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.