---
name: architecture-proposal
description: Creates an upfront system architecture proposal before implementation begins. Defines bounded contexts, layer strategy, system-wide patterns, and quality attributes — the architectural foundation that all feature-level design decisions build on.
metadata:
  author: janmarkuslanger
  version: "1.0"
---

# Architecture Proposal

When this skill is activated, produce a `SYSTEM_DESIGN.md` that defines the architecture of a system *before* implementation begins. This is not a retrospective documentation — it is a forward-looking architectural blueprint that guides all subsequent design and implementation decisions.

## Clarifying Questions

Before writing the system design, ask the engineer the following questions. Skip any already clearly answered in the conversation. **Wait for the answers before proceeding.**

1. What is the system's primary purpose? What problem does it solve, and for whom?
2. What are the 3–5 most important use cases or workflows the system must support?
3. What quality attributes matter most — e.g. testability, scalability, availability, security, maintainability? Rank the top 3.
4. What are the technical constraints? (existing stack, required frameworks, deployment target, team expertise)
5. What is the expected scale? (approximate requests/day, data volume, number of engineers maintaining it)
6. Are there any architectural patterns already decided upon or explicitly ruled out?
7. What is the biggest unknown or risk in this system right now — what keeps you up at night architecturally?
8. Is this greenfield, or does an existing codebase need to be evolved toward this design?

## Steps

1. Use the answers above as the primary input; supplement with codebase exploration if an existing system was mentioned
2. Identify the major domains and bounded contexts
3. Define the layering strategy and how layers relate to each other
4. Choose system-wide architectural patterns and justify them
5. Define quality attributes and how the architecture serves them
6. Identify the highest architectural risks and how they are mitigated

## Output

Write a file called `SYSTEM_DESIGN.md` in the project root with the following sections:

### 1. System Purpose
One paragraph: what does this system do, for whom, and what makes it non-trivial to build? This is the architectural forcing function — the reason the design decisions below exist.

### 2. Bounded Contexts
Identify the major domains and their boundaries. For each bounded context:
- **Name**
- **Responsibility**: what this context owns
- **Core concepts**: the key domain objects that live here
- **Boundary**: what this context does NOT own (explicit exclusion prevents boundary drift)

Include a Mermaid diagram showing all bounded contexts and how they communicate:

```mermaid
graph TD
    subgraph Ordering
        A[Order]
        B[OrderLine]
    end
    subgraph Inventory
        C[Product]
        D[Stock]
    end
    subgraph Payment
        E[Transaction]
    end
    Ordering -->|reserve stock via event| Inventory
    Ordering -->|initiate payment via API| Payment
```

Use edge labels to show the communication style: `via event`, `via API`, `via shared DB`, `direct call`.

### 3. Layer Strategy
Define the layers of the system and the dependency rules between them:

| Layer | Responsibility | May depend on | Must NOT depend on |
|-------|---------------|---------------|-------------------|
| Presentation | HTTP, CLI, UI | Application | Domain, Infrastructure |
| Application | Use case orchestration | Domain | Infrastructure (via interface) |
| Domain | Business logic, rules | — | Everything else |
| Infrastructure | DB, external APIs, messaging | Domain interfaces | Application, Presentation |

Explain any deviations from standard layering and why they are justified.

### 4. Architectural Patterns
List the system-wide patterns chosen and the rationale for each:

| Pattern | Where applied | Why |
|---------|--------------|-----|
| Repository pattern | All DB access | Decouples domain from persistence technology |
| Domain events | Cross-context communication | Avoids direct coupling between bounded contexts |

For each pattern: what problem it solves, what it costs (complexity, indirection), and under what circumstances it would be the wrong choice.

### 5. Quality Attributes
For each quality attribute that meaningfully shapes architectural decisions:

**{Attribute}** (e.g. Testability, Scalability, Maintainability, Security)
- **Requirement**: what level is needed and why
- **Architectural decision**: what in the design serves this attribute
- **Trade-off**: what this decision costs in other dimensions

### 6. Cross-Cutting Concerns
How are these handled system-wide:
- **Error handling**: strategy and boundaries
- **Logging & observability**: what gets logged, at which layer, in which format
- **Authentication & authorization**: where enforced, how propagated
- **Configuration**: how environment-specific config is managed

### 7. Architectural Risks
The top risks that could invalidate or significantly complicate this architecture:

| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| Domain model too anemic, logic leaks into application layer | Medium | High | Enforce domain logic review in PRs; no setters in domain objects |

### 8. What This Architecture Forbids
Explicit constraints — things that must never happen regardless of convenience:
- Examples: "Domain objects must never import infrastructure packages", "No business logic in HTTP handlers", "No direct DB access outside the repository layer"

These constraints are the architecture's invariants. Violating them means the architecture no longer applies.

## Rules

- Write this before any significant implementation — it loses value as a post-hoc document
- Every decision must be justified; "we will use clean architecture" is not a decision, "we will use clean architecture because our domain logic must remain testable without a running database" is
- Be explicit about what the architecture forbids — constraints are as important as choices
- If a `DESIGN.md` exists for a specific feature, it must operate within the boundaries defined here
- Keep it short enough to be read before starting work — this is a compass, not a specification
- Revisit and update this document when a significant architectural decision changes; a stale system design is worse than none