Architecture
Database
Five PostgreSQL schemas per tenant — what lives where and why.
Binexia uses a schema-per-tenant model in a single PostgreSQL 16 instance with pgvector. Each tenant gets five schemas that separate concerns by lifecycle and access pattern.
The Five Schemas
tenant_data — Business Records
Core domain tables specific to the vertical. For IntelliTravel: customers, bookings, destinations, suppliers, contact_history. Plus universal tables:
| Table | Purpose |
|---|---|
entities | Universal entity registry, kept in sync via sync_entity() trigger |
events | Event stream for behavioral analysis |
documents | Document metadata (files stored in MinIO) |
tags | Flexible tagging for any entity |
tenant_semantic — Semantic Model
The metadata layer that makes natural language queries work. This is the source of truth for all metric and dimension definitions.
| Table | Purpose |
|---|---|
entities | Maps domain tables to natural language names |
metrics | SQL expressions, units, format hints (e.g., COUNT(*), currency) |
dimensions | Grouping/slicing columns (time, categorical) |
vocabulary | Business terms → SQL filters (e.g., "high-value customer" → ltv_eur > 5000) |
schema_context | Auto-generated LLM prompt assembled from all above tables |
Changes to metrics flag dependent query templates for review.
tenant_config — Configuration
Platform settings, user preferences, and admin-editable configuration.
| Table | Purpose |
|---|---|
platform_settings | Key-value application settings |
llm_routing | Agent → provider + model + temperature mapping |
dashboards | Dashboard definitions with grid layout JSON |
widgets | Widget configs (type, metric, dimension, chart settings) |
users | User accounts (extends fimula-base auth) |
api_keys | API key management |
tenant_agent_state — Agent Runtime
Session state, outputs, and notification history.
| Table | Purpose |
|---|---|
agent_sessions | Conversation sessions with context |
agent_outputs | Agent results (scores, alerts, forecasts) with expiry |
scheduled_jobs | Cron definitions for scheduled agents |
notifications | In-app and email notification log |
tenant_knowledge — Document Intelligence
Managed by Dify. Stores chunked document embeddings.
| Table | Purpose |
|---|---|
document_chunks | Embeddings with pgvector (embedding_model + embedding_dimensions columns for versioning) |
knowledge_sources | Source document metadata and indexing status |
Database Users
Two users with different privilege levels:
| User | Access | Used by |
|---|---|---|
ubios_reader | Read-only, statement timeouts | AnalyticsAgent SQL execution, Agno queries |
ubios_app | Read-write | Behavioral scoring, extraction, state updates |
Info
The IP testing compose file uses postgres for both users (simpler setup). Production uses separate ubios_reader and ubios_app accounts with restricted grants.
Entity Sync Trigger
The sync_entity() trigger function keeps the tenant_data.entities table in sync with domain tables. When a row is inserted/updated/deleted in a domain table (e.g., customers), the trigger automatically updates the universal entities registry. This ensures agents always have a current view of available data.
Additional Databases
Two extra databases share the PostgreSQL instance:
ubios_dify— Dify's internal state (datasets, documents, chunking progress)ubios_metabase— Metabase's internal state (queries, dashboards, user preferences)