Architecture Blueprint Generator

Step 2 — Classify Streams

Using signals from stack-patterns.md, determine which streams are present:

For monorepos, classify each workspace package independently and run sub-agents per package.

Step 3 — Delegate to Sub-agents

Invoke each detected sub-agent with its scoped path. Pass:

• The root path to analyze
• The stream type
• Any detected framework name (e.g., "React 18", "NestJS", "Django")

Collect the structured report from each sub-agent before proceeding.

Error handling: If a sub-agent returns an empty report or fails, do NOT abort the whole analysis. Record the failure, continue with the remaining sub-agents, and include a > ⚠️ Warning note in the relevant section of the output file.

Step 4 — Synthesize

Using the sub-agent reports, build the cross-stream view:

1. Identify the Frontend ↔ Backend contract: REST, GraphQL, tRPC, WebSocket, or SSR
2. Identify the Backend ↔ Data contract: ORM, query builder, raw SQL, event sourcing
3. Find shared types/schemas that cross stream boundaries
4. Trace the end-to-end auth flow: login UI → API auth → session/token storage
5. List cross-cutting infrastructure: logging, observability, feature flags, CDN, queue

Step 5 — Generate Diagrams

Produce Mermaid diagrams at the appropriate scope:

• System diagram: all streams as subgraphs with cross-stream contracts
• Component diagrams: per-stream (from sub-agent reports)
• Sequence diagram: one representative end-to-end flow (e.g., user login or core feature)
• ER diagram: if a Data stream was found (from data-analyst report)
• Dependency map: inter-module and inter-service edges; flag circular dependencies

Step 6 — Write Output

Save the final blueprint to docs/architecture.md using the structure in architecture-template.md.

If docs/ does not exist, create it. Confirm the file path to the user when done.

Error handling: If the file cannot be written (permissions, read-only workspace), print the full blueprint content to the conversation as a fallback so the user does not lose the output.

Quality Checklist

Before finishing, verify:

• All detected streams are covered (no stream silently skipped)
• Every diagram compiles — verify Mermaid syntax (no unclosed brackets, valid node IDs)
• API table has at least one row per router/controller file found
• No speculation — every claim in the doc traces to a file read during analysis
• Cross-stream contracts section is present if more than one stream was detected
• Output saved to docs/architecture.md (or acknowledged as inline per user request)
• Any sub-agent failures are documented with a ⚠️ Warning note in the output
• If no streams were detected, the user was notified and analysis was not silently aborted
• If output write failed, the blueprint was printed to the conversation as a fallback