Architecture Ref

Reference: Architecture & Patterns

Quick reference for project architecture conventions. Auto-loaded for structural decisions.

Step 1: Detect Project Architecture

Read .claude/project.config.json and scan src/ structure to identify the pattern in use:

Common Patterns

Detection Logic

Glob: src/**/

• If src/{name}/{name}.controller.* + src/{name}/{name}.service.* → Vertical Slicing
• If src/controllers/ + src/services/ + src/models/ → Layered
• If src/features/{name}/ → Feature-based
• If src/domain/ + src/application/ + src/infrastructure/ → DDD

Step 2: Apply Architectural Rules

Vertical Slicing Structure

src/
├── {domain}/                     # Business domain
│   ├── {slice}/                  # One slice per use case
│   │   ├── {slice}.controller.*
│   │   ├── {slice}.service.*
│   │   ├── {slice}.dto.*
│   │   ├── {slice}.spec.*
│   │   └── anatomy.md           # Slice documentation
│   │
│   ├── domain/                   # Domain entities and contracts
│   │   ├── {entity}.entity.*
│   │   └── {entity}.repository.* # Interface
│   │
│   └── {domain}.module.*         # Domain module
│
└── shared/                       # Cross-cutting concerns
    ├── database/
    ├── guards/
    ├── decorators/
    └── utils/

Layered Structure

src/
├── controllers/                  # HTTP layer
├── services/                     # Business logic
├── models/                       # Data models
├── middleware/                    # Request pipeline
├── utils/                        # Shared utilities
└── config/                       # Configuration

Feature-based Structure (Frontend)

src/
├── features/                     # Business domains
│   └── {domain}/
│       ├── {slice}/
│       │   ├── {Slice}Page.*
│       │   ├── {Component}.*
│       │   ├── use{Hook}.*
│       │   ├── {slice}.schema.*
│       │   └── index.*
│       └── shared/               # Domain-shared components
│
├── shared/                       # Cross-cutting
│   ├── components/
│   ├── lib/
│   ├── hooks/
│   └── types/
│
└── app/                          # Routing / entry point

Dependency Rules

ALLOWED:
- /{domainA}/ can import from /shared/
- /{domainA}/{slice}/ can import from /{domainA}/domain/
- /{domainA}/ can import from /{domainB}/domain/ (interfaces only)

FORBIDDEN:
- /{domainA}/ CANNOT import from /{domainB}/{slice}/ (implementation)
- Slices CANNOT import from other slices in the same domain
- /shared/ NEVER imports from domains

FLOW:
Slices → Domain → Shared

File Size Limits

Pattern Consistency Rule

ONE pattern per area. Do not mix competing solutions.

Once chosen, prohibit alternatives in the same area. Document the chosen pattern and why.

Slice Documentation (anatomy.md)

Each new feature/slice SHOULD include an anatomy.md:

# Anatomy: {Slice Name}

> **Domain**: {domain name}
> **Type**: {CRUD | Process | Query | Integration}

## Purpose
{What business problem this solves}

## Data Flow
{ASCII diagram or description}

## Business Rules
{List of rules}

## File Structure
| File | Responsibility |
|------|---------------|
| `{slice}.controller.*` | HTTP handling |
| `{slice}.service.*` | Business logic |
| `{slice}.dto.*` | Input/output shapes |
| `{slice}.spec.*` | Tests |

References

• Project config: .claude/project.config.json
• Architecture docs: docs/architecture.md
• MANUAL: .claude/MANUAL.md

Converted and distributed by TomeVault — claim your Tome and manage your conversions.