Core Entities

Tenants

Each tenant represents an institution (bank, fintech, or mobile money operator) on the platform.

Column Type Description
id uuid Primary key
name varchar Institution name
type enum bank, fintech, mmo
plan varchar Subscription tier
status enum active, suspended, onboarding
contact_email varchar Primary contact
created_at timestamp Creation date
updated_at timestamp Last modification

Tenants are provisioned via POST /api/v1/admin/tenants or the admin-jobs Cloud Run Job.

Tenant API Keys

Column Type Description
id uuid Primary key
tenant_id uuid FK to tenants
key_hash varchar SHA-256 hash of the raw key
key_prefix varchar(8) First 8 chars for identification
scopes jsonb Array of scope strings, or null for unrestricted
expires_at timestamp Optional expiration
revoked_at timestamp Revocation timestamp (soft delete)
created_at timestamp Creation date

Customers

Customers are the entities monitored by a tenant (businesses, SMEs, individuals).

Column Type Description
id uuid Primary key
tenant_id uuid FK to tenants (RLS-enforced)
external_id varchar Identifier from source system
name varchar Customer name
type enum individual, business
industry varchar Industry classification (used for seasonal adjustment)
status enum active, inactive, suspended
metadata jsonb Extensible attributes
created_at timestamp Creation date
updated_at timestamp Last modification

Accounts

Column Type Description
id uuid Primary key
tenant_id uuid FK to tenants (RLS-enforced)
customer_id uuid FK to customers
account_number varchar Account identifier (encrypted)
type enum current, savings, loan, mobile_money
currency varchar(3) ISO 4217 currency code
balance numeric Current balance
status enum active, closed, frozen
created_at timestamp Creation date
updated_at timestamp Last modification

Transactions

Column Type Description
id uuid Primary key
tenant_id uuid FK to tenants (RLS-enforced)
account_id uuid FK to accounts
customer_id uuid FK to customers
type enum credit, debit
amount numeric Transaction amount
currency varchar(3) ISO 4217 currency code
description text Transaction narrative
reference varchar External reference
counterparty varchar Counterparty identifier
transaction_date timestamp Date of transaction
created_at timestamp Import date

Audit Logs

Audit log records are immutable. There is no updated_at column.

Column Type Description
id uuid Primary key
tenant_id uuid FK to tenants
action enum Action type (e.g. compliance.sanctions_check)
description text Human-readable description
actor_type enum user, system, api_key
actor_id varchar Actor identifier
actor_name varchar Actor display name
entity_type enum Target resource type
entity_id varchar Target resource identifier
previous_state jsonb State before change
new_state jsonb State after change
changes jsonb Diff summary
request_id varchar Correlation ID
ip_address varchar Client IP
user_agent text Client user agent
metadata jsonb Additional context
created_at timestamp Event timestamp

Indexes: tenant_id, action, actor_id + actor_type, entity_id + entity_type, created_at.

Import Jobs

Tracks CSV file uploads and processing.

Column Type Description
id uuid Primary key
tenant_id uuid FK to tenants
file_name varchar Original file name
file_size integer File size in bytes
total_rows integer Detected row count
processed_rows integer Rows successfully processed
status enum uploaded, processing, completed, failed
bank_preset varchar gcb, ecobank, stanbic, arb_apex, custom
column_mapping jsonb CSV column to entity field mapping
errors jsonb Array of error messages
error_count integer Total errors
completed_at timestamp Processing completion time
created_at timestamp Upload time
updated_at timestamp Last status change

Implemented in packages/database/src/schema/ at commit 4b572c2.

results matching ""

    No results matching ""