🏗️ Architecture

IntentScope is composed of four services that work together to provide intelligent, observable LLM routing.

System Diagram

┌─────────────────────────────────────────────────────┐
│           Next.js Frontend (port 3000)              │
│   Dashboard │ API Keys │ Playground │ Analytics     │
└──────────────────────┬──────────────────────────────┘
                       │ Clerk JWT
┌──────────────────────▼──────────────────────────────┐
│           FastAPI Gateway (port 8000)               │
│  Auth → Intent Analysis → Budget → Model Router     │
└────────┬─────────────────────────┬──────────────────┘
         │                         │
    ┌────▼────┐           ┌────────▼──────────────┐
    │ Postgres │           │ Groq / Mistral / Ollama│
    │  (5434)  │           │     LLM Providers      │
    └────▲────┘           └───────────────────────┘
         │
    ┌────┴─────────┐
    │ Go Validator  │
    │   (port 8081) │
    └──────────────┘

Services

Service	Stack	Port	Role
Frontend	Next.js 15, React 19, Tailwind CSS 4, Clerk	`3000`	Dashboard UI
API Gateway	FastAPI, LiteLLM, SQLAlchemy (async), Alembic	`8000`	Core gateway
Token Validator	Go, pgx	`8081`	Fast-path key validation
Database	PostgreSQL 15	`5434`	Persistent storage

Request Lifecycle

Every request through IntentScope follows this pipeline:

1. Client sends POST /v1/chat/completions
        │
2. verify_virtual_key  ←── checks DB / Go validator
        │
3. analyze_intent      ←── Mistral classifies the prompt
        │                   category + risk_level + estimated_tokens
4. check_budget        ←── enforces token limits per key
        │
5. determine_target_model  ←── Groq / Mistral / Ollama
        │                      light or heavy tier based on intent
6. acompletion (LiteLLM)   ←── actual LLM call
        │
7. record_usage + log  ←── writes to Postgres
        │
8. Return response to client

Data Models

`User`

id — Clerk user ID
default_model — saved LLM preference
strict_budget — enforce hard token limits
auto_purge_sensitive — delete sensitive logs after 24h

`VirtualKey`

key — hashed API key string
user_id — owner
token_limit — max tokens
tokens_used — running total
expires_at — optional expiry
is_active — revocation flag

`RequestLog`

model — which model handled the request
intent_category — classified intent
risk_level — low / medium / high
prompt_tokens, completion_tokens, total_tokens
latency_ms — end-to-end latency
status_code

Directory Structure

intent-scope/
├── frontend/                   # Next.js 15 dashboard
│   └── src/app/dashboard/      # Overview, Keys, Playground, Usage, Settings
│
├── backend-python/             # FastAPI gateway
│   └── app/
│       ├── core/               # Auth, database, security
│       ├── models/             # ORM models
│       ├── routers/            # REST endpoints
│       ├── schemas/            # Pydantic schemas
│       └── services/           # intent_analyzer, budget, model_router
│
├── backend-go/                 # Token validator
│   └── main.go                 # /validate endpoint
│
├── docs/                       # This documentation site
├── docker-compose.yml          # Dev infra
└── docker-compose.prod.yml     # Production stack

Getting Started Configuration