# Fusion API - Design Document

**Goal:** Build a standalone Odoo 19 module (`fusion_api`) serving as the central hub for API key management, usage tracking, rate limiting, and access control across all Fusion products.

**Architecture:** Dedicated Odoo application with a provider/key vault, auto-detected consumer modules, per-module and per-user access rules with budget caps and rate limits, granular usage logging with daily aggregation, and an OWL dashboard. Other Fusion modules call `self.env['fusion.api.service']` methods which handle key retrieval, access checks, usage logging, and API execution.

**Tech Stack:** Odoo 19, Python 3.12, OWL 2, OpenAI SDK (optional), Anthropic SDK (optional)

---

## Scope

### In Scope
- Shared service keys: OpenAI, Anthropic, Google Maps, Twilio
- OAuth services: Google OAuth, Microsoft OAuth
- Usage tracking: per module, per feature, per user, per AI model
- Rate limiting: global budgets, per-module budgets, RPM/RPD limits, per-user limits
- Access control: enable/disable per module, per user blocking
- Auto-detection of consumer modules on first API call
- OWL dashboard with usage stats and charts

### Out of Scope
- Shipping carrier credentials (stay on `delivery.carrier`)
- Payment provider credentials (stay on `payment.provider`)
- Migrating existing modules (phased rollout later)

---

## Data Model

### `fusion.api.provider`
API service providers (OpenAI, Anthropic, Google Maps, etc.). Pre-seeded with known providers.

### `fusion.api.key`
Credential storage per provider. Supports simple API keys and OAuth (client_id/secret/tokens). Masked in UI, system-group access only. Multiple keys per provider with default selection.

### `fusion.api.consumer`
Auto-detected Fusion modules. Created automatically when a module first calls the API service. Links to `ir.module.module`. Master kill switch per module.

### `fusion.api.access`
Access rules linking consumers to providers. Configures: enable/disable, monthly/daily budget caps, RPM/RPD rate limits. Computed fields show current usage and budget percentage.

### `fusion.api.user.limit`
Optional per-user overrides. Monthly budget, daily request cap, manual block toggle.

### `fusion.api.usage`
Individual API call log. Full granularity: consumer, provider, user, feature, model, tokens, cost, response time, status.

### `fusion.api.usage.daily`
Cron-aggregated daily summaries. Same dimensions with summed totals. Used for reporting and charts.

---

## Service Layer

`fusion.api.service` (AbstractModel) provides:
- `call_openai()` - Make OpenAI chat completion calls
- `call_anthropic()` - Make Anthropic messages API calls
- `get_api_key()` - Get raw API key for any provider (for non-chat uses like Google Maps)
- Auto-registration of consumers on first call
- Access control checks (budget, rate limit, user limit)
- Usage logging with cost estimation
- Key validation

---

## Migration Path

1. Module is standalone - no existing modules need changes to install it
2. Existing modules will be migrated one-by-one to use `fusion.api.service` instead of their own API key fields
3. During migration, modules can check `fusion_api` first and fall back to their own keys

---

## Security Groups

- `fusion_api.group_user` - View usage data
- `fusion_api.group_manager` - Manage providers, consumers, access rules
- `fusion_api.group_admin` - View/edit API keys, full system access