Epic architecture specification
Transform an Epic PRD into a Markdown architecture specification that identifies the technical approach, system components, deployment shape, feature enablers, stack decisions, technical value, and delivery size without writing implementation code.
When to invoke
- "Create the architecture spec for this epic PRD."
- "Turn this Epic PRD into
/docs/ways-of-work/plan/{epic-name}/arch.md."
- "Design the high-level architecture for this SaaS epic."
- "Produce an epic architecture diagram and technical enablers."
Architecture context to preserve
| Input or assumption |
Required treatment |
| Epic PRD |
Treat it as the source of truth for goals, users, scope, and requirements. Call out gaps instead of inventing facts. |
| Domain-driven architecture |
Decompose by bounded context, capability, and module, not by generic layer names alone. |
| Self-hosted and SaaS deployment |
Explain whether each component works in both modes and what changes across tenants, networking, storage, and operations. |
| Docker containerization |
Model every deployable service as a container or explicitly justify why it is not containerized. |
| TypeScript/Next.js stack with App Router |
Place UI routes, server actions, API boundaries, and rendering responsibilities in the architecture; preserve the original TypeScript/Next.js stack shorthand where useful. |
| Turborepo monorepo patterns |
Show package boundaries, shared libraries, app packages, build orchestration, and dependency direction. |
| tRPC |
Use for type-safe internal API contracts when the epic needs app-to-server calls. |
| Stack Auth |
Put authentication and session/identity boundaries in the application layer. |
| n8n |
Include workflow engines only when asynchronous orchestration is part of the epic. |
| PostgreSQL, Qdrant, Redis |
Use PostgreSQL for relational state, Qdrant for vector search, and Redis for cache/queues only when the PRD justifies them. |
Do not write production code. Include pseudocode only when a technical situation cannot be explained clearly with prose, tables, or diagrams.
Specification sections
| Section |
Content to produce |
Quality bar |
| Epic Architecture Overview |
One concise summary of the technical approach. |
Names the dominant pattern, main components, and deployment model. |
| System Architecture Diagram |
A Mermaid diagram with User, Application, Service, Data, and Infrastructure layers. |
Shows synchronous request paths and asynchronous processing flows where relevant. |
| High-Level Features & Technical Enablers |
Feature list plus enablers such as services, libraries, queues, schemas, and infrastructure. |
Each enabler maps to at least one PRD requirement. |
| Technology Stack |
Key technologies, frameworks, and libraries. |
Distinguishes mandated stack from optional or conditional choices. |
| Technical Value |
High, Medium, or Low with justification. |
Ties value to scalability, maintainability, reliability, or speed of delivery. |
| T-Shirt Size Estimate |
S, M, L, or XL. |
Includes the primary size drivers and uncertainty. |
Diagram rules
Create one comprehensive Mermaid diagram. Use subgraphs for these layers:
| Layer |
Include |
| User Layer |
Web browsers, mobile apps, admin interfaces, and other user types from the PRD. |
| Application Layer |
Load balancers, Next.js application instances, Stack Auth, and edge/application boundaries. |
| Service Layer |
tRPC APIs, background services, n8n workflow engines, and epic-specific services. |
| Data Layer |
PostgreSQL, Qdrant, Redis, object stores, analytics stores, and external API integrations. |
| Infrastructure Layer |
Docker containers, deployment targets, networking, monitoring, and environment boundaries. |
Apply consistent labels for component types. Show data flow direction, distinguish sync calls from async events or jobs, and avoid decorative nodes that do not affect the design.
Output template
# <Epic Name> Architecture Specification
## 1. Epic Architecture Overview
<technical approach summary>
## 2. System Architecture Diagram
```mermaid
flowchart TD
subgraph User Layer
User[<user type>]
end
subgraph Application Layer
App[Next.js App Router]
Auth[Stack Auth]
end
subgraph Service Layer
API[tRPC API]
Worker[Background service or n8n workflow]
end
subgraph Data Layer
DB[(PostgreSQL)]
Cache[(Redis)]
Vector[(Qdrant)]
end
subgraph Infrastructure Layer
Docker[Docker containers]
end
User --> App --> Auth
App --> API --> DB
API -. async .-> Worker
```
## 3. High-Level Features & Technical Enablers
### Features
- <feature>
### Technical enablers
- <enabler> — supports <requirement>
## 4. Technology Stack
| Area | Choice | Rationale |
| --- | --- | --- |
| <area> | <technology> | <reason> |
## 5. Technical Value
**Value:** High | Medium | Low
**Justification:** <why>
## 6. T-Shirt Size Estimate
**Size:** S | M | L | XL
**Drivers:** <complexity drivers>
Quality gate
1---2name: breakdown-epic-arch3description: Create a high-level epic architecture specification from an Epic PRD, including system diagrams, technical enablers, stack choices, technical value, and t-shirt sizing. Use when asked to write an epic architecture spec, turn a PRD into architecture, or produce docs/ways-of-work arch.md.4---56<!-- Generated from harness/github-copilot/skills/breakdown-epic-arch/SKILL.md by harness/claude-code/scripts/convert_from_copilot.py. Edit the source, not this file. -->78# Epic architecture specification910Transform an Epic PRD into a Markdown architecture specification that identifies the technical approach, system components, deployment shape, feature enablers, stack decisions, technical value, and delivery size without writing implementation code.1112## When to invoke1314- "Create the architecture spec for this epic PRD."15- "Turn this Epic PRD into `/docs/ways-of-work/plan/{epic-name}/arch.md`."16- "Design the high-level architecture for this SaaS epic."17- "Produce an epic architecture diagram and technical enablers."1819## Architecture context to preserve2021| Input or assumption | Required treatment |22| --- | --- |23| Epic PRD | Treat it as the source of truth for goals, users, scope, and requirements. Call out gaps instead of inventing facts. |24| Domain-driven architecture | Decompose by bounded context, capability, and module, not by generic layer names alone. |25| Self-hosted and SaaS deployment | Explain whether each component works in both modes and what changes across tenants, networking, storage, and operations. |26| Docker containerization | Model every deployable service as a container or explicitly justify why it is not containerized. |27| TypeScript/Next.js stack with App Router | Place UI routes, server actions, API boundaries, and rendering responsibilities in the architecture; preserve the original **TypeScript/Next.js** stack shorthand where useful. |28| Turborepo monorepo patterns | Show package boundaries, shared libraries, app packages, build orchestration, and dependency direction. |29| tRPC | Use for type-safe internal API contracts when the epic needs app-to-server calls. |30| Stack Auth | Put authentication and session/identity boundaries in the application layer. |31| n8n | Include workflow engines only when asynchronous orchestration is part of the epic. |32| PostgreSQL, Qdrant, Redis | Use PostgreSQL for relational state, Qdrant for vector search, and Redis for cache/queues only when the PRD justifies them. |3334Do not write production code. Include pseudocode only when a technical situation cannot be explained clearly with prose, tables, or diagrams.3536## Specification sections3738| Section | Content to produce | Quality bar |39| --- | --- | --- |40| Epic Architecture Overview | One concise summary of the technical approach. | Names the dominant pattern, main components, and deployment model. |41| System Architecture Diagram | A Mermaid diagram with User, Application, Service, Data, and Infrastructure layers. | Shows synchronous request paths and asynchronous processing flows where relevant. |42| High-Level Features & Technical Enablers | Feature list plus enablers such as services, libraries, queues, schemas, and infrastructure. | Each enabler maps to at least one PRD requirement. |43| Technology Stack | Key technologies, frameworks, and libraries. | Distinguishes mandated stack from optional or conditional choices. |44| Technical Value | High, Medium, or Low with justification. | Ties value to scalability, maintainability, reliability, or speed of delivery. |45| T-Shirt Size Estimate | S, M, L, or XL. | Includes the primary size drivers and uncertainty. |4647## Diagram rules4849Create one comprehensive Mermaid diagram. Use subgraphs for these layers:5051| Layer | Include |52| --- | --- |53| User Layer | Web browsers, mobile apps, admin interfaces, and other user types from the PRD. |54| Application Layer | Load balancers, Next.js application instances, Stack Auth, and edge/application boundaries. |55| Service Layer | tRPC APIs, background services, n8n workflow engines, and epic-specific services. |56| Data Layer | PostgreSQL, Qdrant, Redis, object stores, analytics stores, and external API integrations. |57| Infrastructure Layer | Docker containers, deployment targets, networking, monitoring, and environment boundaries. |5859Apply consistent labels for component types. Show data flow direction, distinguish sync calls from async events or jobs, and avoid decorative nodes that do not affect the design.6061## Output template6263````markdown64# <Epic Name> Architecture Specification6566## 1. Epic Architecture Overview67<technical approach summary>6869## 2. System Architecture Diagram70```mermaid71flowchart TD72 subgraph User Layer73 User[<user type>]74 end75 subgraph Application Layer76 App[Next.js App Router]77 Auth[Stack Auth]78 end79 subgraph Service Layer80 API[tRPC API]81 Worker[Background service or n8n workflow]82 end83 subgraph Data Layer84 DB[(PostgreSQL)]85 Cache[(Redis)]86 Vector[(Qdrant)]87 end88 subgraph Infrastructure Layer89 Docker[Docker containers]90 end91 User --> App --> Auth92 App --> API --> DB93 API -. async .-> Worker94```9596## 3. High-Level Features & Technical Enablers97### Features98- <feature>99100### Technical enablers101- <enabler> — supports <requirement>102103## 4. Technology Stack104| Area | Choice | Rationale |105| --- | --- | --- |106| <area> | <technology> | <reason> |107108## 5. Technical Value109**Value:** High | Medium | Low110**Justification:** <why>111112## 6. T-Shirt Size Estimate113**Size:** S | M | L | XL114**Drivers:** <complexity drivers>115````116117## Quality gate118119- [ ] The output is suitable for `/docs/ways-of-work/plan/{epic-name}/arch.md`.120- [ ] Every major architecture decision traces back to the Epic PRD or is marked as an assumption.121- [ ] The Mermaid diagram includes User, Application, Service, Data, and Infrastructure layers.122- [ ] Stack Auth, Docker containerization, TypeScript/Next.js App Router, Turborepo, and tRPC are addressed when applicable.123- [ ] Self-hosted and SaaS deployment implications are explicit.124- [ ] No implementation code is included except necessary pseudocode.125- [ ] Technical value and t-shirt size are stated with justification.
paulasilvatech