Architect

Your principal architect — designs complete systems, not just suggests them

What it does

Give it a repo or a plain-English idea and get back a full architecture suite: C4 Mermaid diagrams, Architecture Decision Records, OpenAPI 3.0 spec, database ERD, deployment topology, and security threat model. Reads the existing codebase first so designs are grounded in reality, not theory. Every tech choice names the alternative it rejected and explains why.

What it can do

Codebase Discovery Before Any Design

Before writing a single design decision, reads the existing repository — file tree, key config files (package.json, Dockerfile, CI workflows), commit history, branch topology, open PRs, and current issues. Builds a real picture of what exists, what patterns the team uses, and what technical debt is present. New designs are grounded in what's actually there, not invented from scratch.

“Document the architecture of this existing system so new engineers can understand it”
“Read our codebase and tell me what architectural problems you see before we start the redesign”
“Map what we've built so far and identify where the seams should be for a microservices split”

Full 8-Document Architecture Suite

Produces 8 interconnected architecture documents every single time: system overview with Mermaid C4 diagrams, three Architecture Decision Records, a complete OpenAPI 3.0 spec, database ERD, infrastructure deployment plan, and a security threat model. Everything lands in docs/architecture/ on a new branch and arrives as a GitHub PR for team review and inline comments.

“Design the complete architecture for a multi-tenant SaaS billing platform”
“Plan the architecture for a real-time collaboration tool with 50K concurrent users”
“Design a marketplace platform — buyers, sellers, listings, payments, reviews”

Architecture Decision Records (ADRs)

Every significant technical choice gets a formal ADR with five required sections: Context (why this decision was needed), Decision (what was chosen), Rationale (why this over the named alternatives — "PostgreSQL over MongoDB because this data is highly relational"), Trade-offs (what is given up, honestly), and Consequences (what the team must do as a result). No unexplained choices.

“Create ADRs for all the tech decisions in our current system — nobody documented the why”
“Write an ADR for the GraphQL vs REST decision for our new public API”
“Document the architectural decision to go microservices vs modular monolith”

Mermaid Diagrams Throughout

Generates C4 context diagrams (system + external actors + third-party services), C4 component diagrams (internal services and their connections), sequence diagrams for critical user journeys (auth flows, payment processing, data sync), and ER diagrams for the database — all embedded as Mermaid in Markdown so they render directly on GitHub and in any Markdown viewer. No external diagramming tools required.

“Create a C4 diagram suite for our platform so we can explain it to investors”
“Draw the OAuth2 auth flow as a sequence diagram including refresh token rotation”
“Generate an ER diagram for our current database so we can plan the next major migration”

Complete OpenAPI 3.0 Specification

Produces a full OpenAPI 3.0.3 YAML specification for every API endpoint — request bodies with schemas, response shapes for all status codes, auth requirements (Bearer JWT defined in securitySchemes), error codes, and example values on every field. Complete enough to generate a typed client SDK with no additional information. Used as the direct input contract for the Code Generator agent.

“Design and spec the API for a marketplace — products, orders, sellers, payments, webhooks”
“Write an OpenAPI spec for our internal data service so frontend can generate a typed client”
“Spec the webhook API for our integration platform — all event types, payloads, retry semantics”

Security Architecture & Threat Modeling

Names specific adversaries and concrete attack scenarios — not generic category labels. Designs authentication and authorization with specific flows, token lifetimes, and rotation strategy. Classifies data sensitivity (PII, secrets, sensitive business data) field by field. Defines network security boundaries: what is internet-facing, what is internal-only, what can talk to what. Every security-sensitive API endpoint is documented with its exact auth requirement.

“Design the security architecture for a fintech app handling payment and KYC data”
“Threat model our current API — we're starting a SOC 2 Type II audit next quarter”
“Design the auth system for a multi-tenant SaaS: roles, per-org permissions, API key management”

Good for / not for

Great for

Starting a new product or service from a blank page
Documenting an existing system that nobody fully understands
Planning a major refactor, rewrite, or microservices migration
Technical due diligence — acquisition review, security audit preparation
Onboarding new senior engineers to a complex codebase
Creating the input spec for the Code Generator agent in the Software Factory pipeline
Justifying architectural choices to stakeholders, investors, or compliance reviewers

Not the right fit for

Small scripts, single-file utilities, or quick prototypes that don't need architecture docs
Hotfixes that need immediate code — not a document
Architectures requiring deep domain expertise the agent wasn't briefed on (ML model selection, medical device firmware)
Real-time operational decisions during an incident

Example tasks

“Design the complete architecture for a multi-tenant SaaS: schema, API spec, auth model, deployment plan, and ADRs for every major decision”
“Read our existing codebase and document the architecture — I need Mermaid diagrams, ADRs, and a security threat model”
“Plan our Rails monolith-to-microservices migration: identify service boundaries, spec each service's API, and document the phased rollout”
“Design the data model and OpenAPI spec for a real-time collaboration platform targeting 50K concurrent users”
“Threat model our fintech API and design the auth system: OAuth2 flows, token rotation, role-based access, PII data classification”