Whole-Repo Architecture Review (Read-Only)

Perform a READ-ONLY, whole-repo architecture review of the provided repository. Do not modify files. Do not invent or speculate about files that do not exist. Ground every claim in concrete paths and code excerpts with line ranges.

GOAL
- Assess how well the current architecture fits the problem the code claims to solve.
- Identify simplifications and refactors that reduce surface area without loss of functionality.
- Propose a target architecture and a minimal, low-risk migration path.

CONSTRAINTS
- Cite: Use the exact format path:line-start–line-end for every finding (use an en dash, e.g., src/api/user.ts:12–27).
- Distinguish **Facts (observed)** vs **Inferences (reasoned)**.
- Prefer the smallest effective change that achieves the goal.
- Do not run external services or mutate the repo.

SCOPE
- Include source code, tests, scripts, infra-as-code, build/CI, container files, configs, schemas, migrations, and docs.
- Detect and list all languages and frameworks present.

METHOD
1) Inventory
   - List modules, packages, services, binaries, CLIs, lambdas, and jobs.
   - Build a dependency map: in-repo imports, cross-service calls, third-party libs.
   - Detect data stores and message buses; list schemas, migrations, and ORMs.
2) Fit and boundaries
   - Identify logical domains and current boundaries.
   - Rate cohesion and coupling per boundary.
   - Flag “god” modules, cyclic deps, and feature leakage across layers.
3) Execution and data flow
   - Trace 3–5 key user journeys or API calls end to end.
   - For each: entry → validation → business rules → I/O → errors → logging → exit.
4) Quality levers
   - Error handling and resilience: timeouts, retries, idempotency, backoff.
   - Configuration: 12-factor, env vs code, secrets management.
   - Observability: logs, metrics, traces, structured context propagation.
   - State and concurrency: shared mutability, locking, async patterns.
   - Performance hotspots: N+1, large JSON, sync I/O on hot paths.
   - Security: secrets, authN/authZ, input validation, injection, SSRF, deserialization.
   - Testing strategy: unit vs integration vs e2e, flakiness, coverage of critical paths.
   - Build/CI/CD: determinism, caching, artifact versioning and promotion.
5) Simplification opportunities
   - Collapse layers that add no invariants.
   - Replace custom frameworks with well-known libraries.
   - Extract tight clusters into modules; inline trivial wrappers.
   - Delete unused code, flags, endpoints, migrations.
   - Consolidate duplicate models/DTOs and error types.
   - Normalize naming and directory structure.
6) Target architecture
   - Propose thin, explicit module/service boundaries.
   - Define minimal contracts: interfaces, DTOs, events.
   - Specify a “golden path” for a request and a background job.
7) Migration plan
   - Phased steps with acceptance checks.
   - Risk, blast radius, and rollback for each phase.
   - Success metrics: latency, error rate, cyclomatic complexity, bundle size, build time.

HEURISTICS & SMELLS CHECKLIST
- Cyclic imports; implicit singletons; wide constructors; global mutable state.
- Overuse of DI or service locators.
- Anemic domain model or business logic leaking into controllers/ORM models.
- Fat util packages; duplicate validation or business rules.
- N+1 DB queries; chatty network calls; sync I/O in request paths.
- Feature flags never removed; dead code and endpoints.
- Tests asserting implementation details rather than behavior.
- Secrets in code; permissive CORS; missing authZ checks.
- CI without pinned versions; non-reproducible builds.

OUTPUT FORMAT (use every section; keep tight and sourced)
A) Repo Overview
   - Stack summary
   - Module map
   - Runtime components
B) Dependency Graph (text tree)
   - Intra-repo and key third-party deps
   - Cycles found
C) Architectural Assessment
   - What works
   - What does not work
   - Top 10 risks (ranked)
D) Simplification Opportunities (ranked)
   For each:
   - Name
   - Current state (**Facts**) with citations (path:line-start–line-end)
   - Proposed change
   - Expected impact (perf, reliability, complexity)
   - Risk level and effort (S/M/L)
E) Target Architecture (concise)
   - Boundaries and contracts
   - Golden path sequence (request)
   - Golden path sequence (background job)
F) Migration Plan
   - Phase 0: Baseline metrics to capture
   - Phase 1..N: Steps → acceptance criteria → rollback
G) Metrics to Track
   - Example formulas and how to measure in this repo
H) Appendix
   - Findings index: finding → citations
   - Unused/dead code list
   - Glossary of key types, tables, and events

CITATION RULES
- Every non-obvious statement requires at least one citation.
- Use multiple citations when a claim spans files or layers.
- Quote short excerpts when helpful. Keep quotes under 25 words. Prefix with `>` and include a citation line.

TRACE TEMPLATES
- Finding: <short name>
  - Fact: <what is observed> (path:line–line)
  - Inference: <what it implies>
- Journey Trace:
  - Entry: <file.fn> (path:line–line)
  - Validation: <file.fn> (path:line–line)
  - Business rules: <file.fn> (path:line–line)
  - I/O: <file.fn> (path:line–line)
  - Errors: <file.fn> (path:line–line)
  - Logging: <file.fn> (path:line–line)
  - Exit: <file.fn> (path:line–line)

QUICK COMMANDS (suggested repo ops; adapt to tooling available)
- List large files and hotspots.
- Detect duplicate code and cycles.
- Map import graph per package.
- Grep for TODO/FIXME, feature flags, and unused exports.

START
- Print “Inventory” first with module map and detected entry points.
- Then proceed in order. Stop if repo is too large; sample representative modules and note the sampling method.