# GEO Platform - AI Context

## Project Overview
GEO (Generative Engine Optimization) SaaS platform that helps brands get cited by AI search engines (ChatGPT, Perplexity, DeepSeek, etc.).

## Tech Stack
- Backend: FastAPI + SQLAlchemy 2.0 (async) + PostgreSQL 15 + Redis 7
- Frontend: Next.js 14 + React 18 + TypeScript + Tailwind CSS + shadcn/ui
- AI: Multi-LLM provider (DeepSeek, OpenAI, etc.) + RAG knowledge base
- Infrastructure: Docker Compose + Prometheus metrics

## Architecture
- Backend API: 33 route modules under backend/app/api/
- Agent Framework: 8 agents (CitationDetector, ContentGenerator, DeAIAgent, GEOOptimizer, MonitorAgent, SchemaAdvisor, CompetitorAnalyzer, TrendAgent)
- Data Models: 35 models under backend/app/models/
- Services: 80+ service files organized by domain under backend/app/services/
- Repositories: 12 repository files under backend/app/repositories/ for data access
- Frontend: 25+ pages under frontend/app/(dashboard)/
- Frontend API Clients: 27 modules under frontend/lib/api/

## Key Patterns
- Repository pattern for data access (backend/app/repositories/)
- Agent Framework: BaseAgent abstract class → concrete agents, Dispatcher + Registry + Redis Queue
- Shared BrandScoringDataService for V2 5-dimension scoring
- Content Pipeline: Generate → DeAI → GEO Optimize → HTML Output
- GEO Workflow: Diagnosis → Strategy → Plan → Content Generation → Monitoring

## API Conventions
- All routes under /api/v1/ prefix
- Authentication via JWT Bearer token (get_current_user dependency)
- Pydantic schemas for request/response validation
- Async SQLAlchemy ORM with AsyncSession

## Frontend Conventions
- API clients in frontend/lib/api/ using fetchWithAuth from client.ts
- Barrel export in frontend/lib/api/index.ts
- Types co-located with API modules
- Dashboard pages under frontend/app/(dashboard)/dashboard/

## Environment
- Backend runs on port 8000
- Frontend runs on port 3001 (dev)
- PostgreSQL on port 5432
- Redis on port 6379
- .env.example has all required variables

## Common Commands
- Start backend: cd geo/backend && python3 -m uvicorn app.main:app --reload --port 8000
- Start frontend: cd geo/frontend && npm run dev
- Start all agents: cd geo/backend && python3 -m app.agent_framework.standalone all
- Docker: docker-compose up -d

## Important Notes
- SEOOptimizer in code actually performs GEO optimization, not traditional SEO
- content.py (content generation) vs contents.py (content management) - different modules
- Analytics endpoints all require authentication via _get_org_id or get_current_user
- CORS: dev mode uses allow_origins=["*"], production must restrict
- Brand scoring uses V2 5-dimension system: mention_rate, recommendation_rank, sentiment_score, citation_quality, competitive_position