Skip to content

Add CLAUDE.md documentation for AI-assisted development #15

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
groupthinking merged 1 commit into from
Jan 28, 2026
Merged

Add CLAUDE.md documentation for AI-assisted development #15

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
116 changes: 116 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,116 @@
# 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.
Copy link

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The description states "the frontend is a Next.js/React/TypeScript monorepo" which is accurate, but throughout the document the actual frontend location is incorrectly referenced. The frontend is located at apps/web/ (Next.js), not in a separate frontend/ directory. This needs to be consistent with the actual repository structure shown in the README.md and the monorepo layout.

Suggested change
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.
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 repository is a monorepo with a Next.js/React/TypeScript frontend located at `apps/web/`.

Copilot uses AI. Check for mistakes.
Copy link

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section describes the codebase as having a "React frontend" but the frontend is actually Next.js (a React framework), not plain React. This distinction is important because Next.js has specific architectural patterns (server components, app router, API routes, etc.) that differ from a standard React app. The description should clarify "Next.js frontend" instead of just "React frontend" for accuracy. Additionally, there's a discrepancy with the custom coding guidelines which describe it as "FastAPI backend, React frontend" without mentioning Next.js.

Copilot generated this review using guidance from repository custom instructions.

## 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)
Comment on lines +18 to +19
Copy link

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The repository structure shows web/ as the Next.js frontend location (line 19), but this is incomplete. The full path should be apps/web/ to match the actual monorepo structure. Additionally, line 18 shows apps/ without explaining it's the monorepo apps directory. The structure description should clarify that web/ is inside apps/ and that apps/ contains multiple applications including firebase/, uvai-frontend/, and web/.

Suggested change
apps/
web/ # Next.js frontend (port 3000)
apps/ # Monorepo applications (Next.js and supporting apps)
firebase/ # Firebase-related app/configuration
uvai-frontend/ # Additional frontend application
web/ # Next.js frontend (port 3000) at apps/web/

Copilot uses AI. Check for mistakes.
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

```bash
# 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)

```bash
# 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
Comment on lines +55 to +70
Copy link

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The frontend commands reference a non-existent structure and workflow. The documentation shows standalone turbo run build, turbo run dev, etc., but these commands should be executed from the monorepo root (where they're defined in package.json as npm run build, npm run dev, etc.). Additionally, the frontend is Next.js-based at apps/web/, not a generic frontend, so commands like npm dev --prefix apps/web or working directly in the apps/web directory would be more accurate. The current commands don't match how the monorepo is actually structured or how Turbo is configured.

Suggested change
# 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
# Install all workspace dependencies (from monorepo root)
npm install
# Start Next.js dev server for the web app
npm run dev # runs Turbo dev pipeline from monorepo root
# or, scoped directly to the web app:
npm run dev --prefix apps/web
# Build web app (and any dependent packages)
npm run build # runs Turbo build pipeline from monorepo root
# or:
npm run build --prefix apps/web
# Lint
npm run lint # from monorepo root
# or:
npm run lint --prefix apps/web
# Test
npm test --prefix apps/web
# or:
npm run test --prefix apps/web

Copilot uses AI. Check for mistakes.
```

## 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`
Comment on lines +92 to +96
Copy link

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The coverage target stated as "90% minimum" is accurate according to pytest.ini (line 17: --cov-fail-under=90), but the coverage source is incorrectly specified. The document states source: src/youtube_extension, but pytest.ini (line 11-13) actually covers backend, enhanced_video_processor, and enterprise_mcp_server, while pyproject.toml covers src/youtube_extension. There's an inconsistency between pytest.ini and pyproject.toml coverage configuration that should be clarified in this documentation.

Suggested change
- 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`
- Config: `pytest.ini` and `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: `--cov-fail-under=90` (90% minimum); sources from `pytest.ini` (`backend`, `enhanced_video_processor`, `enterprise_mcp_server`) and from `pyproject.toml` (`src/youtube_extension`)

Copilot uses AI. Check for mistakes.
Copy link

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The custom coding guidelines (CodingGuidelineID: 1000000) specify that the repository should have test coverage greater than 80% for new features, but the CLAUDE.md documentation states 90% minimum. While pytest.ini does enforce 90% (--cov-fail-under=90), this creates a discrepancy with the stated guideline policy. The documentation should either align with the 80% guideline threshold or explicitly note that the actual enforcement is stricter at 90%.

Copilot generated this review using guidance from repository custom instructions.

### Frontend
- Tests in `apps/web/src/components/__tests__/` and `apps/web/src/__tests__/`
Copy link

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The frontend test path apps/web/src/components/__tests__/ is correct and matches the actual structure, but the documentation should also mention the additional test patterns. According to the apps/web/package.json, tests may follow Next.js conventions, and the README.md mentions tests are also in apps/web/src/__tests__/. Both locations should be documented for completeness.

Copilot uses AI. Check for mistakes.

## 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)
Comment on lines +1 to +116
Copy link

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The CLAUDE.md document contradicts the established custom coding guidelines (CodingGuidelineID: 1000000) in multiple ways. The custom guidelines reference a frontend/ directory extensively and use commands like npm start --prefix frontend, npm test --prefix frontend, etc. However, CLAUDE.md correctly identifies that the frontend is in the monorepo structure but then provides conflicting command examples. The inconsistency between these two documentation files will create confusion. Either the custom guidelines need to be updated to reflect the monorepo structure, or CLAUDE.md should align with the legacy frontend/ references until the custom guidelines are updated.

Copilot generated this review using guidance from repository custom instructions.
Loading