remotion_service/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Monorepo Structure

Three independent projects:
- **`cofee_frontend/`** — Next.js 16 + TypeScript frontend (FSD architecture)
- **`cofee_backend/`** — FastAPI + Python backend (layered module pattern)
- **`remotion_service/`** — ElysiaJS + Remotion video captioning microservice

Each subproject has its own `CLAUDE.md` and `AGENTS.md` — read the relevant one before starting work.

## Cross-Service Data Flow

```
Frontend (Next.js :3000) → Backend API (FastAPI :8000) → Remotion Service (Elysia :3001)
                                  ↕                              ↕
                            PostgreSQL :5332                  S3/MinIO :9000
                            Redis :6379 (pub/sub + task queue)
```

1. Frontend calls Backend API via typed `openapi-fetch` client with JWT auth
2. Backend submits background jobs via Dramatiq (Redis broker) — e.g. transcription, silence detection
3. Backend sends video + transcription to Remotion Service for caption rendering
4. Remotion renders captions onto video, uploads result to S3, returns S3 path
5. Backend notifies Frontend of job completion via WebSocket (Redis pub/sub)

## Frontend Commands

```bash
bun dev                          # Dev server (localhost:3000)
bun run build                    # Production build
bunx tsc --noEmit                # Type-check (lint scripts are broken)
bun run gc <layer> <Name>        # Generate FSD component
bun run gicons                   # Convert raw SVGs to React icon components
bun run gen:api-types            # Regenerate API types from OpenAPI schema (needs backend running)
bun run test:e2e                 # Playwright E2E tests
```

## Backend Commands

```bash
uv sync                                          # Install dependencies
uv run uvicorn cpv3.main:app --reload            # Dev server (localhost:8000)
uv run pytest                                    # Run all tests
uv run pytest tests/integration/<file>.py        # Single test file
uv run pytest -k "test_name"                     # Single test by name
uv run dramatiq cpv3.modules.tasks.service       # Start background worker
uv run alembic revision --autogenerate -m "msg"  # Create migration
uv run alembic upgrade head                      # Apply migrations
uv run ruff check cpv3/                          # Lint
uv run ruff format cpv3/                         # Auto-format
```

## Remotion Service Commands

```bash
cd remotion_service
bun install                      # Install dependencies
bun run server                   # Start API server (localhost:3001)
bun run dev                      # Remotion Studio for visual debugging
bunx tsc --noEmit                # Type-check
```

## Frontend Architecture (FSD)

Strict unidirectional imports: `pages -> widgets -> features -> entities -> shared`. No cross-slice imports within the same layer. Enforced by `eslint-plugin-boundaries`.

Features are **module-aware** — grouped by domain (`features/profile/`, `features/project/`), not flat.

Path aliases: `@app/*`, `@pages/*`, `@widgets/*`, `@features/*`, `@entities/*`, `@shared/*` map to `src/<layer>/*`.

See `cofee_frontend/CLAUDE.md` for full details on components, API client, styling, and gotchas.

## Backend Architecture

Layered module pattern. Each module has exactly: `__init__.py`, `models.py`, `schemas.py`, `repository.py`, `service.py`, `router.py`. No extra files, no subdirectories within modules. When in doubt, put logic in `service.py`.

11 modules: `users`, `projects`, `media`, `files`, `transcription`, `captions`, `jobs`, `notifications`, `tasks`, `webhooks`, `system`.

Flow: Router → Service → Repository → Database (async SQLAlchemy + PostgreSQL).

See `cofee_backend/CLAUDE.md` for full details on patterns, commands, and gotchas.

## Remotion Service Architecture

Standalone video captioning microservice. Two layers sharing types:
- **Server** (`server/`): ElysiaJS API, single `POST /api/render` endpoint — receives S3 video path + transcription, spawns Remotion CLI render, uploads captioned video to S3.
- **Composition** (`src/`): Remotion React components for deterministic frame rendering. All animations **must** use Remotion's `interpolate()`/`spring()`, never CSS transitions or Framer Motion.

See `remotion_service/CLAUDE.md` for full details.

