---

name: architecture description: Architecture principles for module boundaries, design patterns, and migration strategies user-invocable: false

Architecture Skill

Version: 2.0 Source: Architecture Principles

These guidelines are optional extensions to core standards. Use what fits your project's complexity.

---

North Star

Goal: Small changes stay local.

Definition: A typical feature should touch 1-2 modules, ship quickly, and not require coordinated edits across the system.

Smell: If you find yourself editing 5+ files across multiple layers for a simple change, that's a design smell.

---

Core Principles

1. Explicit Over Magic

Prefer readable wiring over convention-heavy frameworks. When someone reads your code, the control flow should be obvious.

Copy// ❌ Magic - What does this do?
@AutoInject()
class UserService {}

// ✅ Explicit - Control flow is clear
class UserService {
  constructor(
    private userRepository: UserRepository,
    private emailService: EmailService
  ) {}
}

2. Boundaries Are Sacred

Modules communicate only through contracts (APIs, props, events). No reaching into another module's internals.

Copy// ❌ Reaching into internals
const user = orderModule.database.users.find(id);

// ✅ Through the contract
const user = orderModule.getUserForOrder(orderId);

3. Own Your Data

Each module owns its schema/state. Other modules read via APIs or props, never direct access.

CopyUserModule owns: users table, user state
OrderModule owns: orders table, cart state

UserModule reads orders via: OrderModule.getOrdersForUser(userId)
OrderModule reads users via: UserModule.getUserById(userId)

4. Optimize for Refactoring

If code is hard to move or rename, it's a design smell. Loose coupling enables safe refactoring.

---

The 3 Layers

Copy01-presentation/  →  02-logic/  →  03-data/

Valid Dependency Flow

CopyPresentation → Logic → Data ✅
Data → Logic ❌ (blocked)
Logic → Presentation ❌ (blocked)

---

Folder Structure

Organize by Feature, Not Layer

Prefer:

Copysrc/
├── users/
│   ├── user.model.ts
│   ├── user.service.ts
│   └── user.controller.ts
├── orders/
│   └── ...
└── shared/
    └── utils/

Avoid:

Copysrc/
├── models/
│   ├── user.model.ts
│   └── order.model.ts
├── services/
│   └── ...

Why: Feature-based keeps related code together. When you work on "users," everything is in one place.

Depth Limit

Maximum 4 levels deep. If deeper, the structure is probably wrong.

---

Module Boundaries

What is a Module?

A cohesive unit with:

• Clear public API (exports)
• Hidden implementation (internals)
• Defined dependencies (imports)

Module Rules

Single Entry Point: Each module exposes its API through an index file.

Copyusers/
├── index.ts             # Public API
├── user.service.ts      # Internal
└── user.repository.ts   # Internal

No Reaching Into Modules:

Copy// ✅ Yes
import { UserService } from '@/users';

// ❌ No
import { UserService } from '@/users/user.service';

Coupling Guidelines

---

Testing Strategy

Guidance

• Heavy unit tests, moderate integration, minimal E2E
• E2E sprawl leads to brittle, slow test suites
• Contract tests recommended for API boundaries

---

Red Flags

Stop and reconsider when you see:

---

When to Extract

Start with a modular monolith (single deployable, clean internal boundaries).

Extract to separate services only when:

Don't extract for "cleanliness" — that adds operational complexity without benefit.

---

Observability Basics

Structured Logging

Copy// ❌ String concatenation
console.log('User ' + userId + ' logged in at ' + new Date());

// ✅ Structured JSON
logger.info('User logged in', { userId, timestamp: new Date() });

Correlation IDs

Track requests across async operations.

Error Boundaries

Catch and report, don't swallow silently.

---

Decision Records

For significant architectural choices, document:

1. Context: What problem are we solving?
2. Decision: What did we choose?
3. Alternatives: What else did we consider?
4. Consequences: What trade-offs are we accepting?

Location: Documentation/decisions/

---

Pattern Selection

Default to simplicity: Function → Module → Class → Pattern

---

Anti-Patterns

---

Scaling Principles

---

References

• references/design-patterns.md — Factory, Repository, Adapter, etc.
• references/migration-patterns.md — Strangler Fig, Branch by Abstraction, etc.
• references/module-boundaries.md — Detailed boundary guidelines

Assets

• assets/decision-record-template.md — ADR template
• assets/architecture-checklist.md — Full architecture review checklist

Scripts

• scripts/analyze_dependencies.py — Map circular dependencies and detect layer violations