init: new structure + fix lint errors

2026-02-03 02:15:07 +03:00
commit 67e0f22b4f
89 changed files with 7654 additions and 0 deletions
@@ -0,0 +1,53 @@
+# 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.