59 lines
2.7 KiB
Markdown
59 lines
2.7 KiB
Markdown
# 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
|