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,211 @@
+# API Reference
+
+## Authentication
+
+All endpoints (except `/auth/*` and `/api/ping/`) require a Bearer token in the Authorization header.
+
+### Register
+```
+POST /auth/register
+```
+
+### Login
+```
+POST /auth/login
+```
+
+### Refresh Token
+```
+POST /auth/refresh
+```
+
+## Users
+
+### List Users
+```
+GET /api/users/
+```
+
+### Get Current User
+```
+GET /api/users/me/
+```
+
+### Get User by ID
+```
+GET /api/users/{user_id}/
+```
+
+### Create User
+```
+POST /api/users/
+```
+
+### Update User
+```
+PATCH /api/users/{user_id}/
+```
+
+### Delete User
+```
+DELETE /api/users/{user_id}/
+```
+
+## Projects
+
+### List Projects
+```
+GET /api/projects/
+```
+
+### Create Project
+```
+POST /api/projects/
+```
+
+### Get Project
+```
+GET /api/projects/{project_id}/
+```
+
+### Update Project
+```
+PATCH /api/projects/{project_id}/
+```
+
+### Delete Project
+```
+DELETE /api/projects/{project_id}/
+```
+
+## Files
+
+### Upload File
+```
+POST /api/files/upload/
+```
+
+### Get File Info
+```
+GET /api/files/get_file/?file_path={path}
+```
+
+### Local File Access
+```
+GET /api/files/local/{file_path}
+```
+
+### List File Entries
+```
+GET /api/files/files/
+```
+
+### Create File Entry
+```
+POST /api/files/files/
+```
+
+### Get File Entry
+```
+GET /api/files/files/{file_id}/
+```
+
+### Update File Entry
+```
+PATCH /api/files/files/{file_id}/
+```
+
+### Delete File Entry
+```
+DELETE /api/files/files/{file_id}/
+```
+
+## Media
+
+### Get Media Metadata
+```
+GET /api/media/get_meta/?file_path={path}
+```
+
+### Remove Silence
+```
+POST /api/media/silence_remove
+```
+
+### Convert to MP4
+```
+POST /api/media/convert
+```
+
+## Transcription
+
+### Whisper Transcribe
+```
+POST /api/transcribe/whisper/
+```
+
+### Google Speech Transcribe
+```
+POST /api/transcribe/google-speech/
+```
+
+## Captions
+
+### Get Video with Captions
+```
+POST /api/captions/get_video/
+```
+
+## Jobs
+
+### List Jobs
+```
+GET /api/jobs/jobs/
+```
+
+### Create Job
+```
+POST /api/jobs/jobs/
+```
+
+### Get Job
+```
+GET /api/jobs/jobs/{job_id}/
+```
+
+### Update Job
+```
+PATCH /api/jobs/jobs/{job_id}/
+```
+
+### Delete Job
+```
+DELETE /api/jobs/jobs/{job_id}/
+```
+
+## Webhooks
+
+### List Webhooks
+```
+GET /api/webhooks/
+```
+
+### Create Webhook
+```
+POST /api/webhooks/
+```
+
+### Get Webhook
+```
+GET /api/webhooks/{webhook_id}/
+```
+
+### Update Webhook
+```
+PATCH /api/webhooks/{webhook_id}/
+```
+
+### Delete Webhook
+```
+DELETE /api/webhooks/{webhook_id}/
+```
@@ -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.
@@ -0,0 +1,96 @@
+.
+├── alembic
+│   ├── env.py
+│   └── versions
+│       └── 0001_initial.py
+├── alembic.ini
+├── cpv3
+│   ├── core
+│   │   ├── auth.py
+│   │   ├── __init__.py
+│   │   ├── schemas.py
+│   │   ├── security.py
+│   │   ├── settings.py
+│   │   └── storage
+│   │       ├── deps.py
+│   │       ├── __init__.py
+│   │       ├── local_backend.py
+│   │       ├── s3_backend.py
+│   │       ├── service.py
+│   │       └── types.py
+│   ├── db
+│   │   ├── base.py
+│   │   ├── __init__.py
+│   │   ├── models.py
+│   │   └── session.py
+│   ├── __init__.py
+│   ├── main.py
+│   └── modules
+│       ├── captions
+│       │   ├── __init__.py
+│       │   ├── router.py
+│       │   ├── schemas.py
+│       │   └── service.py
+│       ├── __init__.py
+│       ├── jobs
+│       │   ├── __init__.py
+│       │   ├── models.py
+│       │   ├── router.py
+│       │   ├── schemas.py
+│       │   └── service_db.py
+│       ├── media
+│       │   ├── __init__.py
+│       │   ├── models.py
+│       │   ├── router.py
+│       │   ├── schemas.py
+│       │   ├── service_db.py
+│       │   └── service.py
+│       ├── projects
+│       │   ├── __init__.py
+│       │   ├── models.py
+│       │   ├── router.py
+│       │   ├── schemas.py
+│       │   └── service.py
+│       ├── storage
+│       │   ├── __init__.py
+│       │   ├── models.py
+│       │   ├── router.py
+│       │   ├── schemas.py
+│       │   └── service.py
+│       ├── system
+│       │   ├── __init__.py
+│       │   └── router.py
+│       ├── transcription
+│       │   ├── constants.py
+│       │   ├── __init__.py
+│       │   ├── models.py
+│       │   ├── router.py
+│       │   ├── schemas.py
+│       │   ├── service_db.py
+│       │   └── service.py
+│       ├── users
+│       │   ├── __init__.py
+│       │   ├── models.py
+│       │   ├── router.py
+│       │   ├── schemas.py
+│       │   └── service.py
+│       └── webhooks
+│           ├── __init__.py
+│           ├── models.py
+│           ├── router.py
+│           ├── schemas.py
+│           └── service_db.py
+├── cpv3.egg-info
+│   ├── dependency_links.txt
+│   ├── PKG-INFO
+│   ├── requires.txt
+│   ├── SOURCES.txt
+│   └── top_level.txt
+├── docker-compose.yml
+├── Dockerfile
+├── project_file_schema.txt
+├── pyproject.toml
+├── schema.dbml
+└── uv.lock
+
+18 directories, 76 files
@@ -0,0 +1,341 @@
+// Enums (expanded + used for Webhooks/JobEvents)
+
+enum ProjectStatusEnum {
+  DRAFT
+  IN_PROGRESS
+  REVIEW
+  COMPLETED
+  ARCHIVED
+  CANCELED
+}
+
+enum StorageBackendEnum {
+  LOCAL
+  S3
+}
+
+enum MediaFileTypeEnum {
+  VIDEO
+  AUDIO
+  IMAGE
+}
+
+enum SourceTypeEnum {
+  UPLOAD
+  IMPORT
+  RECORDING
+  GENERATED
+}
+
+enum ArtifactTypeEnum {
+  VIDEO
+  AUDIO
+  THUMBNAIL
+  PREVIEW
+  WAVEFORM
+  TRANSCRIPT_JSON
+  METADATA
+}
+
+enum TranscribeEngineEnum {
+  LOCAL_WHISPER
+  GOOGLE_CLOUD
+}
+
+enum JobStatusEnum {
+  QUEUED
+  STARTED
+  IN_PROGRESS
+  SUCCEEDED
+  FAILED
+  CANCELED
+  RETRYING
+}
+
+enum WebhookEventEnum {
+  PROJECT_CREATED
+  PROJECT_UPDATED
+  FILE_UPLOADED
+  ARTIFACT_CREATED
+  TRANSCRIPTION_COMPLETED
+  JOB_STARTED
+  JOB_PROGRESS
+  JOB_SUCCEEDED
+  JOB_FAILED
+}
+
+enum JobEventTypeEnum {
+  LOG
+  STATUS_CHANGED
+  PROGRESS
+  WARNING
+  ERROR
+}
+
+// Tables
+
+Table Users {
+  id uuid [pk]
+  created_at datetime
+  updated_at datetime
+  is_active boolean
+  deleted_at datetime
+
+  username varchar(150) [unique]
+  email varchar [unique]
+
+  password_hash varchar(255)
+
+  first_name varchar(150)
+  last_name varchar(150)
+
+  phone_number varchar(16)
+  avatar varchar(2048)
+
+  email_verified boolean
+  phone_verified boolean
+
+  // Replace is_staff and is_superuser with role system later
+  is_staff boolean
+  is_superuser boolean
+
+  date_joined datetime
+  last_login datetime
+
+  Indexes {
+    (email) [name: "idx_users_email"]
+    (username) [name: "idx_users_username"]
+    (is_active) [name: "idx_users_is_active"]
+    (deleted_at) [name: "idx_users_deleted_at"]
+  }
+}
+
+Table Projects {
+  id uuid [pk]
+  created_at datetime
+  updated_at datetime
+  is_active boolean
+  deleted_at datetime
+
+  owner_id uuid
+
+  name varchar(150)
+  description varchar(4096)
+  language varchar(3)
+  folder varchar
+  status ProjectStatusEnum
+
+  Indexes {
+    (owner_id) [name: "idx_projects_owner_id"]
+    (status) [name: "idx_projects_status"]
+    (is_active) [name: "idx_projects_is_active"]
+    (deleted_at) [name: "idx_projects_deleted_at"]
+  }
+}
+
+Table Files {
+  id uuid [pk]
+  created_at datetime
+  updated_at datetime
+  is_active boolean
+  deleted_at datetime
+
+  project_id uuid
+  owner_id uuid
+
+  original_file_name varchar
+  path varchar
+
+  storage_backend StorageBackendEnum
+  mime_type varchar
+  size_bytes bigint
+  checksum varchar(256)
+  file_format varchar(10)
+
+  is_uploaded boolean
+
+  Indexes {
+    (project_id) [name: "idx_files_project_id"]
+    (owner_id) [name: "idx_files_owner_id"]
+    (checksum) [name: "idx_files_checksum"]
+    (is_uploaded) [name: "idx_files_is_uploaded"]
+    (is_active) [name: "idx_files_is_active"]
+    (deleted_at) [name: "idx_files_deleted_at"]
+  }
+}
+
+// Normalized: MediaFiles extends Files (no duplicate project_id/owner_id)
+Table MediaFiles {
+  id uuid [pk]
+  created_at datetime
+  updated_at datetime
+  is_active boolean
+  deleted_at datetime
+
+  file_id uuid [unique]
+
+  duration_sec float
+  frame_rate float
+  width integer
+  height integer
+
+  probe_json jsonb
+  notes varchar(4096)
+  meta jsonb
+
+  file_type MediaFileTypeEnum
+  source_type SourceTypeEnum
+
+  Indexes {
+    (file_id) [name: "idx_mediafiles_file_id"]
+    (file_type) [name: "idx_mediafiles_file_type"]
+    (source_type) [name: "idx_mediafiles_source_type"]
+    (is_active) [name: "idx_mediafiles_is_active"]
+    (deleted_at) [name: "idx_mediafiles_deleted_at"]
+  }
+}
+
+// Normalized: Artifact points to output file; lineage via source_media_file_id
+Table Artifacts {
+  id uuid [pk]
+  created_at datetime
+  updated_at datetime
+  is_active boolean
+  deleted_at datetime
+
+  output_file_id uuid [unique]
+  source_media_file_id uuid
+
+  artifact_type ArtifactTypeEnum
+
+  Indexes {
+    (output_file_id) [name: "idx_artifacts_output_file_id"]
+    (source_media_file_id) [name: "idx_artifacts_source_media_file_id"]
+    (artifact_type) [name: "idx_artifacts_artifact_type"]
+    (is_active) [name: "idx_artifacts_is_active"]
+    (deleted_at) [name: "idx_artifacts_deleted_at"]
+  }
+}
+
+// Normalized: no duplicate project_id; derive via input_file_id / transcript_artifact_id
+Table Transcriptions {
+  id uuid [pk]
+  created_at datetime
+  updated_at datetime
+  is_active boolean
+  deleted_at datetime
+
+  input_file_id uuid
+  transcript_artifact_id uuid
+
+  engine TranscribeEngineEnum
+  language varchar(3)
+
+  document jsonb
+  transcribe_options jsonb
+
+  Indexes {
+    (input_file_id) [name: "idx_transcriptions_input_file_id"]
+    (transcript_artifact_id) [unique, name: "ux_transcriptions_transcript_artifact_id"]
+    (engine) [name: "idx_transcriptions_engine"]
+    (is_active) [name: "idx_transcriptions_is_active"]
+    (deleted_at) [name: "idx_transcriptions_deleted_at"]
+  }
+}
+
+Table Jobs {
+  id uuid [pk]
+  created_at datetime
+  updated_at datetime
+  is_active boolean
+
+  broker_id varchar(255) [unique]
+
+  user_id uuid
+  project_id uuid
+
+  input_data jsonb
+  output_data jsonb
+
+  status JobStatusEnum
+  progress_pct integer
+
+  error_message varchar(4096)
+  current_message varchar(4096)
+
+  started_at datetime
+  finished_at datetime
+
+  Indexes {
+    (broker_id) [name: "idx_jobs_broker_id"]
+    (user_id) [name: "idx_jobs_user_id"]
+    (project_id) [name: "idx_jobs_project_id"]
+    (status) [name: "idx_jobs_status"]
+    (is_active) [name: "idx_jobs_is_active"]
+  }
+}
+
+Table JobEvents {
+  id uuid [pk]
+  created_at datetime
+  updated_at datetime
+  is_active boolean
+
+  job_id uuid
+  event_type JobEventTypeEnum
+  payload jsonb
+
+  Indexes {
+    (job_id) [name: "idx_jobevents_job_id"]
+    (event_type) [name: "idx_jobevents_event_type"]
+    (created_at) [name: "idx_jobevents_created_at"]
+    (is_active) [name: "idx_jobevents_is_active"]
+  }
+}
+
+Table Webhooks {
+  id uuid [pk]
+  created_at datetime
+  updated_at datetime
+  is_active boolean
+  deleted_at datetime
+
+  project_id uuid
+  user_id uuid
+
+  event WebhookEventEnum
+  url varchar(512)
+  secret varchar(256)
+
+  Indexes {
+    (project_id) [name: "idx_webhooks_project_id"]
+    (user_id) [name: "idx_webhooks_user_id"]
+    (event) [name: "idx_webhooks_event"]
+    (project_id, event, url) [unique, name: "ux_webhooks_project_event_url"]
+    (is_active) [name: "idx_webhooks_is_active"]
+    (deleted_at) [name: "idx_webhooks_deleted_at"]
+  }
+}
+
+// Refs (fixed + aligned to actual FK columns)
+Ref: Projects.owner_id > Users.id
+
+Ref: Files.project_id > Projects.id
+Ref: Files.owner_id > Users.id
+
+Ref: MediaFiles.file_id > Files.id
+
+Ref: Artifacts.output_file_id > Files.id
+Ref: Artifacts.source_media_file_id > MediaFiles.id
+
+Ref: Transcriptions.input_file_id > Files.id
+Ref: Transcriptions.transcript_artifact_id > Artifacts.id
+
+Ref: Jobs.project_id > Projects.id
+Ref: Jobs.user_id > Users.id
+
+Ref: JobEvents.job_id > Jobs.id
+
+Ref: Webhooks.project_id > Projects.id
+Ref: Webhooks.user_id > Users.id
+