project/
├── CLAUDE.md                    # Project-wide: tech stack, commands, conventions
└── src/
    └── domains/
        ├── auth/
        │   ├── CLAUDE.md        # Auth domain: purpose, contracts, invariants
        │   └── oauth2/
        │       └── CLAUDE.md    # OAuth2 subdomain (rare, only when needed)
        └── billing/
            └── CLAUDE.md        # Billing domain: purpose, contracts, invariants

# [Project Name]

Last verified: [DATE - use `date +%Y-%m-%d`]

## Tech Stack
- Language: TypeScript 5.x
- Framework: Next.js 14
- Database: PostgreSQL
- Testing: Vitest

## Commands
- `npm run dev` - Start dev server
- `npm run test` - Run tests
- `npm run build` - Production build

## Project Structure
- `src/domains/` - Domain modules (auth, billing, etc.)
- `src/shared/` - Cross-cutting utilities
- `src/infrastructure/` - External adapters (DB, APIs)

## Conventions
- Functional Core / Imperative Shell pattern
- Domain modules are self-contained
- See domain CLAUDE.md files for domain-specific guidance

## Boundaries
- Safe to edit: `src/`
- Never touch: `migrations/` (immutable), `*.lock` files

# [Domain Name]

Last verified: [DATE - use `date +%Y-%m-%d`]

## Purpose
[1-2 sentences: WHY this domain exists, what problem it solves]

## Contracts
- **Exposes**: [public interfaces - what callers can use]
- **Guarantees**: [promises this domain keeps]
- **Expects**: [what callers must provide]

## Dependencies
- **Uses**: [domains/services this depends on]
- **Used by**: [what depends on this domain]
- **Boundary**: [what should NOT be imported here]

## Key Decisions
- [Decision]: [Rationale]

## Invariants
- [Thing that must always be true]

## Key Files
- `index.ts` - Public exports
- `types.ts` - Domain types
- `service.ts` - Main service implementation

## Gotchas
- [Non-obvious thing that will bite you]

# Auth Domain

Last verified: 2025-12-17

## Purpose
Ensures user identity is verified exactly once at the system edge.
All downstream services trust the auth token without re-validating.

## Contracts
- **Exposes**: `validateToken(token) → User | null`, `createSession(credentials) → Token`
- **Guarantees**: Tokens expire after 24h. User objects always include roles.
- **Expects**: Valid JWT format. Database connection available.

## Dependencies
- **Uses**: Database (users table), Redis (session cache)
- **Used by**: All API routes, billing domain (user identity only)
- **Boundary**: Do NOT import from billing, notifications, or other domains

## Key Decisions
- JWT over session cookies: Stateless auth for horizontal scaling
- bcrypt cost 12: Legacy decision, migration to argon2 tracked in ADR-007

## Invariants
- Every user has exactly one primary email
- Deleted users are soft-deleted (is_deleted), never hard deleted
- User IDs are UUIDs, never sequential

## Key Files
- `service.ts` - AuthService implementation
- `tokens.ts` - JWT creation/validation
- `types.ts` - User, Token, Session types

## Gotchas
- Token validation returns null on invalid (doesn't throw)
- Never return raw password hashes in User objects

date +%Y-%m-%d

Last verified: 2025-12-17

## Key Files
- `index.ts` - Public exports
- `service.ts` - Main implementation