# Architecture
<!-- Inspired by matklad's ARCHITECTURE.md pattern.
     https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html

     Purpose: Give new contributors (human or AI) a high-level map of the system.
     Keep this document honest -- update it when the architecture changes.
     If a section no longer reflects reality, fix the doc or fix the code.
-->

## High-Level Overview

[PROJECT_NAME] is a [SYSTEM_TYPE -- e.g., "request-response web application",
"event-driven microservice", "CLI tool with plugin architecture"].

```
[ASCII DIAGRAM -- Replace with your own. Example:]

┌──────────┐     ┌──────────────┐     ┌────────────┐
│  Client  │────>│  API Gateway │────>│  Service A │──┐
└──────────┘     └──────────────┘     └────────────┘  │
                                      ┌────────────┐  │  ┌──────┐
                                      │  Service B │<─┘─>│  DB  │
                                      └────────────┘     └──────┘
```

[2-3 SENTENCES describing the overall architecture approach and key design
decisions -- e.g., "The system follows a modular monolith pattern with strict
module boundaries enforced by linting. Communication between modules happens
through a shared event bus, never direct imports."]

## Domain Structure

<!-- List the major domain areas / bounded contexts / modules. -->

### [DOMAIN_1 -- e.g., "Billing"]
- **Location**: `[PATH -- e.g., src/modules/billing/]`
- **Responsibility**: [WHAT_IT_DOES -- e.g., "Manages subscriptions, invoices, and payment processing"]
- **Key types**: `[TYPE_1]`, `[TYPE_2]`, `[TYPE_3]`
- **External dependencies**: [DEPS -- e.g., "Azure Service Bus via src/Project.Infrastructure/Messaging/"]

### [DOMAIN_2 -- e.g., "Identity"]
- **Location**: `[PATH]`
- **Responsibility**: [WHAT_IT_DOES]
- **Key types**: `[TYPE_1]`, `[TYPE_2]`
- **External dependencies**: [DEPS]

### [DOMAIN_3 -- e.g., "Workspace"]
- **Location**: `[PATH]`
- **Responsibility**: [WHAT_IT_DOES]
- **Key types**: `[TYPE_1]`, `[TYPE_2]`
- **External dependencies**: [DEPS]

## Package Layering

<!-- Define the dependency rules between layers.
     The arrows show allowed dependency directions. -->

```
┌─────────────────────────────┐
│  Presentation / UI          │  React components, CLI handlers, API routes
├─────────────────────────────┤
│  Application / Use Cases    │  Orchestration, commands, queries
├─────────────────────────────┤
│  Domain / Business Logic    │  Pure logic, no I/O, no framework deps
├─────────────────────────────┤
│  Infrastructure / Adapters  │  DB, HTTP clients, file system, queues
└─────────────────────────────┘
```

**Dependency rules:**
- Each layer may only depend on the layer directly below it.
- Domain layer has ZERO external dependencies (no ORM, no HTTP, no framework).
- Infrastructure implements interfaces defined in the Domain layer.
- [ADDITIONAL_RULE -- e.g., "Presentation may bypass Application for simple reads."]

## Cross-Cutting Concerns

### Authentication & Authorization
- [DESCRIPTION -- e.g., "JWT-based auth handled in middleware. Role-based access
  control checked via `authorize()` decorator on use case methods."]

### Logging & Observability
- [DESCRIPTION -- e.g., "Structured JSON logging via pino. Request ID propagated
  through AsyncLocalStorage. Traces exported to OpenTelemetry collector."]

### Error Handling
- [DESCRIPTION -- e.g., "Domain errors modeled as discriminated unions.
  Infrastructure errors wrapped in DomainError at the boundary.
  API layer maps DomainError variants to HTTP status codes."]

### Configuration
- [DESCRIPTION -- e.g., "Environment-based config loaded at startup via
  src/config.ts. Validated with zod schema. No process.env access outside
  this module."]

### Database & Migrations
- [DESCRIPTION -- e.g., "Azure SQL Database accessed via Entity Framework Core. Migrations in
  src/Project.Infrastructure/Migrations/. All queries scoped to tenant via global
  query filters."]

## Key Invariants

<!-- List the things that MUST always be true. These help agents avoid
     introducing subtle bugs. -->

1. [INVARIANT -- e.g., "Every database query MUST be scoped to a workspace ID.
   Unscoped queries will leak data across tenants."]
2. [INVARIANT -- e.g., "The domain layer MUST NOT import from any other layer.
   If you need I/O, define an interface and inject an implementation."]
3. [INVARIANT -- e.g., "All monetary amounts are stored as integers in cents.
   Never use floating-point for money."]
4. [INVARIANT -- e.g., "API responses MUST NOT include internal IDs. Use public
   UUIDs (the `publicId` field) in all external-facing payloads."]
5. [INVARIANT -- e.g., "Migrations MUST be backward-compatible. The old code
   must still work against the new schema during rolling deploys."]

## Entry Points

<!-- Where does execution start? Help agents find the "main" paths. -->

| Entry Point             | Path                          | Purpose                     |
|-------------------------|-------------------------------|-----------------------------|
| [ENTRY_1 -- e.g., Web]  | `[PATH -- e.g., src/app/]`   | [PURPOSE -- e.g., "Next.js pages and API routes"] |
| [ENTRY_2 -- e.g., CLI]  | `[PATH -- e.g., src/cli/]`   | [PURPOSE -- e.g., "Admin CLI commands"]           |
| [ENTRY_3 -- e.g., Worker] | `[PATH -- e.g., src/worker/]` | [PURPOSE -- e.g., "Background job processor"]   |
| [ENTRY_4 -- e.g., Migrations] | `[PATH]`               | [PURPOSE]                   |

## Diagrams & Further Reading

- [LINK -- e.g., "docs/adr/ -- Architecture Decision Records"]
- [LINK -- e.g., "docs/data-model.md -- Database schema documentation"]
- [LINK -- e.g., "docs/api.md -- API endpoint documentation"]