Skip to content

CLAUDE.md

Latest commit

 

History

History
116 lines (89 loc) · 4.06 KB

CLAUDE.md

File metadata and controls

116 lines (89 loc) · 4.06 KB

CLAUDE.md

This file provides context for Claude Code when working in the EventRelay repository.

Project Overview

EventRelay is an AI-powered video automation platform that transforms YouTube videos into actionable workflows. It captures transcripts, extracts events, dispatches them to MCP (Model Context Protocol) agents, and builds a RAG-based knowledge store. The backend is Python/FastAPI and the frontend is a Next.js/React/TypeScript monorepo.

Repository Structure

src/                          # Python backend
  youtube_extension/
    backend/                  # FastAPI app (api/v1/, services/, models/, middleware/)
    services/                 # Orchestration (agents/, workflows/, ai/)
    mcp/                      # MCP ecosystem coordinator
    main.py                   # FastAPI entry point
apps/
  web/                        # Next.js frontend (port 3000)
packages/                     # Shared monorepo packages (eslint-config, tsconfig, logger, etc.)
mcp-servers/                  # MCP server implementations (litert-mcp, shared-state)
tests/                        # Python tests (unit/, integration/, fixtures/, workflows/)
docs/                         # Extended documentation
infrastructure/               # Kubernetes manifests, Terraform, database setup
.github/workflows/            # CI/CD (ci.yml, security.yml, deploy-cloud-run.yml, etc.)

Common Commands

Python Backend

# Install (editable with dev extras)
pip install -e .[dev,youtube,ml]

# Run backend server
uvicorn src.youtube_extension.main:app --reload --port 8000

# Run tests
pytest tests/ -v
pytest tests/unit/ -v                    # Unit tests only
pytest tests/ -m "not slow"              # Skip slow tests

# Lint and format
ruff check src/                          # Lint
ruff check src/ --fix                    # Auto-fix
black src/                               # Format
isort src/                               # Sort imports
mypy src/                                # Type check

Frontend (Next.js)

# Install all workspace dependencies
npm install

# Build (all workspaces via Turbo)
turbo run build
# or: npm run build

# Dev server
turbo run dev
# or: npm run dev

# Lint
turbo run lint

# Test
turbo run test

Code Style

Python

  • Formatter: Black, 88-char line length
  • Import sorting: isort (profile: black)
  • Linter: Ruff (E, W, F, I, B, C4, UP rules; E501 ignored)
  • Type checking: mypy strict mode (disallow_untyped_defs = true)
  • Target Python 3.9+
  • Config in pyproject.toml

TypeScript/JavaScript

  • Strict mode TypeScript (apps/web/tsconfig.json)
  • ESLint with Next.js rules (shared config in packages/eslint-config/)
  • Tailwind CSS for styling
  • Path alias: @/* maps to src/*

Testing

Python (pytest)

  • Config: pyproject.toml [tool.pytest.ini_options]
  • pythonpath = src, testpaths = tests
  • Async mode: asyncio_mode = "auto"
  • Markers: unit, integration, slow, asyncio, database, security, e2e, performance
  • Coverage target: 90% minimum, source: src/youtube_extension

Frontend

  • Tests in apps/web/src/components/__tests__/ and apps/web/src/__tests__/

Architecture Notes

  • Event-driven: Events follow <domain>.<entity>.<action> naming (e.g. youtube.video.captured)
  • Dependency injection: Service container pattern in backend/containers/
  • Multi-provider AI: Routes to Gemini, OpenAI, Anthropic, or Grok
  • MCP integration: Agent orchestration via Model Context Protocol
  • Database: SQLite (dev), PostgreSQL (prod); migrations via Alembic
  • Auth: NextAuth.js (frontend), python-jose (backend)
  • Monorepo: Turbo for JS workspaces (apps/*, packages/*, mcp-servers/*)

Key Policies

  • REAL_MODE_ONLY: No mock delays, fake data, or simulated responses in production code
  • No secrets in code: All keys/credentials go in .env (gitignored)
  • Security: Validate inputs via Pydantic; no dangerouslySetInnerHTML in React; sanitize subprocess args
  • Type safety enforced: mypy strict (Python), TypeScript strict (frontend)