# Documentation

This folder contains documentation and references for the Coffee Project Backend API.

## Project Structure

```
cpv3/
├── api/                    # Versioned API routers
│   └── v1/
│       └── router.py       # Aggregates all module routers
├── common/                 # Cross-cutting concerns and utilities
│   └── schemas.py          # Base Pydantic schema
├── db/                     # Database configuration
│   ├── base.py             # SQLAlchemy base classes
│   ├── models.py           # All ORM models (optional central import)
│   └── session.py          # Database session management
├── infrastructure/         # App bootstrapping, config, security, external integrations
│   ├── settings.py         # Application settings (Pydantic)
│   ├── security.py         # Password hashing, JWT tokens
│   ├── auth.py             # Authentication dependencies
│   ├── deps.py             # Infrastructure-level dependencies
│   └── storage/            # Storage backends
│       ├── base.py         # StorageService and protocol
│       ├── local.py        # Local filesystem backend
│       ├── s3.py           # S3/MinIO backend
│       └── types.py        # Storage types
├── modules/                # Feature modules
│   ├── captions/
│   ├── files/              # File management (renamed from storage)
│   ├── jobs/
│   ├── media/
│   ├── projects/
│   ├── system/
│   ├── transcription/
│   ├── users/
│   └── webhooks/
└── main.py                 # FastAPI application entry point
```

## Module Structure

Each module follows this structure:

- `router.py` - HTTP concerns only (request/response, status codes, dependencies)
- `schemas.py` - Pydantic DTOs only
- `service.py` - Business logic + orchestration (calls repositories + other services)
- `repository.py` - All DB queries (SQLAlchemy session usage)
- `models.py` - ORM models only

## API Versioning

The API uses URL-based versioning. All routes are mounted under `/api/` prefix.