# Data Model

TruePortAI's data architecture is designed for **multi-tenancy**, **strict isolation**, and **full auditability**. The model spans two distinct service domains: the **Platform Backend** (identity, billing, configuration) and **TruePortAI Services** (gateway, analytics, governance).

---

## Domain Overview

```mermaid
graph LR
    subgraph "platform-backend DB (saas_platform_core)"
        direction TB
        U[User]
        T[Tenant]
        M[Membership]
        P[Product]
        PL[Plan]
        S[Subscription]
        INV[Invite]
        CFG[ConfigGroup]
        CI[ConfigItem]
        OTP[OTP]
        SP[StorageProvider]
    end

    subgraph "trueportai-services DB (trueport_ai)"
        direction TB
        AK[APIKey]
        UL[UsageLog]
        VIO[Violation]
        POL[PolicyRule]
    end

    T -->|isolated tenant DB| AK
    T -->|isolated tenant DB| UL
    T -->|isolated tenant DB| VIO

    style U fill:#4A90D9,color:#fff
    style T fill:#7B68EE,color:#fff
    style AK fill:#50C878,color:#fff
    style VIO fill:#FF6B6B,color:#fff
```

---

## Full Entity Relationship Diagram

```mermaid
erDiagram
    %% ── Platform Domain ──────────────────────────────────────

    TENANT {
        string  id          PK   "Short UUID (public)"
        string  name
        string  slug             "Unique URL-safe identifier"
        string  billing_email
        string  status           "active | suspended | archived"
        string  owner_id    FK   "→ USER"
        string  subscription_id  FK "→ SUBSCRIPTION"
        datetime created_at
    }

    USER {
        string  id              PK  "Short UUID"
        string  email               "Unique"
        string  password_hash       "Argon2"
        string  first_name
        string  last_name
        boolean is_platform_admin
        string  auth_provider       "local | google | linkedin | github"
        datetime created_at
    }

    MEMBERSHIP {
        string  id          PK
        string  tenant_id   FK  "→ TENANT"
        string  user_id     FK  "→ USER"
        string  role            "owner | admin | member | viewer"
        string  status          "active | invited | disabled"
        datetime joined_at
    }

    INVITE {
        string   id         PK
        string   tenant_id  FK  "→ TENANT"
        string   email
        string   role           "proposed role"
        string   invited_by FK  "→ USER"
        string   token          "Secure random token"
        datetime expires_at
    }

    PRODUCT {
        string   id          PK
        string   name
        string   slug
        string   description
        datetime created_at
        datetime updated_at
    }

    PLAN {
        string  id          PK
        string  product_id  FK  "→ PRODUCT"
        string  name
        string  description
        float   price           "In USD"
        string  billing_cycle   "MONTHLY | YEARLY"
        array   feature_ids
        datetime created_at
    }

    SUBSCRIPTION {
        string   id         PK
        string   tenant_id  FK  "→ TENANT"
        string   plan_id    FK  "→ PLAN"
        string   status         "ACTIVE | CANCELLED | EXPIRED | TRIAL"
        datetime start_date
        datetime end_date
        datetime created_at
    }

    CONFIG_GROUP {
        string  grp_id      PK
        string  type            "SYSADMIN | TENANT"
        string  grp_title
        string  grp_desc
    }

    CONFIG_SECTION {
        string  sec_id      PK
        string  grp_id      FK  "→ CONFIG_GROUP"
        string  header_title
        string  footer_title
    }

    CONFIG_ITEM {
        string  cfg_id      PK
        string  sec_id      FK  "→ CONFIG_SECTION"
        string  key             "Dotted path e.g. auth.mfa_enforced"
        string  lbl             "Display label"
        string  val             "Current value (string/JSON)"
        string  gen_type        "boolean | string | number | json"
        boolean mod             "Modifiable by tenant?"
        string  scope           "GLOBAL | TENANT | PRODUCT"
        string  target_id
        string  env_id          "prod | staging | dev"
        boolean is_locked
    }

    OTP {
        string   id         PK
        string   user_id    FK  "→ USER"
        string   code
        datetime expires_at
        boolean  used
    }

    STORAGE_PROVIDER {
        string  id          PK
        string  tenant_id   FK  "→ TENANT"
        string  provider        "S3 | AZURE | GCP | LOCAL"
        string  bucket
        string  region
        object  credentials     "Encrypted provider-specific fields"
        datetime created_at
    }

    %% ── TruePortAI Domain ────────────────────────────────────

    API_KEY {
        string   id             PK
        string   key                "sk-{random} — indexed"
        string   owner_id       FK  "→ USER"
        string   tenant_id      FK  "→ TENANT"
        boolean  is_active
        int      rate_limit_rpm     "Default: 60"
        datetime created_at
    }

    USAGE_LOG {
        string   id             PK
        datetime timestamp
        string   api_key        FK  "→ API_KEY"
        string   tenant_id      FK  "→ TENANT"
        string   path
        string   method             "GET | POST"
        int      status_code
        float    latency_ms
        int      request_size_bytes
        int      response_size_bytes
        string   provider           "openai | anthropic | google | azure"
        string   model              "e.g. gpt-4o, claude-3-5-sonnet"
        int      prompt_tokens
        int      completion_tokens
        float    cost_usd
    }

    VIOLATION {
        string   id             PK
        string   usage_log_id   FK  "→ USAGE_LOG"
        string   tenant_id      FK  "→ TENANT"
        string   type               "pii | bias | injection | exfiltration"
        string   severity           "critical | high | medium | low"
        string   direction          "request | response"
        string   description
        object   redacted_payload   "Scrubbed content snapshot"
        string   model_version      "Detecting ML model version"
        boolean  auto_blocked
        datetime detected_at
    }

    POLICY_RULE {
        string   id             PK
        string   tenant_id      FK  "→ TENANT"
        string   name
        string   action             "block | redact | alert | log"
        string   trigger_type       "pii | toxicity | injection | keyword | regex"
        string   pattern            "Regex or keyword"
        boolean  is_active
        int      priority
        datetime created_at
    }

    %% ── Relationships ────────────────────────────────────────

    TENANT        ||--o{  MEMBERSHIP       : "has many"
    TENANT        ||--o{  INVITE           : "issues"
    TENANT        ||--o{  SUBSCRIPTION     : "has"
    TENANT        ||--|{  STORAGE_PROVIDER : "configures"
    TENANT        ||--o{  API_KEY          : "owns"
    TENANT        ||--o{  USAGE_LOG        : "generates"
    TENANT        ||--o{  VIOLATION        : "receives"
    TENANT        ||--o{  POLICY_RULE      : "defines"
    USER          ||--o{  MEMBERSHIP       : "belongs via"
    USER          ||--o{  API_KEY          : "manages"
    USER          ||--o{  OTP              : "requests"
    PLAN          ||--o{  SUBSCRIPTION     : "governs"
    PRODUCT       ||--o{  PLAN             : "has"
    CONFIG_GROUP  ||--o{  CONFIG_SECTION   : "contains"
    CONFIG_SECTION||--o{  CONFIG_ITEM      : "contains"
    API_KEY       ||--o{  USAGE_LOG        : "generates"
    USAGE_LOG     ||--o{  VIOLATION        : "triggers"
```

