main_backend/docs/README.md

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.