"The handler layer delegates all business decisions to the service layer. The service layer owns consistency boundaries and orchestrates repositories. Repositories are the only components that touch the data store."

# If OpenTelemetry is instrumented - query traces for the flow you documented# Jaeger UI: http://localhost:16686# Filter by: operation name matching your entry point# Verify: does the trace span tree match your sequence diagram?# If no tracing is instrumented - this is the highest-priority debt item# for any microservices system. Add it before documenting other flows.

DISTRIBUTED SYSTEMS[ ] Synchronous chain of 3+ services (distributed monolith - single point of failure)[ ] No circuit breaker between services (cascade failure risk)[ ] Shared database between services (defeats service isolation)[ ] No distributed tracing instrumented (flows are unverifiable)[ ] Event topics with no schema registry (consumer drift)[ ] No dead-letter queue for failed event processing[ ] Services communicating without contract/spec (implicit coupling)[ ] No idempotency on event consumers (duplicate processing risk)

Place Order flow (serverless):1. User → API Gateway POST /orders2. → ProcessOrder (Lambda, sync)       → validates input       → writes ORDER record (DynamoDB)       → emits order.placed (EventBridge)       → returns 202 Accepted   [user response ends here]3. order.placed event → EventBridge rule → ReserveInventory (Lambda, async)       → reads PRODUCT record (DynamoDB)       → updates STOCK_LEVEL (DynamoDB, conditional write)       → emits inventory.reserved OR inventory.insufficient4a. inventory.reserved → ChargePayment (Lambda, async)       → calls PaymentGateway (external, 30s timeout)       → writes PAYMENT record (DynamoDB)       → emits payment.completed OR payment.failed4b. inventory.insufficient → NotifyUser (Lambda, async)       → sends email via SES       → writes ORDER status = CANCELLED (DynamoDB)

SERVERLESS[ ] Synchronous function chain > 3 hops (compounds cold start latency)[ ] Function timeout set to maximum (masks slow dependencies)[ ] Shared mutable state between function invocations (race condition)[ ] No cold start latency documented for user-facing functions[ ] Missing dead-letter queue on async triggers (silent failure)[ ] Database connection pool not managed per invocation (connection exhaustion)[ ] Secrets hardcoded in environment variables (should use Secrets Manager)[ ] No distributed tracing (X-Ray / OpenTelemetry) - flows unverifiable[ ] Function doing > 1 business responsibility (violates single-purpose principle)

LAYER VIOLATIONS[ ] Handler/controller directly calls data access layer (bypasses service)[ ] Domain/model layer imports from HTTP or UI layer[ ] Data access layer contains business logic beyond querying[ ] Service layer imports from handler/controller layerHANDLER / VIEW LAYER[ ] Handler method exceeds ~50 lines of logic[ ] Business rules computed inside a template or view[ ] State mutated directly in the handler without going through a service[ ] Auth checks scattered across handlers (not centralised in middleware)CONSISTENCY / STATE[ ] Multi-step write operation with no rollback/compensation if step N fails[ ] In-memory state shared across requests without synchronisation[ ] Cache written before DB (or vice versa) without atomic update[ ] Session/token stores domain objects that should live in the DBSERVICE / ORCHESTRATION LAYER[ ] God service: one module/class handling > 3 distinct business domains[ ] Business logic duplicated across multiple services[ ] Service calls another service directly, creating hidden coupling[ ] No clear owner for a cross-domain operation (logic scattered)DATA ACCESS[ ] N+1 queries (queries inside loops)[ ] Raw query strings concatenated with user input (injection risk)[ ] No query abstraction - SQL/query language used directly across many layers[ ] Missing index on frequently filtered or joined columnINTEGRATIONS[ ] External API called directly from service with no adapter/client wrapper[ ] No timeout configured on outbound HTTP calls[ ] No retry or circuit breaker on failure-prone external calls[ ] External API error codes leaked as-is into internal domain errors

❌ 42 components (basically a class diagram)✅ 7 capabilities: User Mgmt · Order Mgmt · Payment · Inventory · Notification · Reporting · Admin

❌ "The system manages the customer journey end-to-end"✅ OrderService (src/services/order.py) → handles place, modify, cancel operations     depends on: InventoryRepository, PaymentClient, NotificationService

❌ OrderManagement: orders AND payments AND invoices AND customer lookup✅ OrderManagement: order lifecycle only   PaymentProcessing: charge, refund, gateway   CustomerManagement: lookup, profile   Invoicing: document generation

❌ Doc contains: component diagram + layer table + data model   Missing: any sequence diagram showing what actually happens at runtime✅ Add: Key Flow - Place Order   User → POST /orders → AuthMiddleware → OrderHandler        → OrderService (consistency boundary begins)             → InventoryRepo.reserve()             → PaymentClient.charge()     [external, outside boundary]             → OrderRepo.save()        → (consistency boundary commits)        → response 201