---

## Platform Backend Entities

### Tenant
The primary organizational unit. Every resource is scoped to a tenant.

| Field | Type | Notes |
|-------|------|-------|
| `id` | Short UUID | Public-facing identifier |
| `slug` | String | URL-safe, globally unique |
| `status` | Enum | `active`, `suspended`, `archived` |
| `owner_id` | Ref → User | Creator and primary owner |

**Multi-Tenancy Pattern**: Tenant isolation is enforced at the middleware layer. The `TenantContextMiddleware` resolves the tenant from the JWT claim (`tid`), subdomain, or `X-Tenant-Slug` header. No endpoint in the service API requires an explicit `tenant_id` parameter.

---

### User
Global identity that can belong to multiple tenants.

| Field | Type | Notes |
|-------|------|-------|
| `id` | Short UUID | Never expose MongoDB `_id` |
| `email` | EmailStr | Globally unique |
| `password_hash` | String | Argon2 hash |
| `is_platform_admin` | Boolean | Grants full system access |
| `auth_provider` | Enum | `local`, `google`, `linkedin`, `github` |

---

### Membership
The join table between User and Tenant, carrying the user's role within that tenant.

| Role | Permissions |
|------|-------------|
| `owner` | Full control, billing, delete tenant |
| `admin` | Manage members, keys, policy rules |
| `member` | Create/read API keys, view analytics |
| `viewer` | Read-only access to analytics |

---

### Subscription & Billing

```mermaid
stateDiagram-v2
    [*] --> TRIAL : New tenant signup
    TRIAL --> ACTIVE : Billing card added
    ACTIVE --> PAST_DUE : Payment fails
    PAST_DUE --> ACTIVE : Payment recovered
    PAST_DUE --> CANCELLED : Grace period expires
    ACTIVE --> CANCELLED : User cancels
    CANCELLED --> [*]
```

