# Zo Database Schema Diagram

## Entity Relationships

```
┌──────────────────────────────────────────────────────────────────────────┐
│                              USERS (8.9k)                                 │
│  id, email, canonical_email, stripe_customer_id, phone_number,           │
│  given_name, family_name, referrer_handle, created_at                    │
└───────────────────────────────────┬──────────────────────────────────────┘
                                    │ 1:N
                    ┌───────────────┼───────────────┐
                    │               │               │
                    ▼               ▼               ▼
        ┌───────────────┐  ┌───────────────┐  ┌─────────────────┐
        │   HOSTS       │  │  CONNECTIONS  │  │  USER_PROFILES  │
        │   (8.4k)      │  │   (7.8k)      │  │    (8.4k)       │
        │               │  │               │  │                 │
        │ domain_prefix │  │ app           │  │ utm_source_*    │
        │ display_name  │  │ permission    │  │ persona_*       │
        │ keepalive     │  │ pd_conn_id    │  │ promo_codes     │
        └───────┬───────┘  └───────────────┘  └─────────────────┘
                │ 1:N
    ┌───────────┼───────────┬───────────────┬───────────────┐
    │           │           │               │               │
    ▼           ▼           ▼               ▼               ▼
┌─────────┐ ┌─────────┐ ┌─────────┐  ┌───────────┐  ┌─────────────┐
│ CONVER- │ │ IMAGES  │ │ SUBS    │  │ SERVICES  │  │ SPACE_ROUTES│
│ SATIONS │ │ (178MB) │ │ (8.6k)  │  │           │  │             │
│ (92MB)  │ │         │ │         │  │ port      │  │ path        │
│         │ │ memo    │ │ plan    │  │ entrypoint│  │ route_type  │
│ type    │ │ parent  │ │ status  │  │ name      │  │ public      │
│ title   │ │         │ │ stripe  │  │           │  │ code        │
└────┬────┘ └─────────┘ └─────────┘  └───────────┘  └─────────────┘
     │ 1:N
     ├─────────────────────┐
     │                     │
     ▼                     ▼
┌────────────────┐  ┌─────────────────────┐
│   MESSAGES     │  │   TOOL_MESSAGES     │
│   (34MB)       │  │   (8.7GB) ⚠️        │
│                │  │                     │
│ sequence_id    │  │ tool_name           │
│ event_type     │  │ tool_args (jsonb)   │
│ role           │  │ tool_result (jsonb) │
│ data (jsonb)   │  │ tool_timestamp      │
└────────────────┘  └─────────────────────┘
```

## Smaller Reference Tables

```
┌─────────────────────────────────────────────────────────────────┐
│ PUB_* Tables (Public/Shared Content)                            │
├───────────────────┬───────────────────┬─────────────────────────┤
│ pub_conversations │ pub_personas      │ pub_prompts             │
│ (shared chats)    │ (shared personas) │ (prompt library)        │
└───────────────────┴───────────────────┴─────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ Stripe Tables                                                   │
├───────────────────────────────┬─────────────────────────────────┤
│ stripe_payment_links          │ stripe_checkout_sessions        │
│ (product, price, link)        │ (completed purchases)           │
└───────────────────────────────┴─────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ Loom Tables (Workflow Planning)                                 │
├───────────────────────────────┬─────────────────────────────────┤
│ loom_plans                    │ loom_events                     │
│ (workflow definitions)        │ (execution events)              │
└───────────────────────────────┴─────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ Profile Tables                                                  │
├───────────────────────────────┬─────────────────────────────────┤
│ host_activity_profiles        │ host_personality_profiles       │
│ (usage patterns)              │ (AI-generated summaries)        │
└───────────────────────────────┴─────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ Other                                                           │
├───────────────────────────────┬─────────────────────────────────┤
│ credit_gifts                  │ conversation_summaries          │
│ (gifted credits)              │ (AI summaries of convos)        │
└───────────────────────────────┴─────────────────────────────────┘
```

## Key Indexes for Metrics Queries

| Table | Index | Use Case |
|-------|-------|----------|
| conversations | `idx_conversations_not_deleted` | Active conversation queries |
| tool_messages | `idx_tool_messages_tool_name` | Tool usage aggregations |
| tool_messages | `idx_tool_messages_timestamp` | Time-range tool queries |
| subscriptions | `subscriptions_host_id_status_idx` | Sub status lookups |
| users | `users_canonical_email_idx` | User dedup |
| connections | `idx_connections_user_id_app` | App connection lookups |