# Architecture Design

> **AI Context**: This document defines WHERE files go and WHAT each file does. Follow this structure exactly.

## Directory Tree
```
src/
├── core/
│   ├── __init__.py
│   ├── models.py          # Data models / ORM definitions
│   ├── database.py        # DB connection, sessions, migrations
│   └── config.py          # Settings, environment variables (pydantic-settings)
├── api/
│   ├── __init__.py
│   ├── routes.py          # HTTP endpoint definitions
│   ├── schemas.py         # Pydantic request/response models
│   └── dependencies.py    # FastAPI/Flask dependency injection (auth, DB)
├── services/
│   ├── __init__.py
│   ├── [feature]_service.py  # Business logic (one per major feature)
│   └── email_service.py      # External integrations
├── utils/
│   ├── __init__.py
│   ├── validators.py      # Input validation helpers
│   ├── exceptions.py      # Custom exception classes
│   └── logger.py          # Logging configuration
└── main.py                # Application entry point

tests/
├── conftest.py            # pytest fixtures, shared setup
├── unit/                  # Unit tests (isolated, fast)
│   ├── test_models.py
│   ├── test_validators.py
│   └── test_services.py
├── integration/           # Integration tests (DB, external APIs)
│   ├── test_api.py
│   └── test_database.py
└── e2e/                   # End-to-end tests (full flow)
    └── test_[feature].py

docs/
├── PRD.md                 # Requirements (SOURCE OF TRUTH)
├── ARCHITECTURE.md        # This file (FILE MAP)
├── CONTEXT.md             # Coding standards
└── decisions/             # Architecture Decision Records (ADRs)
    └── 001-use-fastapi.md

agents/
├── smolagent_runner.py    # Python agent with local Ollama
└── multiagent_workflow.py # Multi-agent orchestration

scripts/
├── setup.sh               # One-command project setup
├── start-ollama.sh        # Start optimized local Ollama server
└── lint.sh                # Run all linters and formatters
```

## File Responsibilities

| File | Responsibility | Key Classes/Functions | Dependencies |
|------|---------------|----------------------|--------------|
| `core/config.py` | Environment config, secrets | `Settings` (pydantic) | `pydantic-settings` |
| `core/models.py` | ORM models | `User`, `Post` | SQLAlchemy/Pydantic |
| `core/database.py` | DB engine, sessions | `get_db()`, `Base`, `engine` | `core/models` |
| `api/schemas.py` | API I/O models | `UserCreate`, `UserResponse` | Pydantic |
| `api/dependencies.py` | Dependency injection | `get_current_user()`, `get_db()` | `core/database` |
| `api/routes.py` | HTTP handlers | `create_user()`, `get_posts()` | `services/`, `schemas/` |
| `services/*_service.py` | Business logic | `create_user()`, `send_email()` | `core/models`, external APIs |
| `utils/validators.py` | Validation | `validate_email()`, `validate_password()` | regex, stdlib |
| `utils/exceptions.py` | Custom errors | `ValidationError`, `NotFoundError` | stdlib |
| `utils/logger.py` | Logging setup | `get_logger()` | `logging` module |
| `main.py` | App factory | `create_app()` | Everything |

## Data Flow
```
[Client] → [Routes] → [Dependencies] → [Services] → [Models/DB]
              ↓                              ↓
         [Schemas]                    [External APIs]
              ↓
         [Validators]
```

## Module Dependencies
- `api` depends on: `services`, `core`, `utils`
- `services` depends on: `core`, `utils`
- `core` depends on: `utils` (exceptions, validators)
- `utils` depends on: NOTHING (stdlib only)
- **Rule**: No circular dependencies. `utils` is the leaf. `api` is the root.