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

Full Entity Relationship Diagram

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

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.

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:

Admin creates key via POST /trueportai-services/api/v1/keys
Key is stored hashed in MongoDB
Client embeds key in x-api-key header or Authorization: Bearer
Middleware validates on every request
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