| title |
tags |
created |
updated |
| AI Cost Tracker — Architecture |
| architecture |
| ai |
| cost-tracking |
| oliver-platform |
|
2026-04-27 |
2026-04-27 |
AI Cost Tracker
Centralised shared service that tracks AI API spend across all Oliver projects. Every project that calls Gemini, ElevenLabs, Google Cloud TTS, or other paid AI APIs sends usage events here.
Live URLs
| Environment |
URL |
| Dev (optical-dev) |
https://optical-dev.oliver.solutions/cost-tracker/ |
| API health |
https://optical-dev.oliver.solutions/cost-tracker/v1/health |
| API docs |
https://optical-dev.oliver.solutions/cost-tracker/v1/docs |
| Prod (future) |
https://cost.oliver.agency/ |
Repo: git@bitbucket.org:zlalani/ai-cost-tracker.git
Why it exists
Oliver runs multiple projects (video-accessibility, One2Edit, Box-pipelines …) all consuming paid AI APIs. Without centralised tracking: no visibility into total spend, no per-client cost attribution, no budget enforcement.
Architecture diagram
┌──────────────────────────────────┐ ┌────────────────────────────────────┐
│ Any Oliver Project │ │ ai-cost-tracker │
│ (e.g. video-accessibility) │ POST │ git@bitbucket.org:zlalani/... │
│ │ /v1/ │ │
│ AI call sites │ preflt │ FastAPI + MongoDB + Redis + React │
│ (Gemini, ElevenLabs, GCP TTS) │────────►│ POST /v1/preflight │
│ │ │ │ POST /v1/usage/record │
│ Direct HTTP calls (httpx) │ │ POST /v1/users/upsert │
│ - POST /v1/preflight │◄────────│ POST /v1/projects/upsert │
│ - POST /v1/usage/record │ │ │
│ - SQLite outbox + retry │ │ Admin UI (Microsoft SSO) │
└──────────────────────────────────┘ │ Workspaces / Teams / Projects │
│ Pricing + LiteLLM auto-sync │
│ Budgets + email alerts │
│ Dashboard + Pivot analytics │
└────────────────────────────────────┘
Key design decisions
| Decision |
Choice |
Why |
| Deployment |
Separate repo + Docker Compose on optical-dev |
Clean isolation, independent scaling |
| Org hierarchy |
Workspace → Team → Project |
Matches Oliver agency structure |
| User ownership |
Each project owns users; lazy mirror in shared |
No SSO migration needed |
| Pricing |
LiteLLM auto-sync + YAML (non-LLM) + admin override |
Auto-updated for LLMs, manual for chars |
| Transport |
Sync HTTP + SQLite outbox fallback |
Never breaks the AI pipeline |
| Budget enforcement |
Hard limits via preflight check |
allow=false before call is made |
| Auth (projects) |
API key per project (X-API-Key header) |
Simple, revocable, auditable |
| Auth (admins) |
Microsoft SSO (+ dev login for testing) |
Consistent with all Oliver projects |
| Integration |
Direct HTTP calls from client projects |
No SDK package to maintain/publish |
Org hierarchy
Workspace (e.g. "Ford", "H&M", "Oliver Internal")
└── Team (e.g. "Video", "Localization", "QC")
└── Project (e.g. "Ford Q3 Campaign", "H&M Spring 2026")
└── Job / event (individual AI call)
Users live in each project (video-accessibility, etc.) and are lazily mirrored into the cost-tracker when their first usage event arrives.
Tech stack
- Backend: FastAPI + MongoDB 7 + Redis 7 + Celery (worker + beat)
- Frontend: React 18 + Vite + TypeScript — nginx inside Docker
- Auth admin: Microsoft Azure AD OIDC + dev login (APP_ENV=dev only)
- Deploy: Docker Compose on optical-dev, Apache reverse proxy at
/cost-tracker/
Docker Compose services
| Service |
Port |
Role |
api |
8003→8001 |
FastAPI + uvicorn (2 workers) |
frontend |
5174→80 |
React SPA + nginx |
mongodb |
internal |
MongoDB 7 |
redis |
internal |
Redis 7 |
celery-worker |
— |
Async task processing |
celery-beat |
— |
Scheduled tasks (pricing sync 02:00 UTC) |
API endpoints (project-facing, X-API-Key auth)
| Method |
Path |
Purpose |
POST |
/v1/preflight |
Check budget, get request_id |
POST |
/v1/usage/record |
Record actual AI call cost |
POST |
/v1/users/upsert |
Create/update user mirror |
POST |
/v1/projects/upsert |
Create/update project mirror |
GET |
/v1/health |
Liveness check |
Related articles
