# Architecture Decisions

## Key Design Choices

<!-- Captured from ADRs in .aiwg/architecture/ and code review discussions -->
<!-- Add [confidence: established|emerging|speculative] to each entry. See auto-memory overview for convention. -->

### [Decision Category]

**Decision**: <!-- What was decided --> [confidence: established — see ADR-XXX]
**Context**: <!-- Why the decision was needed -->
**Rationale**: <!-- Why this choice was made -->
**Alternatives Considered**: <!-- What else was evaluated -->
**Trade-offs**: <!-- Pros and cons of this choice -->
**Status**: <!-- Active, Superseded, Deprecated -->

<!-- Example of a well-annotated entry:
### Authentication Strategy

**Decision**: Use JWT RS256 for all service tokens. [confidence: established — see ADR-012]
**Context**: Needed stateless auth that works across microservices.
**Rationale**: RS256 lets services verify tokens without sharing a secret.
**Alternatives Considered**: HS256 (shared secret — rejected: key distribution problem), opaque tokens (rejected: requires DB lookup on every request).
**Trade-offs**: Token revocation requires a denylist or short expiry; accepted this for the stateless benefit.
**Status**: Active

### Session Caching

**Decision**: Consider Redis for session storage in web-facing services. [confidence: emerging — evaluated sprint 4, not yet in prod]
**Status**: Under evaluation
-->

---

## Architectural Patterns

### Overall Architecture

<!-- Learned from codebase structure and architecture documentation -->

**Style**: <!-- e.g., "Microservices", "Monolith", "Serverless", "Event-driven" -->
**Justification**: <!-- Why this architectural style -->

### Layer Organization

```
[Project Structure]
├── [Layer 1]     # Purpose
├── [Layer 2]     # Purpose
└── [Layer 3]     # Purpose
```

**Separation of Concerns**:
- <!-- e.g., "Domain logic isolated from infrastructure" -->
- <!-- e.g., "API layer separate from business logic" -->

### Communication Patterns

<!-- Learned from inter-component communication -->

**Internal Communication**:
- <!-- e.g., "Direct function calls within modules" -->
- <!-- e.g., "Event bus for cross-module communication" -->

**External Communication**:
- <!-- e.g., "REST APIs for client communication" -->
- <!-- e.g., "Message queue for async processing" -->

## Design Patterns Used

### Creational Patterns

<!-- Learned from object creation patterns in codebase -->

**Factory Pattern**: <!-- Where and why used -->
**Singleton Pattern**: <!-- Where and why used -->
**Builder Pattern**: <!-- Where and why used -->

### Structural Patterns

<!-- Learned from code organization -->

**Adapter Pattern**: <!-- Where and why used -->
**Decorator Pattern**: <!-- Where and why used -->
**Facade Pattern**: <!-- Where and why used -->

### Behavioral Patterns

<!-- Learned from runtime behavior -->

**Observer Pattern**: <!-- Where and why used -->
**Strategy Pattern**: <!-- Where and why used -->
**Command Pattern**: <!-- Where and why used -->

## Technology Stack

### Core Technologies

<!-- Learned from package.json, requirements.txt, go.mod, etc. -->

**Language**: <!-- e.g., "TypeScript 5.x" -->
**Runtime**: <!-- e.g., "Node.js 20.x" -->
**Framework**: <!-- e.g., "Express.js 4.x" -->

**Rationale**: <!-- Why these technologies were chosen -->

### Database

**Type**: <!-- e.g., "PostgreSQL 15" -->
**ORM/Query Builder**: <!-- e.g., "Prisma" or "raw SQL" -->
**Migration Strategy**: <!-- e.g., "Prisma Migrate" -->

**Rationale**: <!-- Why this database choice -->

### External Services

<!-- Learned from integrations -->

**Service**: <!-- e.g., "Stripe for payments" -->
**Purpose**: <!-- What it's used for -->
**Integration Pattern**: <!-- How it's integrated -->

## Code Organization Principles

### Module Structure

<!-- Learned from codebase organization -->

**Pattern**: <!-- e.g., "Feature-based modules" or "Layer-based" -->

```
src/
├── [module1]/
│   ├── [module1].controller.ts
│   ├── [module1].service.ts
│   ├── [module1].repository.ts
│   └── [module1].types.ts
```

**Rationale**: <!-- Why this organization -->

### Dependency Management

<!-- Learned from dependency injection patterns -->

**Pattern**: <!-- e.g., "Constructor injection" -->
**DI Container**: <!-- e.g., "InversifyJS" or "manual" -->
**Rationale**: <!-- Why this approach -->

### Interface Design

<!-- Learned from API and interface patterns -->

**Principle**: <!-- e.g., "Program to interfaces, not implementations" -->
**Convention**: <!-- e.g., "Interfaces in .types.ts files" -->

## Data Architecture

### Data Flow

<!-- Learned from data movement through system -->

```
[Source] → [Transform] → [Destination]
```

**Pattern**: <!-- e.g., "Request → Validation → Business Logic → Repository → Database" -->

### State Management

<!-- Learned from state handling patterns -->

**Client State**: <!-- How client state is managed -->
**Server State**: <!-- How server state is managed -->
**Cache Strategy**: <!-- How caching is implemented -->

### Data Validation

<!-- Learned from validation patterns -->

**Where**: <!-- e.g., "At API boundaries and database writes" -->
**How**: <!-- e.g., "Zod schemas for runtime validation" -->
**Strategy**: <!-- e.g., "Fail fast, validate early" -->

## Security Architecture

### Authentication

<!-- Learned from auth implementation -->

**Method**: <!-- e.g., "JWT tokens" -->
**Storage**: <!-- e.g., "HttpOnly cookies" -->
**Rotation**: <!-- e.g., "Refresh tokens with 7-day expiry" -->