---

### Configuration System

The configuration model uses a **hierarchical override chain**:

```
Bootstrap Default → System DB (Global) → Tenant DB Override
```

Each `ConfigItem` stores a `scope` and optional `is_locked` flag. When `is_locked = true`, tenant admins cannot override the value.

```mermaid
graph TD
    A[Bootstrap YAML / Env Vars] -->|lowest priority| B[System DB Config]
    B --> C{Is Tenant Override set?}
    C -->|No| D[Use System Value]
    C -->|Yes| E{Is Locked?}
    E -->|Yes| D
    E -->|No| F[Use Tenant Value]
```

---

## TruePortAI Service Entities

### API Key
The authentication credential for client applications connecting to the Gateway.

| Field | Type | Notes |
|-------|------|-------|
| `key` | String | Format: `sk-{32-char token}` |
| `rate_limit_rpm` | Int | Default 60 req/min; enforced via Redis |
| `is_active` | Boolean | Soft-disable without key rotation |

**Key Lifecycle**:
1. Admin creates key via `POST /trueportai-services/api/v1/keys`
2. Key is stored hashed in MongoDB
3. Client embeds key in `x-api-key` header or `Authorization: Bearer`
4. Middleware validates on every request
5. Key can be deactivated in-place (`is_active = false`)

---

### Usage Log
The immutable audit record for every AI interaction.

| Field | Type | Notes |
|-------|------|-------|
| `provider` | Enum | `openai`, `anthropic`, `google`, `azure` |
| `model` | String | e.g., `gpt-4o`, `claude-3-5-sonnet` |
| `prompt_tokens` | Int | Extracted from provider response |
| `completion_tokens` | Int | For cost calculation |
| `cost_usd` | Float | Computed per provider pricing |
| `latency_ms` | Float | End-to-end proxy + provider time |

**Storage Strategy**:
- **MongoDB** (`usage_logs` collection): Hot data, last 30 days, indexed for dashboard queries.
- **S3/Blob** (`{tenant-id}/logs/{YYYY/MM/DD}/{log-id}.json`): Cold archive, unlimited retention, raw payload included.

---

### Violation
Generated by the Analytics Engine when an ML model or policy rule triggers.

| Field | Type | Notes |
|-------|------|-------|
| `type` | Enum | `pii`, `bias`, `injection`, `exfiltration` |
| `severity` | Enum | `critical`, `high`, `medium`, `low` |
| `direction` | Enum | `request` (user prompt) or `response` (LLM reply) |
| `auto_blocked` | Boolean | True if request/response was stopped |
| `redacted_payload` | Object | The scrubbed snapshot — no raw PII stored |

---

### Policy Rule
Tenant-defined governance rules that augment the ML model detections.

| Action | Behavior |
|--------|----------|
| `block` | Request/response is stopped; 403 returned |
| `redact` | Matching tokens replaced with `[REDACTED]` |
| `alert` | Violation logged and notification sent |
| `log` | Silent audit only |

---

## Storage Layout (S3 / Azure Blob)

```
{tenant-slug}/
├── logs/
│   └── {YYYY}/
│       └── {MM}/
│           └── {DD}/
│               └── {usage-log-id}.json     # Full raw interaction
├── violations/
│   └── {violation-id}.json                 # Violation snapshot
└── exports/
    └── {report-id}.csv                     # On-demand exports
```

---

## Database Collections Summary

### `saas_platform_core` (Global — MongoDB Atlas)

| Collection | Purpose |
|------------|---------|
| `users` | Global user accounts |
| `tenants` | Organization records |
| `tenant_memberships` | User↔Tenant role assignments |
| `invites` | Pending email invitations |
| `products` | SaaS product catalog |
| `plans` | Pricing tiers |
| `subscriptions` | Active billing contracts |
| `configuration_groups` | Config UI layout |
| `configurations` | Dynamic settings key-value store |
| `otps` | One-time passwords (TTL index) |
| `storage_providers` | Per-tenant storage credentials |

### `trueport_ai` (Per-Tenant — MongoDB Atlas)

| Collection | Purpose |
|------------|---------|
| `api_keys` | TruePortAI authentication credentials |
| `usage_logs` | Hot audit trail (30-day retention) |
| `violations` | Detected policy and ML violations |
| `policy_rules` | Custom governance rules |