---
title: AI Cost Tracker — Architecture
tags: [architecture, ai, cost-tracking, oliver-platform]
created: 2026-04-27
updated: 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

- [[wiki/tech-patterns/cost-tracker-integration|cost-tracker-integration]] — how to connect a new project
- [[wiki/tech-patterns/cost-tracker-pricing-sources|cost-tracker-pricing-sources]] — how pricing is maintained
- [[wiki/tech-patterns/cost-tracker-providers|cost-tracker-providers]] — billing units per AI provider
- [[wiki/concepts/preflight-record-pattern|preflight-record-pattern]] — the core usage-tracking pattern
