e094014dbe
- Add workflow instruction to commit and push after code changes - Add backend development commands (Python venv, uvicorn) - Add database commands (Alembic migrations) - Expand environment setup for both frontend and backend - Document backend architecture (agents, services, repositories, models) - Add PostgreSQL and Alembic to tech stack - Update data persistence section for backend storage Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
108 lines
4 KiB
Markdown
Executable file
108 lines
4 KiB
Markdown
Executable file
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Workflow
|
|
|
|
**After every round of code changes, commit and push to the remote repository.** Write clear, descriptive commit messages that explain what was changed and why.
|
|
|
|
## Project Overview
|
|
|
|
Mod Comms is an AI-powered proof review tool for Barclays marketing materials. It uses multiple AI agents to analyze uploaded proofs (marketing assets) for legal compliance, brand adherence, tone of voice, and channel suitability.
|
|
|
|
## Development Commands
|
|
|
|
### Frontend
|
|
```bash
|
|
cd frontend
|
|
npm install # Install dependencies
|
|
npm run dev # Start dev server on port 3000
|
|
npm run build # Production build
|
|
npm run preview # Preview production build
|
|
```
|
|
|
|
### Backend
|
|
```bash
|
|
cd backend
|
|
python -m venv venv
|
|
source venv/bin/activate # Windows: venv\Scripts\activate
|
|
pip install -r requirements.txt
|
|
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
|
```
|
|
|
|
### Database
|
|
```bash
|
|
cd backend
|
|
alembic upgrade head # Run migrations
|
|
alembic revision --autogenerate -m "description" # Create migration
|
|
```
|
|
|
|
## Environment Setup
|
|
|
|
### Frontend (`frontend/.env.local`)
|
|
```
|
|
GEMINI_API_KEY=your_api_key_here
|
|
VITE_BACKEND_WS_URL=ws://localhost:8000/ws/analyze
|
|
VITE_BACKEND_URL=http://localhost:8000
|
|
```
|
|
|
|
### Backend (`backend/.env`)
|
|
```
|
|
GEMINI_API_KEY=your_api_key_here
|
|
DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/modcomms
|
|
AZURE_TENANT_ID=your_tenant_id
|
|
AZURE_CLIENT_ID=your_client_id
|
|
CORS_ORIGINS=http://localhost:3000
|
|
DISABLE_AUTH=true # For local development without Azure AD
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Frontend (`frontend/`)
|
|
- **App.tsx** - Main application with routing and global state (campaigns, proofs, flagged/resolved items)
|
|
- **components/** - React components for views (Campaigns, Projects, FeedbackReport, Analytics, Auditing)
|
|
- **services/geminiService.ts** - WebSocket client for backend analysis
|
|
- **services/apiService.ts** - REST API client
|
|
- **types.ts** - Core TypeScript definitions
|
|
|
|
### Backend (`backend/app/`)
|
|
- **main.py** - FastAPI app entry point with WebSocket route at `/ws/analyze`
|
|
- **agents/** - AI agent implementations (legal, brand, tone, channel, lead)
|
|
- **services/analysis_service.py** - Orchestrates multi-agent analysis pipeline
|
|
- **services/gemini_service.py** - Google Gemini 2.5 Flash API wrapper
|
|
- **services/reference_docs.py** - Loads brand/channel guidelines as context
|
|
- **repositories/** - Data access layer (campaigns, proofs, audits, users)
|
|
- **models/** - SQLAlchemy ORM models and Pydantic schemas
|
|
|
|
### Multi-Agent System
|
|
Four specialist agents analyze each proof in parallel:
|
|
- **Legal Agent** - Advertising standards, disclaimers, financial promotion detection
|
|
- **Brand Agent** - Logo usage, colors, typography, design principles
|
|
- **Tone Agent** - Copy clarity, brand voice, grammar
|
|
- **Channel Agent** - Platform specs, accessibility, technical requirements
|
|
|
|
The **Lead Agent** synthesizes feedback and determines overall RAG status:
|
|
- **Green**: All pass, max 1 amber issue per agent (Legal amber → overall Amber)
|
|
- **Amber**: >1 actionable issue per agent, or any Legal amber
|
|
- **Red**: Any agent returns Red
|
|
|
|
### Key Data Types (`frontend/types.ts`)
|
|
- `RagStatus` - 'Red' | 'Amber' | 'Green' | 'Error'
|
|
- `OverallStatus` - 'Passed' | 'Failed' | 'Analysis Error' | 'Requires Manual Legal Review'
|
|
- `AgentReview` - Complete analysis result with all agent reviews
|
|
|
|
### State Persistence
|
|
- **Frontend**: localStorage with `barclays_modcomms_*_v3` keys
|
|
- **Backend**: PostgreSQL (SQLAlchemy async + asyncpg, Alembic migrations)
|
|
|
|
### User Roles
|
|
- **Admin** - Full access to all campaigns, Settings, Analytics, Auditing
|
|
- **Basic User** - Limited to own agency's campaigns
|
|
|
|
## Reference Documentation
|
|
|
|
Brand and channel guidelines in `reference_docs/`:
|
|
- `brand/` - Barclays/Barclaycard brand guidelines, tone of voice, design principles
|
|
- `channel/` - Digital and social media guidelines
|
|
|
|
Product requirements: `specs/Barclays_ModComms_Req_v5.md`
|