| # 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. |
|
|
