Whole Repo Architecture Review

Perform a READ-ONLY, whole-repo architecture review of the provided repository: {{Context:if used in an AI agent use the current project}}.

Review Focus: {{Focus: Comprehensive, Fit and Boundaries, Execution and Data Flow, Quality Levers, Simplification Opportunities}}

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.
- 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.