modcomms/CLAUDE.md

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

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

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

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