Architect

Architect — System Architecture & Technical Decisions

Purpose

This skill performs Phase 3 of the Dev Design SkillSet pipeline. It takes gatekeeper-design-approved requirements (from researcher) and project plan (from planner) and produces the complete system architecture: C4 diagrams, Arc42 documentation, Architecture Decision Records, API contracts, data model, deployment topology, and the authoritative backend/​runtime stack lock that downstream phases must inherit.

When to Activate

Activate when commander delegates Phase 3 (Architecture) after the researcher's requirements and planner's project plan have been approved by gatekeeper-design, or when a user directly requests a system architecture, C4 diagrams, ADRs, API contracts, or a backend/​runtime stack recommendation.

---

Execution Modes

Pipeline Mode (Commander-Delegated)

In pipeline mode delegated by commander, do NOT submit to gatekeeper-design yourself. Produce the deliverables plus a gatekeeper-ready review packet and return both to commander. Commander owns the review cycle.

Standalone Mode (Direct User Activation)

When activated directly by a user, this skill owns the final review loop for its own deliverables. Produce the architecture package, submit it to gatekeeper-design, address any REVISE findings, and return the approved result plus the final review report.

---

Workflow

Step 1: Architecture Style Selection

Based on the requirements and domain analysis, select the primary architecture style. Document the decision as ADR-001.

Consult references/​architecture-patterns.md for detailed pattern descriptions.

Step 2: Lock Backend Stack Template

Select the backend/​runtime overlay from the sibling skills-root library at ../​tech-stacks/. The selected overlay becomes the Backend Stack Lock for the rest of the pipeline.

Choose exactly one backend overlay file:

• ../​tech-stacks/​node-typescript.md
• ../​tech-stacks/​bun-typescript.md
• ../​tech-stacks/​deno-typescript.md
• ../​tech-stacks/​python-fastapi.md
• ../​tech-stacks/​rust-axum.md
• ../​tech-stacks/​go-gin.md
• ../​tech-stacks/​dotnet-aspnet.md

Document the lock as a dedicated section containing:

• Overlay file name
• Runtime/​framework/​database/​validation version tuple
• Decision drivers and rationale
• Constraints inherited from researcher/​planner
• Explicit deviations from the overlay, each justified and cross-linked to an ADR

Do not leave the stack implicit in ADRs alone. The backend stack lock is a first-class deliverable that downstream phases must inherit.

Step 3: Create C4 Diagrams

Produce diagrams at three levels using Mermaid DSL:

Level 1 — System Context: Shows the system as a box surrounded by users and external systems. Answers: "What does the system do and who interacts with it?"

Level 2 — Container: Shows the high-level technical building blocks (web app, API, database, message queue). Answers: "What are the main technical components and how do they communicate?"

Level 3 — Component: For complex containers, shows the internal components and their responsibilities. Answers: "How is this container organized internally?"

Do NOT create Level 4 (Code) diagrams manually — use IDE tools on demand.

C4Context
    title System Context Diagram

    Person(user, "End User", "Uses the application")
    System(system, "Application", "Core system being designed")
    System_Ext(payment, "Payment Gateway", "Processes payments")
    System_Ext(email, "Email Service", "Sends notifications")

    Rel(user, system, "Uses", "HTTPS")
    Rel(system, payment, "Processes payments", "HTTPS/​REST")
    Rel(system, email, "Sends emails", "SMTP/​API")

Step 4: Produce Arc42 Architecture Document

Follow the Arc42 v9.0 template structure. The document MUST include:

1. Introduction and Goals — Business requirements, quality goals, stakeholders
2. Constraints — Technical, organizational, and regulatory constraints
3. Context and Scope — System context diagram (C4 Level 1), external interfaces
4. Solution Strategy — Fundamental technology decisions and approaches
5. Building Block View — Container and component diagrams (C4 Level 2-3)
6. Runtime View — Key sequence diagrams for critical flows
7. Deployment View — Infrastructure topology, environments
8. Crosscutting Concepts — Security, logging, configuration, error handling, i18n
9. Architecture Decisions — Index of ADRs
10. Quality Requirements — Quality tree mapping NFRs to architecture tactics
11. Risks and Technical Debt — Known risks and accepted debt
12. Glossary — Domain terms (from researcher's ubiquitous language)

Consult references/​arc42-template.md for the complete template.

Step 5: Write Architecture Decision Records

For every significant technical decision, create an ADR using MADR v4.0:

---
status: "{Proposed | Accepted | Deprecated | Superseded by ADR-XXXX}"
date: YYYY-MM-DD
decision-makers: [list]
---

# ADR-XXXX: [Short Title]

## Context and Problem Statement
[What is the technical problem or decision point?]

## Decision Drivers
- [Driver 1]
- [Driver 2]

## Considered Options
1. [Option A]
2. [Option B]
3. [Option C]

## Decision Outcome
Chosen option: "[Option]", because [justification].

### Consequences
- Good: [Positive consequence]
- Bad: [Trade-off accepted]
- Neutral: [Side effect]

## Pros and Cons of Options

### [Option A]
- Good: [Pro]
- Bad: [Con]

### [Option B]
- Good: [Pro]
- Bad: [Con]

Step 6: Define API Contracts

Produce API contract specifications:

• REST APIs: OpenAPI 3.1 specification
• Event-driven APIs: AsyncAPI 3.0 specification
• Internal service-to-service: gRPC with Protocol Buffers or tRPC
• GraphQL: Schema definition (if applicable)

API contracts MUST define: endpoints, request/​response schemas, error formats (RFC 7807), authentication requirements, rate limits, and versioning strategy.

Step 7: Design Data Model

Produce the logical data model:

• Entity-relationship diagrams (Mermaid ERD)
• Key entity definitions with attributes, types, and constraints
• Relationships and cardinality
• Data flow across bounded contexts
• Migration strategy and rollback plan
• Data retention and privacy (GDPR/​regulatory compliance)

Step 8: Define Deployment Topology

Specify the infrastructure architecture:

• Environment list (dev, staging, production)
• Container orchestration (Kubernetes, ECS, serverless)
• CDN and edge computing strategy
• Database hosting and replication
• Secrets management approach
• Disaster recovery and backup strategy

Step 9: Prepare Review Handoff

Package the complete architecture document (Arc42), C4 diagrams, ADRs, API contracts, data model, deployment topology notes, and Backend Stack Lock with a review packet containing:

• Source skill: architect
• Deliverables produced
• Approved upstream context used
• Backend Stack Lock summary, including overlay file and version tuple
• Any approved deviations or unresolved exceptions

If operating in pipeline mode, return the deliverables and review packet to commander for gatekeeper submission.

If operating in standalone mode, submit the deliverables and review packet to gatekeeper-design, address any REVISE findings, and resubmit until APPROVED.

---

Output Format

The architect produces:

1. Architecture Document (Arc42 format) with embedded C4 diagrams
2. ADR Collection — One ADR per significant decision
3. API Contracts — OpenAPI/​AsyncAPI specifications
4. Data Model — ERD with entity definitions
5. Backend Stack Lock — Exact ../​tech-stacks/​*.md overlay selection, version tuple, and justified deviations

In pipeline mode, return the deliverables with a gatekeeper-ready review packet.

In standalone mode, return the approved deliverables plus the final gatekeeper-design review report.

---

Additional Resources

Reference Files

For detailed templates and pattern descriptions:

• references/​arc42-template.md — Complete Arc42 v9.0 template adapted for AI-driven workflows
• references/​architecture-patterns.md — Clean Architecture, Hexagonal, Event-Driven, CQRS, and microservices pattern details