### Authorization

<!-- Learned from access control patterns -->

**Model**: <!-- e.g., "Role-based access control (RBAC)" -->
**Implementation**: <!-- e.g., "Middleware checks roles on protected routes" -->

### Data Protection

<!-- Learned from security measures -->

**Encryption at Rest**: <!-- What's encrypted -->
**Encryption in Transit**: <!-- TLS configuration -->
**Secrets Management**: <!-- How secrets are stored -->

## Performance Architecture

### Caching Strategy

<!-- Learned from caching implementation -->

**What's Cached**: <!-- e.g., "API responses, database query results" -->
**Cache Store**: <!-- e.g., "Redis" -->
**Invalidation**: <!-- How cache is invalidated -->

### Optimization Patterns

<!-- Learned from performance improvements -->

**Database Optimization**:
- <!-- e.g., "Indexes on frequently queried columns" -->
- <!-- e.g., "Connection pooling with max 20 connections" -->

**API Optimization**:
- <!-- e.g., "Pagination for large result sets" -->
- <!-- e.g., "Response compression with gzip" -->

## Scalability Considerations

### Horizontal Scaling

<!-- Learned from scaling strategy -->

**Approach**: <!-- e.g., "Stateless application servers behind load balancer" -->
**Session Management**: <!-- e.g., "Redis for shared session storage" -->

### Vertical Scaling

<!-- Learned from resource allocation -->

**Limits**: <!-- e.g., "Single instance can handle 1000 req/s" -->
**Bottlenecks**: <!-- Known resource constraints -->

## Error Handling Architecture

### Error Propagation

<!-- Learned from error handling patterns -->

**Strategy**: <!-- e.g., "Errors bubble up, caught at controller layer" -->
**Custom Errors**: <!-- e.g., "Domain-specific error classes extend base Error" -->

### Logging Strategy

<!-- Learned from logging implementation -->

**Levels**: <!-- e.g., "error, warn, info, debug" -->
**Structure**: <!-- e.g., "Structured JSON logs" -->
**Aggregation**: <!-- e.g., "Logs sent to CloudWatch" -->

## Testing Architecture

### Test Pyramid

<!-- Learned from test organization -->

```
    /\     E2E Tests (few)
   /  \
  /----\   Integration Tests (moderate)
 /------\
/--------\ Unit Tests (many)
```

**Distribution**: <!-- e.g., "70% unit, 20% integration, 10% E2E" -->

### Test Isolation

<!-- Learned from test patterns -->

**Unit Tests**: <!-- e.g., "Isolated with mocks for dependencies" -->
**Integration Tests**: <!-- e.g., "Use test database, reset between tests" -->
**E2E Tests**: <!-- e.g., "Full stack with test database and seeded data" -->

## Deployment Architecture

### Environment Strategy

<!-- Learned from deployment configuration -->

**Environments**: <!-- e.g., "Development, Staging, Production" -->
**Promotion Path**: <!-- How code moves between environments -->

### Infrastructure

<!-- Learned from infrastructure setup -->

**Hosting**: <!-- e.g., "AWS ECS" -->
**Database**: <!-- e.g., "AWS RDS PostgreSQL" -->
**CDN**: <!-- e.g., "CloudFront" -->

### CI/CD Pipeline

<!-- Learned from CI/CD configuration -->

**Stages**: <!-- e.g., "Lint → Test → Build → Deploy" -->
**Tooling**: <!-- e.g., "GitHub Actions" -->

## Evolution and Technical Debt

### Known Technical Debt

<!-- Learned from code review and refactoring discussions -->

**Item**: <!-- What needs improvement -->
**Impact**: <!-- Why it matters -->
**Plan**: <!-- When/how to address -->

### Architectural Improvements

<!-- Planned or recent architectural changes -->

**Recent Changes**:
- <!-- e.g., "Migrated from REST to GraphQL for better client flexibility" -->

**Planned Changes**:
- <!-- e.g., "Planning to extract auth module into separate service" -->

## Decision Records

### ADR Index

<!-- Cross-reference to .aiwg/architecture/adrs/ -->

**ADR-001**: <!-- Title and link -->
**ADR-002**: <!-- Title and link -->

**Recent Decisions**: <!-- Highlight most relevant recent ADRs -->

## Cross-Cutting Concerns

### Observability

<!-- Learned from monitoring and observability setup -->

**Metrics**: <!-- What's measured -->
**Tracing**: <!-- How requests are traced -->
**Alerting**: <!-- What triggers alerts -->

### Configuration Management

<!-- Learned from config patterns -->

**Strategy**: <!-- e.g., "Environment variables for config" -->
**Validation**: <!-- e.g., "Config schema validated on startup" -->

### Feature Flags

<!-- Learned from feature flag usage -->

**System**: <!-- e.g., "LaunchDarkly" or "custom" -->
**Usage**: <!-- When feature flags are used -->

## Lessons Learned

### What Worked Well

<!-- Learned from successful architectural decisions -->

**Decision**: <!-- What was decided -->
**Outcome**: <!-- Positive results -->

### What Would Change

<!-- Learned from challenges or mistakes -->

**Decision**: <!-- What was decided -->
**Lesson**: <!-- What was learned -->
**Better Approach**: <!-- What would be done differently -->

## Continuous Learning

<!-- Track evolving architectural understanding -->

**Recent Insights**: <!-- e.g., "Discovered event sourcing pattern fits our audit requirements" -->
**Experiments**: <!-- e.g., "Trying CQRS for read/write separation" -->
**Pain Points**: <!-- e.g., "Current monolith makes feature isolation difficult" -->