Add CLAUDE.md documentation for AI-assisted development#15
Add CLAUDE.md documentation for AI-assisted development#15groupthinking merged 1 commit intomainfrom
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Summary of ChangesHello @groupthinking, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request introduces a dedicated documentation file, Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces CLAUDE.md, a comprehensive documentation file to provide context for AI-assisted development. This is a great initiative to streamline working with AI tools in the repository. The document is well-structured and covers key aspects of the project. My review focuses on a few minor inconsistencies and omissions in the documentation to enhance its accuracy and completeness, ensuring the AI assistant has the most precise context possible.
There was a problem hiding this comment.
Pull request overview
This PR adds a new CLAUDE.md documentation file intended to provide context for Claude Code when working in the EventRelay repository. The file covers project structure, development commands, code style guidelines, testing configuration, and architectural patterns.
Changes:
- New documentation file
CLAUDE.mdwith 116 lines covering project overview, repository structure, common commands, code style, testing, architecture notes, and key policies
|
|
||
| ## 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. |
There was a problem hiding this comment.
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.
| 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/`. |
| apps/ | ||
| web/ # Next.js frontend (port 3000) |
There was a problem hiding this comment.
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/.
| 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/ |
| # 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 |
There was a problem hiding this comment.
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.
| # 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 |
| - 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` |
There was a problem hiding this comment.
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.
| - 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`) |
| - Coverage target: 90% minimum, source: `src/youtube_extension` | ||
|
|
||
| ### Frontend | ||
| - Tests in `apps/web/src/components/__tests__/` and `apps/web/src/__tests__/` |
There was a problem hiding this comment.
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.
|
|
||
| ## 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. |
There was a problem hiding this comment.
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.
| # 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 | ||
|
|
||
| ```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 | ||
| ``` | ||
|
|
||
| ## 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) |
There was a problem hiding this comment.
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.
| - `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` |
There was a problem hiding this comment.
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 open a new pull request to apply changes based on the comments in this thread |
2 participants
Summary
Add comprehensive
CLAUDE.mddocumentation to provide context and guidance for Claude Code when working in the EventRelay repository. This file serves as a quick reference for project structure, development workflows, code standards, and architectural patterns.Changes
CLAUDE.mdwith 116 lines of structured documentation covering:Implementation Details
The documentation is organized for quick scanning with:
pyproject.toml,tsconfig.json, etc.)This enables Claude Code to understand the project context, follow established patterns, and maintain consistency with existing code standards without requiring manual context setup.
https://claude.ai/code/session_01XfMiNNVDB3BmeVBAXoKBvB