❌ "Clean layered architecture, no business logic in handlers"   (written from the design doc, not the code)✅ "Intended: layered. Actual: 14 handler methods contain business logic.   See debt list section 11 for full inventory."

[ ] Component count is 5–12[ ] Every component maps to a named capability (not a function/class name)[ ] No component description uses "and" across unrelated domains[ ] At least 1 end-to-end sequence diagram exists[ ] Every external dependency has a role name (not just a product name)[ ] Document validated against actual code (not just design docs or README)[ ] A developer has confirmed the component boundaries[ ] Architectural debt is documented, not hidden

1. "Does this component diagram match how you'd explain the system to a new hire?"2. "Are there components I've merged that you'd keep separate?"3. "Is there behavior that doesn't appear in these diagrams?"4. "Does this consistency boundary diagram match what actually commits and rolls back?"5. "Which parts would you argue with?"

Scenario 1: Primary database unavailable→ Which components fail immediately?→ Which can degrade gracefully?→ Is there a circuit breaker? Does the doc show it?Scenario 2: External payment/API service returns 503→ Does the sequence diagram show the error path?→ Does the consistency boundary roll back?→ What is the user-visible impact?Scenario 3: Message broker / queue unavailable→ Which async flows stop?→ Are async dependencies documented in the component diagram?→ What is the fallback for each?Scenario 4: Deployment / process restart mid-request→ What state is lost?→ Is the state inventory in the doc accurate?→ What operations are not idempotent?

✅ Every gap found → update diagram OR add to debt list (never silently ignore)✅ Every disputed boundary → redrawn with developer input✅ Every unverified claim → marked [unverified] until confirmed✅ Every production incident that the doc can explain → referenced as validation evidence❌ Never mark validation complete if Gate 2 found disputes❌ Never leave a known gap undocumented

Analyze this module. Describe:1. Its business responsibility in one sentence (capability, not class name)2. The operations it exposes3. Its dependencies (data access, external clients, other services)4. Where it owns a consistency boundary (transaction, saga, etc.)5. Any notable patterns or anti-patternsApply compression: name the capability, not the class.

Analyze this handler/route file. Describe:1. The URL(s) and HTTP methods it handles2. What input it reads (path params, query, body, headers, session/token)3. What service/use-case it delegates to4. What it returns or renders5. Flag any business logic that should not be in the handler layerMap it as a request flow: entry → middleware → handler → service → response.

Analyze this data access module. Describe:1. The table(s) or collection(s) it maps to2. The queries or operations it exposes3. Any relationships and their loading strategy (eager/lazy)4. Any identified N+1 query risks5. Whether it contains business logic it shouldn't

Analyze this integration client. Describe:1. What external service it wraps (name it by role, not product)2. The operations it exposes to the internal system3. Timeout, retry, and circuit breaker configuration4. How external errors are translated to internal domain errors5. Whether the external API contract is hidden behind an interface

Analyze this build file. Extract:1. Language version and target runtime/platform2. All major framework and library dependencies with versions3. Any build plugins or tools that affect code generation or behavior4. Module/package structure if multi-module5. Any outdated, deprecated, or conflicting dependencies

I need to write an Architecture Decision Record for the following decision:Decision context: [describe the situation that forced the decision]What was decided: [state the decision in one sentence]When it was made: [date or approximate period]Constraints at the time: [technical, resource, time, or org constraints]Alternatives that were considered: [list them]Generate a complete ADR using this structure:1. Title (ADR-NNN: [imperative verb + subject])2. Status: Accepted3. Context (2–4 sentences - what was true at the time that forced this decision)4. Decision (1–2 sentences, direct - no hedging)5. Alternatives considered (table: option | why rejected)6. Consequences (positive / negative / risks)7. Review date (suggest a specific date based on the decision type)Write it as if you are the engineer who made the decision, in past tense.Be specific - avoid generic phrases like "to improve performance."

