Skip to main content

Data Model

II-Agent uses PostgreSQL with SQLAlchemy 2.0 async patterns.

Shared ORM Conventions​

  • Most entities inherit UUID primary keys from the common base.
  • created_at and updated_at timestamps come from the shared ORM base.
  • Foreign keys use UUIDs consistently across domains.
  • A few log/message tables use BigInteger autoincrement IDs where append-heavy behavior makes that appropriate.

Main Table Families​

Identity and auth​

  • users
  • api_keys

Sessions and chat​

  • sessions
  • session_pins
  • session_wishlists
  • chat_messages
  • chat_summaries
  • chat_runs
  • provider container/file/vector-store tables

Execution and observability​

  • run_tasks
  • task_logs
  • agent_run_tasks
  • agent_run_messages
  • application_events

Billing​

  • billing_transactions
  • credit_balances
  • credit_transactions

Files and content​

  • user and session assets
  • slide_contents
  • slide_versions
  • slide_templates
  • media_templates
  • storybooks
  • storybook_pages

Projects and integrations​

  • projects
  • deployment, database, and subdomain tables
  • connector and Composio profile tables
  • Apple credential tables

Relationship Patterns​

At a high level:

  • users own sessions, balances, files, and billing records
  • sessions own messages, runs, pins, wishlists, and events
  • projects own deployments, databases, and domains
  • storybooks own pages and inter-page links
  • slide contents own versions

Migration Model​

  • Alembic manages schema changes.
  • Startup can apply migrations automatically unless explicitly skipped.
  • Schema review matters because the platform spans agent execution, product features, and billing.

Design Notes​

The standalone docs/database-design.md source adds more detail around:

  • index strategy
  • JSONB usage
  • optimistic locking
  • FK/cascade tradeoffs
  • review items and operational caveats

This Docusaurus page is the working summary; the root design document remains the deeper reference.