fischer
/
geo
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
geo/CLAUDE.md

2.7 KiB
Raw Blame History

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