docs/ARCHITECTURE.md

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.