## Docker Services

```
postgres  → localhost:5332    minio   → localhost:9000 (console: 9001)
redis     → localhost:6379    api     → localhost:8000 (OpenAPI at /api/schema/)
worker    → Dramatiq bg jobs  remotion → localhost:3001
```

```bash
cd cofee_backend && docker-compose up    # DB, Redis, MinIO, API, Worker
cd remotion_service && docker-compose up # Remotion service (dev)
```

## Localization

All user-facing UI text **must be in Russian**. The only exception is the brand name "Coffee Project" / "Cofee Project" — it stays in English.

## Code Style (Both Projects)

- Simple over clever, early returns over deep nesting
- Max ~30 lines per function — extract helpers if longer
- Named constants instead of magic values
- Descriptive names: `getUserById` not `getData`
- Store user-facing error messages in named constants (`ERROR_` prefix), not inline strings

## Agent Team

This project has a team of 19 specialist agents: 3 leads, 14 specialists, and 2 staff.
Agent files: `.claude/agents/`. Shared protocol: `.claude/agents-shared/team-protocol.md`.

**You (Claude) ARE the tech lead / orchestrator.** You select and dispatch agents directly.

### Team Hierarchy

    You (Tech Lead)
      ├── Architecture Lead → Backend Architect, Frontend Architect, DB Architect, Remotion Engineer, Sr. Backend Engineer, Sr. Frontend Engineer
      ├── Quality Lead → Frontend QA, Backend QA, Security Auditor, Design Auditor, Performance Engineer
      ├── Product Lead → UI/UX Designer, Technical Writer, ML/AI Engineer
      ├── DevOps Engineer (staff)
      └── Debug Specialist (staff)

### Architect vs. Engineer Role Split

**Architects** (Backend Architect, Frontend Architect) design specs, API contracts, component trees, and patterns. They advise — they do NOT write implementation code.

**Engineers** (Senior Backend Engineer, Senior Frontend Engineer) implement production code from architect specs. They receive designs and produce working code.

This separation ensures architectural decisions are made before implementation begins.

### Developer Team Consultation

For ANY non-trivial task, dispatch specialist agents directly. Do NOT solve domain-specific
tasks yourself. Use leads for multi-specialist coordination, or dispatch specialists directly
for focused tasks (e.g., `devops-engineer` for Docker, `security-auditor` for security).

**CRITICAL: Never edit files yourself for domain-specific work — dispatch the specialist first.** Reading files to understand the problem is fine; editing them is not.

### Dispatch Loop

1. **Announce**: "Consulting with the developer team to [task summary]"
2. **Identify affected files** using Glob/Read (read-only — do NOT edit yet)
3. **Dispatch agents in parallel** — pass file paths and task description (NOT file contents)
4. **Collect results** from all agents
5. Present results to user, **crediting which specialists contributed**

Skip agents ONLY for: rename a variable, fix a typo, fix a single-line syntax
error, answer a quick factual question, run a command the user explicitly asked for.

### Conflict Handling

If dispatched agents report conflicting recommendations:
- Present both perspectives to the user with your analysis
- Let the user decide on trade-offs that affect their product

## Available ECC Skills

The `everything-claude-code` plugin provides skills invocable via `/skill-name`. Key ones for this project:

| Skill | When to use |
|-------|-------------|
| `/plan` | Before implementing multi-step features — creates step-by-step plan |
| `/tdd` | When writing new features or fixing bugs — test-first workflow |
| `/docs` | Look up current library docs via Context7 (Next.js, FastAPI, Remotion, etc.) |
| `/security-review` | After writing auth, user input handling, API endpoints, or file uploads |
| `/search-first` | Before writing custom code — check for existing libraries/patterns |

Use `superpowers:verification-before-completion` to enforce running verification commands before claiming work is done.

## Compact Instructions

When compacting, always preserve:
- List of all modified files and their purposes
- Test command results (pass/fail)
- Architecture decisions made in this session
- Error messages and their resolutions
- Which subproject (frontend/backend/remotion) is being worked on