Data model
Matilda uses one SQLite file. The schema is created and migrated in matilda/db.py with plain DDL and ALTER TABLE statements. There is no ORM.
contacts
The central table, keyed by phone.
| Column | Notes |
|---|---|
phone | Primary key |
name, email | |
role | lead or agent |
intent | buy, sell, or browsing |
budget, timeline | Free text as captured |
preapproval | yes, no, in-progress, or unknown |
areas | JSON list |
property_interest | |
status | new, qualifying, qualified, showing, nurture |
timezone | |
reminders_enabled | |
notes | |
memory | Curated long-term facts injected every turn |
onboarded | |
share_token | Set on qualification, used by the lead sheet |
fub_person_id, fub_sync_status, fub_synced_at | Follow Up Boss link |
created_at, updated_at |
conversations
| Column | Notes |
|---|---|
id | |
phone | Contact |
role | user or assistant |
content | |
source | matilda for agent and web chat, personal_imessage for worker-synced threads |
source_guid | De-duplication key for worker-synced messages |
created_at |
reminders
phone, subject, day_of_week, reminder_time, recurring, active.
lead_events
The Captured timeline. phone, kind (capture, status, or fub), field, value, detail, created_at. Display-only, written by the worker ingest path.
crm_items
CRM activity already pushed to Follow Up Boss. phone, kind (note, task, or appointment), content_hash, with a unique constraint on the three so nothing is pushed twice.
dashboard_users
| Column | Notes |
|---|---|
email | Primary key |
password_hash | PBKDF2-HMAC-SHA256 |
name | |
role | owner, admin, or viewer |
team_id | |
must_change_password | Set on admin-provisioned accounts |
is_demo |
teams and team_members
teams holds named teams. team_members is the many-to-many link. Teams never scope data access.
audit_log
actor, action (a dotted verb such as settings.update), target, detail, created_at. Secret values are never stored.
settings
Runtime configuration overrides saved from the Setup page. These win over environment variables.
login_codes
Web-chat OTP state. code_hash (HMAC), expires_at, attempts, consumed, ip.
worker_keys
key_id, secret_hash (SHA-256), label, created_by, last_seen_at, revoked.
routines, tasks, contractors, integration_requests
Tables backing the Tasks page routines, the task board, the Contractors pages, and the "integration not listed" requests from Setup.
Properties, tenants, landlords, tickets, and invoices are not persisted in the current release. They are served from a curated fixture module. Only contractors have been promoted to a real table.