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