Below is a technical architectural debt list from an engineering analysis.Rewrite it for a CTO / VP Engineering audience using these rules:1. Replace every technical term with its business impact   (e.g. "N+1 query" → "database asks the same question N times under load")2. Frame each item as: [what it is] → [what happens if we don't fix it] → [what fixing it enables]3. Group items into three tiers:   - Immediate risk (production incidents or security exposure likely)   - Delivery friction (slowing feature development)   - Strategic constraints (limiting future scaling or modernization)4. For each item, provide: effort estimate in weeks, not story points5. End with a recommended priority order and the business case for the top 3Technical debt list to translate:[paste your anti-pattern checklist results here]

Below is a list of anti-patterns found in a codebase analysis.Score each one on two dimensions and assign a decision:Risk score (1–5):  5 = Data loss, security breach, or production outage likely  4 = Significant user impact or revenue loss possible  3 = Degraded performance or increased incident frequency  2 = Developer friction - slows delivery, doesn't break anything  1 = Cosmetic / style - no functional impactEffort score (1–5):  5 = Architectural overhaul - months  4 = Multi-sprint refactor - weeks, multiple teams  3 = Single-sprint fix - 1–2 weeks, one team  2 = Days of work - targeted, low risk  1 = Hours - config change or single fileDecision rules:  High risk + Low effort   → Fix Now  High risk + Med effort   → Fix Next Sprint  High risk + High effort  → Plan & Track  Med risk  + Low effort   → Fix When Passing  Med risk  + Med effort   → Backlog With Date  Low/Med   + High effort  → Accept & Document  Low risk  + Any effort   → SkipFor each item produce:  Item | Risk score (with one-sentence justification) | Effort score (with one-sentence justification) | DecisionAnti-patterns to score:[paste your checklist findings here]

I have a documented sequence diagram for [flow name]:[paste your sequence diagram here]And the following log excerpt from a production trace of the same flow:[paste log excerpt here]Compare them. For each hop in the sequence diagram:1. Does it appear in the logs?2. Are there hops in the logs that are NOT in the diagram?3. Does the ordering match?4. Do the error paths in the diagram match what the logs show?Produce:- A verified steps list (diagram matches log)- A discrepancy list (diagram says X, log shows Y)- Missing steps list (in logs but not in diagram)- Recommended diagram updates

Given these module summaries, apply the following compression rules:- Collapse modules/classes into capabilities (not names)- Collapse endpoints into use cases- Collapse tables/collections into domain concepts- Collapse integrations into rolesThen produce:1. Architecture style (one of: layered monolith / modular monolith /   microservices / event-driven / serverless / transitional)2. Component diagram (ASCII or Mermaid) with 5–12 components max3. Primary request flows as numbered step sequences4. Key design patterns identified5. Top 5 architectural debt items ranked by risk × effortFormat as an architecture overview document with explicit diagrams.

Node 1:  ingest_repo          → Clone repo, parse build file, extract dependency graphNode 2:  chunk_by_module      → Group files by module boundary (never by individual file)Node 3:  pass1_structure      → LLM: summarise each module (G.1–G.6 prompts)Node 4:  pass2_behavior       → LLM: trace top 3 flows, map state and async boundariesNode 5:  pass3_compress       → LLM: apply compression rules, generate component diagramNode 6:  assemble_draft       → Fill 12-section template, mark all claims [unverified]Node 7:  gate1_static         → Run jdeps/depcruise, diff import graph vs diagramNode 8:  gate2_human          → interrupt() — pause for developer review and feedbackNode 9:  gate3_runtime        → Fetch logs/APM, compare top flows against sequence diagramsNode 10: gate4_failure        → LLM: test doc against 4 standard failure scenariosNode 11: refinement           → Update diagrams + debt list; loop back if major gaps foundNode 12: publish_doc          → Write final Markdown + Mermaid, generate ADR stubs

# Wrong — loses inter-module contextfor file in repo.all_files():    summary = llm.summarise(file)# Right — preserves module relationshipsfor module in repo.modules_by_package():    summary = llm.summarise(module.all_files())

class PipelineState(TypedDict):    repo_path: str    build_file_summary: dict    module_chunks: list[ModuleChunk]    module_summaries: list[ModuleSummary]    flow_traces: list[FlowTrace]    component_diagram: str          # Mermaid source    anti_pattern_score: int    gate1_violations: list[str]    human_feedback: str    gate3_gaps: list[str]    gate4_gaps: list[str]    final_doc: str    debt_register: list[DebtItem]

1. Who specifically will read this section?2. What decision will it help them make?3. If I skip it, what is the worst realistic outcome?

✅ 1. Component diagram (5–12 components, capability-named)   → Answers: what are the moving parts?✅ 2. One end-to-end sequence diagram (the primary revenue flow)   → Answers: what actually happens at runtime?✅ 3. Debt score from the anti-pattern checklist   → Answers: how healthy is it, and what's the biggest risk?

Include:✅ Section 01 (Executive Overview) - expanded, business-language✅ Section 02 (Architecture) - component diagram only, no code references✅ Section 10 (Design Decisions) - framed as "why we built it this way"✅ Section 11 (Debt Map) - framed as risk and cost, not technical violations✅ Modernization options table (3 options with effort/risk/benefit)Remove or move to appendix:❌ All code snippets and bash commands❌ Section 03 (Handler Layer detail)❌ Section 06 (Data Model detail)❌ Anti-pattern checklist raw output

❌ Technical: "14 JSP files contain scriptlets - layer violation"✅ Business:  "14 UI components contain business logic - each change               requires a developer instead of a designer, slowing               feature delivery by ~2 days per change"

Include:✅ All 12 sections✅ Stack appendix (their specific stack)✅ Anti-pattern checklist (so they know what to avoid adding)✅ Sequence diagrams with code-level detail✅ Layer interaction rules (what is and isn't allowed)Emphasise:→ Section 03 (Handler Layer) - where to add new endpoints→ Section 04 (Component Design) - which service to call for what→ Section 05 (Data Flows) - how to trace a bug through the system→ Section 11 (Debt Map) - what not to copy from existing code

Include:✅ Section 07 (Security Architecture) - primary section, fully detailed✅ Section 05 (Data Flows) - annotated with: what data, where it goes, who can see it✅ Section 08 (Integrations) - every outbound call with auth mechanism✅ Section 09 (Deployment) - config management, secrets handling✅ Section 12 (NFR) - compliance requirements explicitly called outFormat requirements:→ Every security control must state: what it protects, how it's enforced, where it breaks→ Gaps must be listed explicitly - do not omit or soften them→ Use "identified gap" not "area for improvement"

Include:✅ All 12 sections✅ Actual vs intended architecture gap analysis (Section 11)✅ Full anti-pattern checklist results - raw, unfiltered✅ Architecture style identification (Section Pass 3, Step 2)✅ Known failure modes and production incidents referencedCritical: do not sanitize the debt map for this audience.A consultant working from an optimistic debt list will recommendthe wrong modernization path.

[ ] I know who will read this[ ] I have removed or summarised sections they won't use[ ] Technical terms affecting non-technical readers have been translated[ ] The debt/risk section is framed in the language this audience uses[ ] The document is the right length for their available reading time

Debt item:     [Name of the anti-pattern]Location:      [File / module / layer where it occurs]Risk score:    [1–5] - [one sentence explaining the risk]Effort score:  [1–5] - [one sentence explaining the fix]Decision:      [Fix Now / Fix Next Sprint / Plan / Accept / Skip]Owner:         [Team or engineer responsible]Target date:   [Specific date, not "Q3" - vague dates mean never]Evidence:      [Link to the specific code location]

Risk 3 vs 4 - ask: "Has this caused a production incident in the past year?"  Yes → score 4. No → score 3.Effort 3 vs 4 - ask: "Does fixing this require coordinating more than one team?"  Yes → score 4. No → score 3.When in doubt, score higher on risk, lower on effort.  Higher risk → more urgency to fix.  Lower effort → easier to justify doing it now.

Debt item:     Raw SQL concatenated with user inputLocation:      src/main/java/com/example/ReportController.java:214Risk score:    5 - SQL injection vulnerability, direct data breach pathEffort score:  1 - Replace string concat with PreparedStatement (2 hours)Decision:      Fix NowOwner:         Platform teamTarget date:   2025-02-14Evidence:      github.com/org/repo/blob/main/.../ReportController.java#L214---Debt item:     No timeout on payment gateway HTTP clientLocation:      src/main/java/com/example/PaymentClient.javaRisk score:    5 - Gateway hang blocks all payment threads, revenue stopsEffort score:  2 - Set connectTimeout + readTimeout in RestTemplate configDecision:      Fix NowOwner:         Payments teamTarget date:   2025-02-14Evidence:      github.com/org/repo/blob/main/.../PaymentClient.java#L31

Step 1: Map the disagreement precisely   → "We disagree about whether X calls Y directly" is precise   → "We disagree about the architecture" is not   → If you can't write the disagreement in one sentence, it's not     clear enough to resolveStep 2: Go to the code, not to consensus   → Check the actual import graph, not memory   → Run the dependency analysis tool (see appendix)   → The code is the ground truth - opinions are notStep 3: Document both views if the code is transitional   → "Intended: X → Service → Y. Actual: 3 of 14 handlers call Y directly.      Migration is 60% complete."   → Don't flatten a transitional state into a clean diagramStep 4: If still unresolved after step 2, the dispute is about the   intended architecture, not the current one   → Separate the two explicitly in the doc   → "Current state" vs "target state" are different sections

✅ Document the finding - omitting it makes the doc misleading✅ Frame as system state, not personal failure   → "The payment module has grown to own 4 distinct domains"   → NOT "John's payment module violates single responsibility"✅ Pair every finding with a recommended action   → A finding without a path forward reads as blame✅ Share findings with affected team leads before publishing broadly   → No one should read about a problem with their code for the first time     in a team-wide document❌ Never soften findings to the point of hiding them❌ Never name individual engineers in debt or violation lists

1. What the system does (1 paragraph, business language)2. What the current constraints are (3 bullets, business impact framing)3. What options we have (2–3 options, each with: cost / risk / benefit)4. What we recommend (1 option, with rationale)5. What we need from you (a decision, a resource, an approval)

# ADR-[number]: [Decision title]**Date:** YYYY-MM-DD**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-[N]**Deciders:** [Names or teams involved]## ContextWhat situation forced this decision? What constraints existed?(2–4 sentences. Be specific about what was true at the time.)## DecisionWhat was decided?(1–2 sentences. State it directly - no hedging.)## Alternatives considered| Option | Why rejected ||--------|-------------|| [Option A] | [Reason] || [Option B] | [Reason] |## Consequences**Positive:** What does this enable?**Negative:** What does this constrain or cost?**Risks:** What could go wrong because of this decision?## Review dateWhen should this decision be revisited? (Set a real date.)

ADR-001: Use layered monolith instead of microservicesADR-002: Use Spring MVC over REST-only APIADR-003: Store sessions in DB instead of in-memoryADR-004: Accept SOAP integration with ERP system (not replace)ADR-005: Use JPA/Hibernate for all data access

docs/  architecture/    adr/      ADR-001-monolith-over-microservices.md      ADR-002-spring-mvc-choice.md      ADR-003-session-storage.md    diagrams/      component-diagram-v3.mermaid      order-flow-sequence.mermaid    architecture-guide.md   ← this document

[ ] A new service or major component is added or removed[ ] The deployment model changes (e.g., monolith → modular, on-prem → cloud)[ ] A major external dependency changes (new payment provider, new DB)[ ] The authentication model changes[ ] A significant debt item is resolved (document the before/after)[ ] The team structure changes in a way that reflects in component ownership

## Document Version History| Version | Date | Author | Summary of changes ||---------|------|--------|-------------------|| v1.0 | 2019-03 | [name] | Initial architecture capture || v1.1 | 2020-08 | [name] | Added payment service, updated sequence diagrams || v2.0 | 2022-11 | [name] | Migrated from Struts to Spring MVC - full re-capture || v3.0 | 2024-06 | [name] | Extracted notification module, updated debt map |

# Run monthly - compare import graph against last documented state# If new cross-layer imports appear, flag for reviewjdeps -dotoutput ./deps-current target/myapp.jardiff deps-baseline.dot deps-current/myapp.dot# Count anti-pattern checklist items - track trend over time# Increasing score = drift is acceleratinggrep -c "^\[x\]" architecture-checklist-current.txt

[ ] A developer says "I didn't know that module existed"[ ] A bug required changes in 4+ unrelated modules[ ] A new hire's mental model of the system is significantly wrong after onboarding[ ] A production incident exposed a dependency not in the architecture doc[ ] The team is debating "how it works" rather than "how to improve it"[ ] An integration test exercises a path not in any sequence diagram

# Module-level dependency graphjdeps --print-module-deps -recursive target/myapp.jarjdeps -dotoutput ./deps target/myapp.jar# Full transitive dependency treemvn dependency:tree -Dverbosemvn help:effective-pom# Circular dependency detection# Add to pom.xml:# <rule implementation="org.apache.maven.enforcer.rules.dependency.BanCircularDependencies"/># Architecture rule enforcement (as JUnit tests)# ArchUnit: com.tngtech.archunit

# Find scriptlets (business logic in views - architectural debt)grep -rn "<%[^@!]" src/main/webapp --include="*.jsp"# Find session state (scalability constraint inventory)grep -rn "session\.setAttribute" src/ --include="*.java" --include="*.jsp"# Find JNDI lookups (service locator pattern - legacy signal)grep -rn "InitialContext\|lookup(" src/main/java --include="*.java"# Find raw SQL strings (injection risk + query inventory)grep -rn "\"SELECT\|\"INSERT\|\"UPDATE\|\"DELETE" src/ --include="*.java"

[ ] JSP contains <% %> scriptlets with business logic[ ] @Transactional placed on DAO methods (should be on service)[ ] JDBC calls with manual commit/rollback outside service layer[ ] HttpSession stores non-serializable domain entities[ ] N+1 queries from LAZY fetch in a loop (Hibernate)[ ] Spring XML config overridden by annotation config inconsistently

Analyze this JSP. Describe:1. What model attributes it expects2. Any business logic in scriptlets - list each occurrence3. Which forms it submits and to which action URLs4. Which other JSPs it includes5. Classify: pure view / mixed view-logic / heavy logic (migration needed)

Analyze this Maven POM. Extract:1. Java version and target runtime (Tomcat / JBoss / WebLogic)2. All major framework dependencies with versions3. Build plugins affecting behavior (aspectj, code generation, etc.)4. Multi-module structure5. Dependency conflicts or end-of-life libraries

# Import graph (pip install pydeps)pydeps src/myapp --max-bacon=3 --cluster# Circular import detectionpip install isortisort --check-only --diff .# Dead code / unused importspip install vulturevulture src/# Dependency treepip install pipdeptreepipdeptree# Type-checked architecture rulespip install import-linter# Define contracts in .importlinter config

# Find business logic in views (fat view detection)grep -rn "def get\|def post\|def put\|def delete" */views.py | wc -l# Find raw SQL (injection risk)grep -rn "raw(\|cursor.execute\|RawSQL" . --include="*.py"# Find direct model access in views (bypasses service layer)grep -rn "\.objects\." */views.py --include="*.py"# Find N+1 risks (queryset in loop)grep -rn "for.*in.*\:" . --include="*.py" -A2 | grep "\.objects\."# Django: check for missing select_related / prefetch_relatedgrep -rn "\.objects\.filter\|\.objects\.all" . --include="*.py" | \  grep -v "select_related\|prefetch_related"

[ ] Business logic in views.py / route handlers (fat views)[ ] Direct .objects. queryset calls inside view functions[ ] Missing select_related / prefetch_related (Django N+1)[ ] settings.py contains secrets (not env vars)[ ] Celery tasks contain business logic (should delegate to service)[ ] Django signals used for core business logic (obscures flow)[ ] Synchronous external HTTP calls inside async endpoint handlers

# Module dependency graphnpx depcruise --include-only "^src" --output-type dot src | dot -T svg > deps.svg# Circular dependency detectionnpx madge --circular src/# Unused exports / dead codenpx ts-prune# Outdated packagesnpm outdatednpx npm-check-updates# Bundle analysis (if applicable)npx webpack-bundle-analyzer

# Find route definitions (entry point inventory)grep -rn "router\.\(get\|post\|put\|delete\|patch\)" src/ --include="*.js" --include="*.ts"# Find direct DB calls in controllers (layer violation)grep -rn "\.find\|\.save\|\.query\|\.execute" src/controllers/ --include="*.ts"# Find missing async error handlinggrep -rn "async.*req.*res" src/routes/ --include="*.js" | grep -v "try\|catch"# Find untyped any (TypeScript debt)grep -rn ": any" src/ --include="*.ts" | wc -l

[ ] Business logic in Express route handlers directly[ ] Missing async error handling (unhandled promise rejections)[ ] Synchronous file I/O (fs.readFileSync) inside request handlers[ ] Missing input validation before DB operations[ ] No connection pooling configured for DB client[ ] Secrets hardcoded in source (not process.env)[ ] Callback hell - nested callbacks instead of async/await[ ] No rate limiting on public endpoints

# NDepend (commercial) - comprehensive .NET dependency analysis# dotnet-depends (free)dotnet tool install -g dotnet-dependsdotnet depends# Circular reference detection# ReSharper / Rider: built-in architecture diagram# Outdated packagesdotnet list package --outdated# Unused referencesdotnet tool install -g dotnet-script# Or use ReSharper's "Remove Unused References"

[ ] Business logic in Controller action methods[ ] DbContext injected directly into Controllers (bypasses repository)[ ] Missing cancellation token propagation in async methods[ ] Synchronous .Result or .Wait() calls on async methods (deadlock risk)[ ] Missing using statements / DbContext not disposed (connection leak)[ ] Secrets in appsettings.json committed to source control[ ] Missing EF Core AsNoTracking() on read-only queries[ ] N+1 queries from missing .Include() in EF Core

# Gem dependency treebundle viz   # generates dependency graph image# Circular dependency detectiongem install rubocop-railsrubocop --only Rails/FilePath# Dead code detectiongem install debridedebride app/# Unused gemsgem install bundler-auditbundle audit# Rails-specific: check for N+1gem install bullet  # add to Gemfile (development group)

[ ] Fat controller - business logic beyond params + render in controller[ ] Fat model - ActiveRecord model with 500+ lines of non-persistence logic[ ] Logic in views / ERB templates[ ] Direct ActiveRecord queries in controllers (bypasses service layer)[ ] N+1 queries - missing .includes() / .eager_load()[ ] Callbacks (before_save, after_create) containing business logic[ ] God model - one ActiveRecord class owning unrelated domains[ ] Missing database indexes on foreign keys and frequently queried columns

# Module dependency graphgo mod graph# Import cycle detection (built into go build)go build ./...    # fails on circular imports# Static analysisgo vet ./...# Dead codego install golang.org/x/tools/cmd/deadcode@latestdeadcode ./...# Dependency visualizationgo install github.com/kisielk/godepgraph@latestgodepgraph ./... | dot -Tpng -o deps.png# Outdated dependenciesgo list -m -u all

[ ] Business logic in http.HandlerFunc directly[ ] Missing context propagation (ctx not passed through call chain)[ ] Goroutine leak - goroutine started with no cancellation mechanism[ ] Missing error wrapping (errors.Wrap / fmt.Errorf %w)[ ] Global state in package-level variables (not safe for concurrent use)[ ] Interface not defined at point of use (defined in implementation package)[ ] Missing graceful shutdown handling (http.Server.Shutdown)[ ] init() functions with side effects (hidden initialization order)

Analyze this module. Describe:1. Its business responsibility in one sentence (capability, not class name)2. The operations it exposes3. Its dependencies (data access, external clients, other services)4. Where it owns a consistency boundary (transaction, saga, etc.)5. Any notable patterns or anti-patternsApply compression: name the capability, not the class.[paste module source code here]

Analyze this handler/route file. Describe:1. The URL(s) and HTTP methods it handles2. What input it reads (path params, query, body, headers, session/token)3. What service/use-case it delegates to4. What it returns or renders5. Flag any business logic that should not be in the handler layerMap it as a request flow: entry → middleware → handler → service → response.[paste handler source code here]

Analyze this data access module. Describe:1. The table(s) or collection(s) it maps to2. The queries or operations it exposes3. Any relationships and their loading strategy (eager/lazy)4. Any identified N+1 query risks5. Whether it contains business logic it shouldn't[paste data access source code here]

Analyze this integration client. Describe:1. What external service it wraps (name it by role, not product)2. The operations it exposes to the internal system3. Timeout, retry, and circuit breaker configuration4. How external errors are translated to internal domain errors5. Whether the external API contract is hidden behind an interface[paste client source code here]

Analyze this build file. Extract:1. Language version and target runtime/platform2. All major framework and library dependencies with versions3. Any build plugins or tools that affect code generation or behavior4. Module/package structure if multi-module5. Any outdated, deprecated, or conflicting dependencies[paste build file contents here]

Analyze this configuration file. Extract:1. What components/beans/services are registered2. What environment-specific values are present vs externalised3. Any security-sensitive config (credentials, secrets, connection strings)4. Cross-cutting concerns configured here (logging, auth, caching, tracing)5. What this config tells us about the intended architecture[paste config file here]

Given these module summaries, apply the following compression rules:- Collapse modules/classes into capabilities (not names)- Collapse endpoints into use cases- Collapse tables/collections into domain concepts- Collapse integrations into rolesThen produce:1. Architecture style (one of: layered monolith / modular monolith /   microservices / event-driven / serverless / transitional)2. Component diagram (ASCII or Mermaid) with 5–12 components max3. Primary request flows as numbered step sequences4. Key design patterns identified5. Top 5 architectural debt items ranked by risk × effortFormat as an architecture overview document with explicit diagrams.[paste module summaries here]

Based on these component summaries, generate a Mermaid sequence diagramfor the [flow name] flow.Include every hop: entry point → middleware → handler → service(s) →data access → external calls → response.For each hop show:- The component name- The operation called- Whether it is synchronous or async (use -->> for async)- Where the consistency boundary begins and ends (add a note)- What happens on failure at this hop (add alt block)[paste component summaries here]

Based on these module summaries, generate a Mermaid graph TD componentdiagram showing:1. All components as nodes (5–12 max, capability-named)2. Dependency arrows (A --> B means A depends on B)3. External systems as a different node shape4. Group components by layer using subgraph blocksLabel each arrow with the relationship type:  calls | reads | writes | emits | consumes[paste module summaries here]

I need to write an Architecture Decision Record for the following decision:Decision context: [describe the situation that forced the decision]What was decided: [state the decision in one sentence]When it was made: [date or approximate period]Constraints at the time: [technical, resource, time, or org constraints]Alternatives that were considered: [list them]Generate a complete ADR using this structure:1. Title (ADR-NNN: [imperative verb + subject])2. Status: Accepted3. Context (2–4 sentences - what was true at the time that forced this decision)4. Decision (1–2 sentences, direct - no hedging)5. Alternatives considered (table: option | why rejected)6. Consequences (positive / negative / risks)7. Review date (suggest a specific date based on the decision type)Write it as if you are the engineer who made the decision, in past tense.Be specific - avoid generic phrases like "to improve performance."

Below is a list of anti-patterns found in a codebase analysis.Score each one on two dimensions and assign a decision.Risk score (1–5):  5 = Data loss, security breach, or production outage likely  4 = Significant user impact or revenue loss possible  3 = Degraded performance or increased incident frequency  2 = Developer friction - slows delivery, doesn't break anything  1 = Cosmetic / style - no functional impactEffort score (1–5):  5 = Architectural overhaul - months  4 = Multi-sprint refactor - weeks, multiple teams  3 = Single-sprint fix - 1–2 weeks, one team  2 = Days of work - targeted, low risk  1 = Hours - config change or single fileDecision rules:  High risk + Low effort   → Fix Now  High risk + Med effort   → Fix Next Sprint  High risk + High effort  → Plan & Track  Med risk  + Low effort   → Fix When Passing  Med risk  + Med effort   → Backlog With Date  Low/Med   + High effort  → Accept & Document  Low risk  + Any effort   → SkipFor each item produce a table row:  Item | Risk (score + one-sentence justification) | Effort (score + justification) | DecisionAnti-patterns to score:[paste your checklist findings here]

Below is a technical architectural debt list from an engineering analysis.Rewrite it for a CTO / VP Engineering audience using these rules:1. Replace every technical term with its business impact   Examples:   - "N+1 query" → "database asks the same question N times under load - causes slowdowns at peak"   - "God service" → "one component doing too many things - a bottleneck and single point of failure"   - "No circuit breaker" → "if payment provider goes down, we go down with it - no automatic fallback"2. Frame each item as:   [What it is in plain language] → [What happens if we don't fix it] → [What fixing it enables]3. Group items into three tiers:   - Immediate risk (production incidents or security exposure)   - Delivery friction (slowing feature development)   - Strategic constraints (limiting future scaling or modernization)4. For each item provide effort in weeks, not story points5. End with:   - Recommended priority order (top 3 with business case)   - Total estimated remediation cost (engineering weeks)   - "If we do nothing" scenario in 12 monthsTechnical debt list:[paste your anti-pattern checklist results here]

Based on this architecture analysis, produce a 1-page executive brieffor a CTO / VP Engineering audience.Structure it exactly as:1. What this system does (2 sentences, business language only)2. Current architecture (1 sentence naming the style + 1 key diagram reference)3. Current constraints (3 bullets, each: constraint → business impact)4. Options (2–3 options, each: name | effort | risk | what it enables)5. Recommendation (1 option with 2-sentence rationale)6. What we need from you (one specific decision or resource)Rules:- No technical jargon- No code references- Each bullet max 2 lines- Total length: fits on one A4 pageArchitecture analysis input:[paste your architecture doc sections 01, 10, 11 here]

I have a documented sequence diagram for [flow name]:[paste your sequence diagram here]And the following log excerpt from a production trace of the same flow:[paste log excerpt here]Compare them. For each hop in the sequence diagram:1. Does it appear in the logs? (yes / no / partially)2. Are there log entries for hops NOT in the diagram?3. Does the ordering match?4. Do the error paths in the diagram match what the logs show?Produce four lists:- Verified steps (diagram matches log)- Discrepancies (diagram says X, log shows Y - explain each)- Missing from diagram (in logs but not documented)- Recommended diagram updates

I have two versions of an architecture document.Version A (older - the baseline):[paste older component diagram / capability table here]Version B (current - what we believe is true now):[paste current component diagram / capability table here]Identify:1. Components added (in B, not in A)2. Components removed (in A, not in B)3. Dependency changes (arrows that changed direction or were added/removed)4. Responsibility changes (same component, different scope)5. Architecture style changes (if the overall style shifted)For each change, assess:- Is this intentional (planned evolution) or drift (unplanned accumulation)?- Does it require a new ADR?- Does it require updating sequence diagrams?

Here is my architecture documentation for [system name]:[paste component diagram + key sequence diagrams here]Walk through this failure scenario:Scenario: [describe the failure - e.g., "Primary database becomes unavailable for 5 minutes"]For each component in the architecture:1. Is it directly affected? (yes / no / cascades from another)2. What is the user-visible impact?3. Does the architecture documentation show a fallback or circuit breaker?4. Does the documented behavior match what would actually happen?Produce:- Impact map (which components fail, cascade, or survive)- Documentation gaps (what the doc doesn't answer about this scenario)- Recommended additions to sequence diagrams or deployment section

Day 1 - Structure (Pass 1)  G.5 (build file) → G.6 (config) → G.3 (data access) → G.1 (services)Day 2 - Behavior (Pass 2)  G.2 (handlers) → G.4 (integrations) → G.8 (sequence diagrams)Day 3 - Abstraction (Pass 3)  G.7 (derive architecture) → G.9 (component diagram) → G.11 (score debt)Day 4 - Documentation  G.10 (ADRs for top 3 decisions) → G.12 (exec translation) → G.13 (brief)Day 5 - Validation  G.14 (validate sequences vs logs) → G.16 (failure scenarios) → refine