Architecture

Architecture overview

Thalix Vault separates the user-facing tv CLI, an authenticated service boundary, a relational catalog, and private file storage. The backend is the sole authorization authority; the CLI never receives database credentials, object-storage credentials, or server secrets — only a revocable, scoped bearer token.

Implementation status: implemented for the MVP surface — identity/session (#22/#23/#24/#25), Root Folders/metadata (#5), files/versions/lifecycle (#6/#7/#8), access delegation (#9), audit (#10), Agent Skill (#11), standalone distribution (#12), ICM templates/workspaces (#68/#70), and the Tier 1 local stdio MCP server (#78) are all built, tested, and merged (the hosted Tier 2 MCP server is not built). See Current state for exactly what remains planned or operator-blocked rather than code-incomplete.

Control plane

The control plane is Supabase (Postgres + GoTrue auth + Storage), fronted by a TanStack Start application deployed through Lovable. There is a single Supabase project per environment — see Current state for what that concentration means in practice. The CLI never talks to Supabase directly: every tv command calls one of the application's own /api/internal/* routes over HTTPS, which in turn calls a SECURITY DEFINER Postgres RPC using the service role. See Trust boundaries for exactly how that chain is locked down at each hop.

flowchart LR
    Human[User or administrator] --> CLI[tv CLI]
    Agent[Local AI agent] --> Skill[Installed thalix-vault Agent Skill]
    Skill --> CLI
    Browser[Browser: login, account, device approval] -->|Secure HttpOnly cookies| App
    CLI -->|tv_ bearer token, TLS| App[TanStack Start app /api/internal/*]
    App -->|service role, SECURITY DEFINER RPCs| PG[(Supabase Postgres: RLS on every table)]
    App -->|signed URLs, service role| Storage[(Supabase Storage: private buckets)]
    PG --> Audit[(Append-only audit_events_view)]
    CI[GitHub Actions] --> Releases[Signed public release artifacts]
    Releases --> Updater[tv update / tv update --rollback]

System boundaries

Client boundary

The tv CLI parses commands, maintains the local authenticated session (a private, permission-locked credential file — see Security and authorization), streams file bytes and checksums, renders human or JSON output, and applies user confirmation boundaries. It calls the application's internal API and never implements an authoritative access decision itself.

The installed thalix-vault Agent Skill is documentation over the CLI (see Agent Skill). It discovers and runs supported commands through the current user's own session; it has no separate credentials, API surface, or permissions.

Service boundary

Every /api/internal/* route validates its request shape and correlation ID, resolves the caller's tv_ bearer token (or, for browser routes, the Secure HttpOnly session cookie) to an authenticated identity, and calls exactly one SECURITY DEFINER Postgres function that performs authorization, validation, and mutation together in one round trip. These routes are internal implementation details, not a supported public API or compatibility promise for MVP consumers.

Persistence boundary

Postgres (Supabase) stores logical file identity, immutable version metadata, metadata revisions, Root Folders, groups, grants, and every audit table, each with Row Level Security enabled and all client-role table privileges revoked — see Trust boundaries.
Supabase Storage private buckets store file bytes under opaque keys; the CLI never receives a storage credential, only a short-lived, operation-scoped signed URL.
A file version becomes readable only after the backend's own independent re-measurement of the uploaded object (byte count and SHA-256) matches what the CLI reported, and the catalog commit succeeds.
SQL and object storage cannot share one transaction, so they require explicit reconciliation for the narrow pending/orphaned-object case — see Reconciliation.

Distribution boundary

The private source repository holds source, tests, workflows, and signing configuration. GitHub Actions builds, tests, and Ed25519-signs platform artifacts and publishes them to a separate, source-free thalix-vault-releases repository, so a standalone install never needs access to the private source repository. The Lovable-hosted /cli/install page links to those artifacts but is not their source of truth — see Releasing tv and Failed release and rollback.

Primary modules

Module	Responsibility	Status
Identity and session	Login, revocation, account state, bootstrap role	Implemented
Vault object	Private transfer authorization, checksums, object keys	Implemented
File catalog	Logical files, versions, metadata, storage/SQL coordination	Implemented
Metadata schema	Root Folders, definitions, normalization, validation	Implemented
Authorization	Ownership, groups, grants, delegation, query predicates	Implemented
Query	Bounded access-filtered catalog search	Implemented
Audit	Append-only event recording and unified filtered retrieval	Implemented
CLI	Command parsing, session state, streaming, rendering, errors	Implemented
Agent skill	Portable guidance, installation, integrity, compatibility	Implemented
Distribution	Packaging, signing, publishing, update, rollback	Implemented (unpublished — see Current state)
Minimal web	Landing, login, account state, `/cli/install`, `/docs`	Implemented
Templates & workspaces	ICM plugin convention: template/workspace instantiate/derive/import/update/review, workspace checkout/commit	Implemented
MCP server	Tier 1 local stdio (serve/install/uninstall/doctor); Tier 2 hosted deferred — see ADR-0007	Implemented (Tier 1) · Not built (Tier 2)
Invitations	Admin-facing creation of new-member invitations	Implemented

Architecture invariants

The backend authorizes every protected operation; the CLI never decides access itself.
Storage remains private; public distribution of tv never grants vault access.
Content versions, metadata revisions, and audit events are immutable histories — enforced by database triggers, not just application convention (see Trust boundaries).
Search removes inaccessible rows before results leave the backend.
Correlation IDs connect records only across boundaries an operation reaches. Local-only failures do not imply service, SQL, storage, or database audit records.
Partially completed uploads never become readable versions.
Provider details (Supabase, Lovable) remain behind narrow service and infrastructure interfaces.