From e094014dbe988838ac199efab38afc5c9c01d2bd Mon Sep 17 00:00:00 2001 From: michael Date: Sat, 24 Jan 2026 09:42:39 -0600 Subject: [PATCH] Improve CLAUDE.md and README.md with backend documentation - 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 --- CLAUDE.md | 83 ++++++++++++++++++++++++++++++++++++++++++------------- README.md | 36 +++++++++++++++++++++++- 2 files changed, 99 insertions(+), 20 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 66c15d1..e208366 100755 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,12 +2,17 @@ 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 @@ -16,39 +21,79 @@ 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 -Create `frontend/.env.local` with: +### 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 Structure (`frontend/`) -- **App.tsx** - Main application component, handles routing between views and manages global state (campaigns, proofs, flagged/resolved/error items) -- **components/** - React components for each view and UI element -- **services/geminiService.ts** - Google Gemini AI integration for proof analysis +### 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 AI agents analyze each proof: -- **Legal Agent** - Checks advertising standards, disclaimers, financial promotion detection -- **Brand Agent** - Verifies brand guidelines (logos, colors, branding) -- **Tone Agent** - Analyzes copy clarity, brand personality, grammar -- **Channel Agent** - Assesses technical suitability for digital channels +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 -A **Lead Agent** mediates specialist feedback and determines overall RAG status: -- Green: All pass, max 1 amber issue per agent (except Legal amber triggers overall Amber) -- Amber: >1 actionable issue per agent, or any Legal amber -- Red: Failure from any agent +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 (`types.ts`) -- `AgentReview` - Complete analysis result with all agent reviews +### 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 -Application state persists to localStorage with `barclays_modcomms_*_v3` keys. Large preview URLs are stripped before saving to avoid quota errors. +- **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 @@ -56,8 +101,8 @@ Application state persists to localStorage with `barclays_modcomms_*_v3` keys. L ## Reference Documentation -Brand and channel guidelines are in `reference_docs/`: +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 specification: `specs/Barclays_ModComms_Req_v5.md` +Product requirements: `specs/Barclays_ModComms_Req_v5.md` diff --git a/README.md b/README.md index 9a5b935..e03417b 100755 --- a/README.md +++ b/README.md @@ -54,6 +54,8 @@ Each agent returns a RAG status (Red/Amber/Green) with detailed feedback: - FastAPI (Python) - WebSocket for real-time communication - Google Gemini 2.5 Flash for AI analysis +- PostgreSQL with SQLAlchemy async + asyncpg +- Alembic for database migrations - Pydantic for data validation ## Project Structure @@ -69,9 +71,13 @@ barclays_modcomms/ ├── backend/ # FastAPI server │ ├── app/ │ │ ├── agents/ # AI agent implementations +│ │ ├── api/ # REST endpoints +│ │ ├── models/ # SQLAlchemy ORM and Pydantic schemas +│ │ ├── repositories/ # Data access layer │ │ ├── services/ # Gemini API, analysis orchestration │ │ ├── websocket/ # Real-time communication │ │ └── main.py # FastAPI entry point +│ ├── alembic/ # Database migrations │ └── requirements.txt │ ├── reference_docs/ # Brand & channel guidelines @@ -138,6 +144,10 @@ The application will be available at `http://localhost:3000`. | Variable | Description | Default | |----------|-------------|---------| | `GEMINI_API_KEY` | Google Gemini API key | Required | +| `DATABASE_URL` | PostgreSQL connection string | Required | +| `AZURE_TENANT_ID` | Azure AD tenant ID | Required for auth | +| `AZURE_CLIENT_ID` | Azure AD client ID | Required for auth | +| `DISABLE_AUTH` | Disable auth for local dev | `false` | | `CORS_ORIGINS` | Allowed CORS origins | `http://localhost:3000` | | `HOST` | Server host | `0.0.0.0` | | `PORT` | Server port | `8000` | @@ -235,6 +245,21 @@ npm run preview # Preview build uvicorn app.main:app --reload # Dev server with hot reload ``` +### Database Migrations + +```bash +cd backend + +# Run all pending migrations +alembic upgrade head + +# Create a new migration after model changes +alembic revision --autogenerate -m "description of changes" + +# Downgrade one revision +alembic downgrade -1 +``` + ## Reference Documentation The `reference_docs/` directory contains brand and channel guidelines used by the AI agents: @@ -260,7 +285,16 @@ The `reference_docs/` directory contains brand and channel guidelines used by th ## Data Persistence -Application state is persisted to localStorage with the following keys: +### Backend (PostgreSQL) + +Primary data storage uses PostgreSQL with SQLAlchemy async ORM: +- Campaigns, proofs, and analysis results +- User accounts and agency associations +- Audit trail for flagged issues and resolutions + +### Frontend (localStorage) + +Client-side caching uses localStorage with the following keys: - `barclays_modcomms_campaigns_v3` - `barclays_modcomms_campaign_proofs_v3` - `barclays_modcomms_flagged_items_v3`