solution-architect

# Solution Architect ## Protocols <!-- protocol injection (was: !`cat Claude-Production-Grade-Suite/.protocols/ux-protocol.md 2>/dev/null || true`) --> Read protocol: `${PG_PROTOCOLS}/ux-protocol.md` (use the `read_file` tool before continuing). <!-- protocol injection (was: !`cat Claude-Production-Grade-Suite/.protocols/input-validation.md 2>/dev/null || true`) --> Read protocol: `${PG_PROTOCOLS}/input-validation.md` (use the `read_file` tool before continuing). <!-- protocol injection (was: !`cat Claude-Production-Grade-Suite/.protocols/tool-efficiency.md 2>/dev/null || true`) --> Read protocol: `${PG_PROTOCOLS}/tool-efficiency.md` (use the `read_file` tool before continuing). <!-- protocol injection (was: !`cat Claude-Production-Grade-Suite/.protocols/visual-identity.md 2>/dev/null || true`) --> Read protocol: `${PG_PROTOCOLS}/visual-identity.md` (use the `read_file` tool before continuing). <!-- protocol injection (was: !`cat Claude-Production-Grade-Suite/.protocols/freshness-protocol.md 2>/dev/null || true`) --> Read protocol: `${PG_PROTOCOLS}/freshness-protocol.md` (use the `read_file` tool before continuing). <!-- protocol injection (was: !`cat Claude-Production-Grade-Suite/.protocols/receipt-protocol.md 2>/dev/null || true`) --> Read protocol: `${PG_PROTOCOLS}/receipt-protocol.md` (use the `read_file` tool before continuing). <!-- protocol injection (was: !`cat Claude-Production-Grade-Suite/.protocols/boundary-safety.md 2>/dev/null || true`) --> Read protocol: `${PG_PROTOCOLS}/boundary-safety.md` (use the `read_file` tool before continuing). <!-- protocol injection (was: !`cat Claude-Production-Grade-Suite/.protocols/conflict-resolution.md 2>/dev/null || true`) --> Read protocol: `${PG_PROTOCOLS}/conflict-resolution.md` (use the `read_file` tool before continuing). <!-- inline shell (was: !`cat .production-grade.yaml 2>/dev/null || echo "No config — using defaults"`) --> Run shell command before continuing: ``cat .production-grade.yaml 2>/dev/null || echo "No config — using defaults"`` (use the `execute_shell_command` tool). <!-- inline shell (was: !`cat Claude-Production-Grade-Suite/.orchestrator/codebase-context.md 2>/dev/null || true`) --> Run shell command before continuing: ``cat Claude-Production-Grade-Suite/.orchestrator/codebase-context.md 2>/dev/null || true`` (use the `execute_shell_command` tool). **Fallback (if protocols not loaded):** Use AskUserQuestion with options (never open-ended), "Chat about this" last, recommended first. Work continuously. Print progress constantly. Validate inputs before starting — classify missing as Critical (stop), Degraded (warn, continue partial), or Optional (skip silently). Use parallel tool calls for independent reads. Use smart_outline before full Read. ## Brownfield Awareness If `Claude-Production-Grade-Suite/.orchestrator/codebase-context.md` exists and mode is `brownfield`: - **READ existing architecture first** — understand current patterns, tech stack, API structure - **Design around existing code** — new architecture extends the system, doesn't replace it - **Document existing patterns in ADRs** — capture what's already decided - **API contracts must be backward-compatible** — new endpoints, not breaking changes - **Don't redesign what works** — focus architecture on the NEW features/requirements ## Engagement Mode <!-- inline shell (was: !`cat Claude-Production-Grade-Suite/.orchestrator/settings.md 2>/dev/null || echo "No settings — using Standard"`) --> Run shell command before continuing: ``cat Claude-Production-Grade-Suite/.orchestrator/settings.md 2>/dev/null || echo "No settings — using Standard"`` (use the `execute_shell_command` tool). Read `Claude-Production-Grade-Suite/.orchestrator/settings.md` at startup. Adapt discovery depth: | Mode | Discovery Approach | |------|-------------------| | **Express** | Auto-derive from BRD. Ask only if critical info missing. Conservative defaults. | | **Standard** | 5-7 questions across 2 rounds. Scale sizing + constraints. Fitness-derived architecture. | | **Thorough** | 12-15 questions across 4 structured rounds. Full capacity planning. Trade-off analysis. Architecture alternatives. | | **Meticulous** | Everything in Thorough + individual ADR approval, tech stack walkthrough, capacity modeling with cost estimates. | ## Progress Output Follow `Claude-Production-Grade-Suite/.protocols/visual-identity.md`. Print structured progress throughout execution. **Skill header** (print on start): ``` ━━━ Solution Architect ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` **Phase progress** (print during execution): ``` [1/5] Constraint Discovery ✓ Scale: {users}, {CCU}, {constraints} ⧖ analyzing compliance requirements... ○ fitness function [2/5] Architecture Design ✓ Pattern: {pattern}, {N} ADRs ⧖ generating system diagrams... ○ user review [3/5] API Contracts ✓ {N} OpenAPI specs, {M} endpoints ⧖ defining error schemas... ○ versioning strategy [4/5] Data Model ✓ ERD: {N} entities, {M} migrations ⧖ writing migration files... ○ audit trail schema [5/5] Scaffold ✓ Project structure generated ⧖ writing Dockerfiles... ○ docker-compose ``` **Completion summary** (print on finish — MUST include concrete numbers): ``` ✓ Solution Architect {pattern}, {N} ADRs, {M} endpoints, scaffold generated ⏱ Xm Ys ``` ## Overview Full architecture pipeline: from business requirements to a scaffolded, production-ready codebase. The architecture is DERIVED from project constraints (scale, team, budget, compliance) — not picked from a template. There is no one-size-fits-all architecture. Generates architecture deliverables at the project root (`api/`, `schemas/`, `docs/architecture/`, project scaffold) with workspace artifacts in `Claude-Production-Grade-Suite/solution-architect/`. ## Config Paths Read `.production-grade.yaml` at startup. Use these overrides if defined: - `paths.api_contracts` — default: `api/` - `paths.adrs` — default: `docs/architecture/architecture-decision-records/` - `paths.architecture_docs` — default: `docs/architecture/` - `paths.erd` — default: `schemas/erd.md` - `paths.migrations` — default: `schemas/migrations/` - `paths.tech_stack` — default: `docs/architecture/tech-stack.md` Deliverables go to the **project root** (`api/`, `schemas/`, `docs/architecture/`). Workspace artifacts go to `Claude-Production-Grade-Suite/solution-architect/`. ## When to Use - Designing a new SaaS product or platform - Planning microservices or service-oriented architecture - Selecting tech stacks for production systems - Creating API contracts and data models - Scaffolding multi-cloud, production-grade projects - Architecture review or modernization of existing systems ## Process Flow ```dot digraph sa { rankdir=TB; "Triggered" [shape=doublecircle]; "Phase 1: Discovery" [shape=box]; "Phase 2: Architecture Design" [shape=box]; "Phase 3: Tech Stack" [shape=box]; "Phase 4: API Contracts" [shape=box]; "Phase 5: Data Models" [shape=box]; "Phase 6: Scaffold" [shape=box]; "User Review" [shape=diamond]; "Suite Complete" [shape=doublecircle]; "Triggered" -> "Phase 1: Discovery"; "Phase 1: Discovery" -> "Phase 2: Architecture Design"; "Phase 2: Architecture Design" -> "User Review"; "User Review" -> "Phase 2: Architecture Design" [label="revise"]; "User Review" -> "Phase 3: Tech Stack" [label="approved"]; "Phase 3: Tech Stack" -> "Phase 4: API Contracts"; "Phase 4: API Contracts" -> "Phase 5: Data Models"; "Phase 5: Data Models" -> "Phase 6: Scaffold"; "Phase 6: Scaffold" -> "Suite Complete"; } ``` ## Phase 1: Discovery & Scale Assessment The architecture must fit the project's actual constraints. This phase gathers those constraints — at a depth matching the engagement mode. ### Step 1: Read Existing Context Before asking ANY questions, read in parallel: 1. `Claude-Production-Grade-Suite/polymath/handoff/context-package.md` — may contain scale, constraints, decisions 2. `Claude-Production-Grade-Suite/product-manager/BRD/brd.md` — user stories, acceptance criteria, business rules 3. `Claude-Production-Grade-Suite/.orchestrator/codebase-context.md` — brownfield context **Reduce questions to cover ONLY gaps not addressed in existing context.** If polymath or PM already established scale targets, do not re-ask. ### Step 2: Scale & Fitness Interview Adapt depth to engagement mode. Use AskUserQuestion with structured options (never open-ended). #### Express Mode Skip interview entirely. Auto-derive from BRD signals: - User count hints from user stories -> default to "small" (< 1K users) if no signals - Tech mentions in BRD or polymath context -> use those, else conservative defaults - Default: modular monolith, managed services, single region, single DB - Log: `✓ Express mode — auto-deriving architecture from BRD` If a critical constraint is completely missing (e.g., BRD mentions "enterprise customers" but no scale number), ask ONE clarifying question maximum. #### Standard Mode (2 rounds) **Round 1 — Scale & Users:** ```python <!-- v0.1: render numbered options as plain Markdown; parse reply --> AskUserQuestion(questions=[{ "question": "I need to understand your scale to design the right architecture.\n\n" "These 3 questions determine whether you need a simple monolith or a distributed system.", "header": "Scale & Users", "options": [ {"label": "Small scale — < 1K users, MVP or internal tool", "description": "Simple architecture, minimal infra, fast to build"}, {"label": "Medium scale — 1K-100K users, startup/growth", "description": "Needs to scale but not from day 1. Service extraction plan."}, {"label": "Large scale — 100K+ users, high availability", "description": "Distributed architecture, multi-region, serious infrastructure"}, {"label": "Not sure — help me estimate", "description": "I'll ask a few questions to figure this out"}, {"label": "Chat about this", "description": "Free-form input"} ], "multiSelect": false }]) ``` Follow up with: ```python <!-- v0.1: render numbered options as plain Markdown; parse reply --> AskUserQuestion(questions=[{ "question": "What's the primary data pattern?", "header": "Data Characteristics", "options": [ {"label": "Read-heavy — dashboards, content, catalogs", "description": "Cache-first, read replicas, CDN"}, {"label": "Write-heavy — logging, IoT, transactions", "description": "Queue-based, event sourcing, eventual consistency"}, {"label": "Balanced — typical CRUD SaaS", "description": "Standard request/response, relational DB"}, {"label": "Real-time — chat, collaboration, live updates", "description": "WebSocket/SSE, pub/sub, in-memory state"}, {"label": "Chat about this", "description": "Free-form input"} ], "multiSelect": false }]) ``` **Round 2 — Constraints:** ```python <!-- v0.1: render numbered options as plain Markdown; parse reply --> AskUserQuestion(questions=[{ "question": "Who will build and maintain this system?", "header": "Team & Budget", "options": [ {"label": "Solo or pair — keep it simple", "description": "Monolith, managed services, minimal ops"}, {"label": "Small team (3-5) — some specialization", "description": "Can handle moderate complexity"}, {"label": "Medium team (6-15) — dedicated roles", "description": "Can support microservices if needed"}, {"label": "Large team (15+) — multiple squads", "description": "Service ownership model, independent deploys"}, {"label": "Chat about this", "description": "Free-form input"} ], "multiSelect": false }]) ``` ```python <!-- v0.1: render numbered options as plain Markdown; parse reply --> AskUserQuestion(questions=[{ "question": "Any hard constraints?", "header": "Compliance & Deployment", "options": [ {"label": "No special requirements", "description": "Standard web app, no regulatory burden"}, {"label": "GDPR — EU user data", "description": "Data residency, right to deletion, consent management"}, {"label": "SOC2 / ISO 27001 — enterprise customers", "description": "Audit trails, access controls, security policies"}, {"label": "HIPAA — health data", "description": "BAA required, encryption everywhere, dedicated tenancy"}, {"label": "PCI DSS — payment data", "description": "Tokenization, network segmentation, quarterly scans"}, {"label": "Multiple / Other (specify)", "description": "Select to describe your requirements"}, {"label": "Chat about this", "description": "Free-form input"}