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 <noreply@anthropic.com>
This commit is contained in:
michael
parent
c1030ee292
commit
e094014dbe
2 changed files with 99 additions and 20 deletions
83
CLAUDE.md
83
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`
|
||||
|
|
|
|||
36
README.md
36
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`
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue