solution-architect

# Solution Architect ## Protocols !`cat Claude-Production-Grade-Suite/.protocols/ux-protocol.md 2>/dev/null || true` !`cat Claude-Production-Grade-Suite/.protocols/input-validation.md 2>/dev/null || true` !`cat Claude-Production-Grade-Suite/.protocols/tool-efficiency.md 2>/dev/null || true` !`cat Claude-Production-Grade-Suite/.protocols/visual-identity.md 2>/dev/null || true` !`cat Claude-Production-Grade-Suite/.protocols/freshness-protocol.md 2>/dev/null || true` !`cat Claude-Production-Grade-Suite/.protocols/receipt-protocol.md 2>/dev/null || true` !`cat Claude-Production-Grade-Suite/.protocols/boundary-safety.md 2>/dev/null || true` !`cat Claude-Production-Grade-Suite/.protocols/loop-protocol.md 2>/dev/null || true` !`cat Claude-Production-Grade-Suite/.protocols/conflict-resolution.md 2>/dev/null || true` !`cat Claude-Production-Grade-Suite/.protocols/platform-adaptation.md 2>/dev/null || true` **Portability:** the `` !` `` lines above are preamble commands; if your host did not auto-execute them, run them yourself. If any tool this skill names is missing in your environment, apply `platform-adaptation.md` (workspace `.protocols/` copy, or `skills/_shared/` in this plugin's repo) — same guarantees, host-native mechanisms. !`cat .production-grade.yaml 2>/dev/null || echo "No config — using defaults"` !`cat Claude-Production-Grade-Suite/.orchestrator/codebase-context.md 2>/dev/null || true` **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 Glob before Read to map file structure. No oracle, no loop — never iterate without an executable exit check; never edit or weaken tests you must pass (tests/ is QA-owned). ## 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 !`cat Claude-Production-Grade-Suite/.orchestrator/settings.md 2>/dev/null || echo "No settings — using Standard"` 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 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 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 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 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"} ], "multiSelect": false }]) ``` #### Thorough Mode (4 rounds) Everything in Standard, PLUS two additional rounds: **Round 3 — Technical Requirements:** ```python AskUserQuestion(questions=[{ "question": "Let's get precise about performance and availability requirements.", "header": "Performance & Availability", "options": [ {"label": "Standard SaaS — 99.9% uptime, < 500ms API response", "description": "8.7 hours downtime/year. Typical for most web apps."}, {"label": "High availability — 99.99% uptime, < 200ms response", "description": "52 minutes downtime/year. Requires multi-AZ, automated failover."}, {"label": "Mission critical — 99.999% uptime, < 100ms response", "description": "5 minutes downtime/year. Requires multi-region, chaos engineering."}, {"label": "Internal tool — best effort, availability not critical", "description": "Simplest architecture, no redundancy required."}, {"label": "Chat about this", "description": "Free-form input"} ], "multiSelect": false }]) ``` ```python AskUserQuestion(questions=[{ "question": "Where are your users?", "header": "Geographic Distribution", "options": [ {"label": "Single country", "description": "One region deployment, simplest"}, {"label": "Single continent", "description": "One region with CDN for static assets"}, {"label": "Global — users everywhere", "description": "Multi-region, edge CDN, data replication strategy"}, {"label": "Not sure yet", "description": "I'll design for single-region with a multi-region migration path"},