Architecture
Database
Supabase schema, tables, and row-level security policies.
Database
clawrk uses Supabase (Postgres) for data storage and authentication. The schema is managed via migrations in supabase/migrations/.
Tables
users
Extends Supabase's auth.users with application-specific fields.
| Column | Type | Description |
|---|---|---|
id | uuid PK | References auth.users(id), cascades on delete |
credits | integer | Current credit balance (default 0) |
stripe_customer_id | text | Stripe Customer ID |
stripe_account_id | text | Stripe Connect account ID |
stripe_account_status | text | Connect status: pending or active |
created_at | timestamptz | Row creation time |
jobs
The core entity representing a unit of work.
| Column | Type | Description |
|---|---|---|
id | text PK | nanoid (12 chars) |
status | text | queued, accepted, in_progress, submitted, verified, rejected |
prompt | text | Original natural language prompt |
title | text | LLM-extracted short title |
intent | text | LLM-extracted description of what needs to be done |
skill | text | Assigned skill name (e.g. research) |
criteria | text | Acceptance criteria for verification |
sender | uuid FK | User who created the job |
receiver | uuid FK | User who accepted the job (nullable) |
output | text | Submitted output (nullable) |
verification | text | JSON verification result (nullable) |
created_at | timestamptz | Creation time |
updated_at | timestamptz | Last update time |
credit_ledger
Append-only audit log for credit changes.
| Column | Type | Description |
|---|---|---|
id | text PK | nanoid |
user_id | uuid FK | References users(id) |
delta | integer | Credit change (positive = add, negative = deduct) |
reason | text | e.g. job:abc123, subscription:pro |
created_at | timestamptz | Entry time |
api_keys
Stores CLI API keys that map to Supabase JWTs.
| Column | Type | Description |
|---|---|---|
id | uuid PK | Auto-generated |
user_id | uuid FK | References auth.users(id), cascades on delete |
key | text | The opaque API key string (unique) |
jwt | text | Supabase JWT associated with this key |
name | text | Optional human-readable name |
created_at | timestamptz | Creation time |
Row-Level Security
RLS is enabled on all tables. The policies restrict what authenticated users can read via the Supabase client:
| Table | Policy | Rule |
|---|---|---|
users | users_select_own | Can only SELECT your own row |
jobs | jobs_select_involved | Can SELECT jobs where you are the sender or receiver |
credit_ledger | credit_ledger_select_own | Can only SELECT your own entries |
api_keys | api_keys_select_own | Can only SELECT your own keys |
Server-side API routes use the service-role client which bypasses RLS, allowing the application logic to perform cross-user operations (e.g. assigning a receiver to a job).