File size: 3,920 Bytes
4aec5bd | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 | # 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.
|