Architecture Overview
This document provides a high-level overview of the SEO Platform architecture.
System Architecture
┌─────────────────────────────────────────────────────────────┐
│ Frontend (React) │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ Pages │ │ Components │ │ API Client │ │
│ │ (TanStack │ │ (Tailwind) │ │ (TanStack Query) │ │
│ │ Router) │ │ │ │ │ │
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Backend (FastAPI) │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ API Routes │ │ Services │ │ Models │ │
│ │ (REST) │ │ (Business │ │ (SQLAlchemy) │ │
│ │ │ │ Logic) │ │ │ │
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌───────────┐
│ PostgreSQL│ │ OpenAI │ │ Redis │
│ (Primary │ │ API │ │ (Cache) │
│ Storage) │ │ │ │ │
└───────────┘ └───────────┘ └───────────┘
Technology Stack
Frontend
| Technology | Purpose |
|---|---|
| React 19 | UI framework |
| TypeScript 5.9 | Type safety |
| Vite | Build tool |
| TanStack Query 5 | Server state management |
| TanStack Router | Client-side routing |
| Tailwind CSS 4 | Styling |
| Lucide React | Icons |
Backend
| Technology | Purpose |
|---|---|
| Python 3.13 | Runtime |
| FastAPI | Web framework |
| SQLAlchemy 2.0 | ORM |
| Pydantic | Validation |
| Alembic | Migrations |
| asyncpg | PostgreSQL driver |
Infrastructure
| Technology | Purpose |
|---|---|
| PostgreSQL 15+ | Primary database |
| Redis | Caching (optional) |
| Docker | Containerization |
| Vercel | Frontend hosting |
Backend Modules
Core Modules
backend/app/
├── api/v1/ # REST endpoints
│ ├── auth.py # Authentication
│ ├── users.py # User management
│ ├── jobs.py # Job operations
│ ├── dedupe.py # Deduplication
│ ├── taxonomies.py # Taxonomy management
│ └── usage.py # Usage/billing
├── models/ # SQLAlchemy models
│ ├── tenancy.py # User/tenant models
│ ├── keywords.py # Keyword models
│ ├── taxonomy.py # Taxonomy models
│ ├── dedupe.py # Dedupe models
│ └── billing.py # Billing models
├── services/ # Business logic
│ ├── workflow/ # Classification, dedupe
│ ├── ingest/ # File parsing
│ └── metering_service.py
└── core/ # Config, security, DB
Module Responsibilities
| Module | Responsibility |
|---|---|
| Auth + Tenancy | User authentication, multi-tenant isolation |
| Jobs | Keyword job lifecycle management |
| Ingest | CSV parsing, normalization |
| Dedupe | Duplicate detection and resolution |
| Classification | AI-powered keyword categorization |
| Taxonomy | Category hierarchy management |
| Billing | Usage tracking, budget enforcement |
Frontend Structure
frontend/src/
├── pages/ # Route components
│ ├── LoginPage.tsx
│ ├── JobsPage.tsx
│ ├── JobDetailPage.tsx
│ └── ...
├── components/ # Reusable UI
│ ├── ui/ # Base components
│ └── ...
├── api/ # API client
│ └── client.ts
├── hooks/ # Custom hooks
└── lib/ # Utilities
Data Flow
Keyword Classification Flow
1. Upload CSV → Job created
2. Parse → Keywords extracted & normalized
3. Dedupe → Duplicates identified
4. Review → User resolves duplicates
5. Classify → AI assigns categories
6. Export → Download results
Request Flow
Browser → React → API Client → FastAPI → Service → Database
↓
OpenAI API (for classification)
Multi-Tenancy
The platform uses row-level tenant isolation:
- All tenant-specific tables include
tenant_id - API endpoints filter by authenticated user's tenant
- Database indexes include tenant_id for performance
Security Model
- Authentication: JWT tokens (30-minute expiry)
- Authorization: Role-based (user/admin)
- Data Isolation: Tenant-scoped queries
- API Security: CORS, rate limiting
Related Documentation
- Backend Documentation - Detailed backend guide
- Frontend Documentation - Detailed frontend guide
- API Reference - Complete API documentation