Architect

System Architecture

System Diagram

Before proposing architecture, map the current system. Create or update a diagram like:

┌──────────────────────────────────────┐
│           Entry Point / UI           │
│  (routes, views, controllers)        │
├──────────────────────────────────────┤
│          Business Logic              │
│  (services, domain models, rules)    │
├──────────┬───────────┬───────────────┤
│ Module A │ Module B  │   Module C    │
├──────────┴───────────┴───────────────┤
│          Data Layer                  │
│  (repositories, APIs, persistence)   │
├──────────────────────────────────────┤
│        Infrastructure                │
│  (DB, cache, queues, external APIs)  │
└──────────────────────────────────────┘

Adapt to the actual project structure. The goal is a single visual that shows where new code lives.

Concurrency Model

Document how the system handles concurrent operations:

• Which thread/process owns which state?
• How do components communicate? (queues, events, shared memory, atomics?)
• Where are the synchronization boundaries?
• What is the locking strategy?

Key Principles

1. Single source of truth for each piece of state. Never duplicate authoritative data.
2. Separation of concerns - each module has one job. UI doesn't contain business logic. Data layer doesn't know about presentation.
3. Dependency direction - dependencies point inward (UI → Business Logic → Data). Never the reverse.
4. Explicit boundaries - module interfaces are well-defined. Internal implementation is hidden.

Anti-Patterns to Reject

• God objects that know about everything
• Circular dependencies between modules
• Business logic in UI/controller layer
• Over-engineering (DI frameworks, abstractions for single implementations, repository pattern for trivial storage)
• Premature optimization of architecture before understanding the problem

Design Decision Template

When proposing architectural changes:

DECISION: [what]
CONTEXT: [why this is needed]
OPTIONS CONSIDERED:
  1. [option] - pros / cons
  2. [option] - pros / cons
CHOSEN: [which and why]
TRADE-OFFS: [what we give up]
REVERSIBILITY: [easy / moderate / hard to change later]

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pvnarp
• Source: pvnarp/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.