Add core Supabase schema migration

This commit is contained in:
ZTatman 2026-03-27 17:22:21 -04:00
parent 0c0ba74c09
commit 1af765a6aa
4 changed files with 1507 additions and 0 deletions

970
NEW_PLAN.md Normal file
View file

@ -0,0 +1,970 @@
# Nadir — Supabase Setup & Architecture Guide
> Complete reference for setting up Supabase, the data schema, storage buckets, authentication, and monetization for the Nadir voice mood diary app.
> Intended for use with coding agents — each section is a discrete, executable step.
---
## Table of Contents
1. [Project Overview](#1-project-overview)
2. [Tech Stack](#2-tech-stack)
3. [Supabase Project Setup](#3-supabase-project-setup)
4. [Environment Variables](#4-environment-variables)
5. [Database Schema](#5-database-schema)
6. [Storage Buckets](#6-storage-buckets)
7. [Row Level Security](#7-row-level-security)
8. [Python Dependencies](#8-python-dependencies)
9. [Python db.py — Supabase Client](#9-python-dbpy--supabase-client)
10. [Authentication Flow](#10-authentication-flow)
11. [Subscription Tiers](#11-subscription-tiers)
12. [Monetization — Stripe + RevenueCat](#12-monetization--stripe--revenuecat)
13. [AI Call Enforcement Pattern](#13-ai-call-enforcement-pattern)
14. [FastAPI Endpoints Reference](#14-fastapi-endpoints-reference)
15. [Full System Architecture](#15-full-system-architecture)
16. [Build Order](#16-build-order)
---
## 1. Project Overview
Nadir is a voice-first personal mood diary app. Users speak freely, their voice is transcribed by Whisper, AI extracts emotional metadata, and entries are stored in a vector database for RAG-powered pattern queries.
**Core user flows:**
- Record a voice entry → transcribe → auto-tag mood/triggers → save
- Ask questions about emotional patterns → RAG retrieves relevant entries → AI answers
- Weekly reflection digest generated from last 7 entries
**Privacy:** All audio and diary data is private per-user. No entry is ever visible to other users.
---
## 2. Tech Stack
| Layer | Tool | Notes |
| ------------------- | --------------------- | ----------------------------------- |
| Mobile frontend | React Native + Expo | iOS + Android from one codebase |
| Backend API | FastAPI (Python) | Hosted on Railway or Render |
| Database | Supabase PostgreSQL | + pgvector extension for embeddings |
| File storage | Supabase Storage | Private buckets, signed URLs |
| Authentication | Supabase Auth | Email, Google, Apple sign-in |
| Voice transcription | OpenAI Whisper | Runs on server, not phone |
| Embeddings | sentence-transformers | `all-MiniLM-L6-v2`, runs locally |
| LLM (local dev) | Ollama `llama3.2:1b` | Free, runs on your machine |
| LLM (production) | OpenAI `gpt-4o-mini` | Swap when ready to deploy |
| Billing | Stripe + RevenueCat | RevenueCat handles iOS/Android IAP |
---
## 3. Supabase Project Setup
### Step 1 — Create project
1. Go to `supabase.com` and sign in
2. Click **New Project**
3. Choose a name (e.g. `nadir-prod`) and a strong database password
4. Select the region closest to your users
5. Wait ~2 minutes for provisioning
### Step 2 — Collect credentials
Go to **Settings → API** and copy:
```
Project URL: https://xxxxxxxxxxxx.supabase.co
Anon key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Service key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... ← keep secret, server only
```
Go to **Settings → Database** and copy:
```
Connection string (URI):
postgresql://postgres:[PASSWORD]@db.xxxxxxxxxxxx.supabase.co:5432/postgres
```
---
## 4. Environment Variables
Add all of these to your `.env` file. Never commit this file to Git.
```env
# Supabase
SUPABASE_URL=https://xxxxxxxxxxxx.supabase.co
SUPABASE_ANON_KEY=eyJ...
SUPABASE_SERVICE_KEY=eyJ... # server-side only, never expose to client
DATABASE_URL=postgresql://postgres:[PASSWORD]@db.xxxxxxxxxxxx.supabase.co:5432/postgres
# OpenAI (for production LLM calls)
OPENAI_API_KEY=sk-...
# Stripe
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
# RevenueCat (optional, for mobile billing)
REVENUECAT_API_KEY=...
```
Your `.gitignore` should already contain `.env` — confirm before pushing to GitHub.
---
## 5. Database Schema
Run all of the following SQL in **Supabase → SQL Editor** in the order shown.
### Step 1 — Enable extensions
```sql
-- Vector similarity search
create extension if not exists vector;
-- UUID generation
create extension if not exists "uuid-ossp";
```
### Step 2 — profiles table
Created automatically when a user signs up via a trigger on `auth.users`.
```sql
create table public.profiles (
id uuid primary key references auth.users(id) on delete cascade,
created_at timestamptz default now(),
display_name text,
avatar_url text
);
-- Auto-create profile when user signs up
create or replace function public.handle_new_user()
returns trigger as $$
begin
insert into public.profiles (id, display_name)
values (new.id, new.raw_user_meta_data->>'full_name');
return new;
end;
$$ language plpgsql security definer;
create trigger on_auth_user_created
after insert on auth.users
for each row execute procedure public.handle_new_user();
```
### Step 3 — entries table
```sql
create table public.entries (
id uuid primary key default gen_random_uuid(),
user_id uuid not null references public.profiles(id) on delete cascade,
created_at timestamptz default now(),
transcript text not null,
audio_path text, -- pointer to Supabase Storage object path
duration_secs int, -- length of the voice recording
processing_status text not null default 'recorded'
check (processing_status in ('recorded', 'transcribing', 'transcribed', 'analyzing', 'pending_review', 'confirmed', 'error')),
embedding vector(384), -- all-MiniLM-L6-v2 dimensions
summary text -- optional AI-generated summary
);
-- Index for fast vector similarity search
create index on public.entries
using ivfflat (embedding vector_cosine_ops)
with (lists = 100);
-- Index for fast user entry lookups
create index on public.entries (user_id, created_at desc);
-- Index for queue-style lookups
create index on public.entries (user_id, processing_status, created_at desc);
```
### Step 4 — entry_analysis table
```sql
create table public.entry_analysis (
entry_id uuid primary key references public.entries(id) on delete cascade,
created_at timestamptz default now(),
updated_at timestamptz default now(),
valence double precision check (valence between -1.0 and 1.0),
arousal double precision check (arousal between 0.0 and 1.0),
intensity double precision check (intensity between 0.0 and 1.0),
confidence double precision check (confidence between 0.0 and 1.0),
dominant_mood text,
analysis_status text not null default 'proposed'
check (analysis_status in ('proposed', 'pending_review', 'confirmed', 'corrected')),
model_version text
);
create index on public.entry_analysis (analysis_status);
create index on public.entry_analysis (created_at desc);
```
### Step 5 — entry_mood_signals table
```sql
create table public.entry_mood_signals (
id uuid primary key default gen_random_uuid(),
entry_id uuid not null references public.entries(id) on delete cascade,
mood text not null,
intensity double precision not null check (intensity between 0.0 and 1.0),
confidence double precision check (confidence between 0.0 and 1.0),
valence_weight double precision,
created_at timestamptz default now(),
unique (entry_id, mood)
);
create index on public.entry_mood_signals (entry_id);
create index on public.entry_mood_signals (mood, entry_id);
```
### Step 6 — entry_tags table
```sql
create table public.entry_tags (
id uuid primary key default gen_random_uuid(),
entry_id uuid not null references public.entries(id) on delete cascade,
tag text not null,
confidence double precision check (confidence between 0.0 and 1.0),
created_at timestamptz default now(),
unique (entry_id, tag)
);
create index on public.entry_tags (entry_id);
create index on public.entry_tags (tag, entry_id);
```
### Step 7 — entry_feedback table
```sql
create table public.entry_feedback (
id uuid primary key default gen_random_uuid(),
entry_id uuid not null references public.entries(id) on delete cascade,
user_id uuid not null references public.profiles(id) on delete cascade,
created_at timestamptz default now(),
field_name text not null,
old_value jsonb,
new_value jsonb,
reason text,
check (field_name in ('processing_status', 'analysis_status', 'valence', 'arousal', 'intensity', 'dominant_mood', 'mood_signals', 'tags', 'summary'))
);
create index on public.entry_feedback (user_id, created_at desc);
create index on public.entry_feedback (entry_id);
```
### Step 8 — ai_usage_log table
```sql
create table public.ai_usage_log (
id uuid primary key default gen_random_uuid(),
user_id uuid not null references public.profiles(id) on delete cascade,
created_at timestamptz default now(),
call_type text not null
check (call_type in ('ask', 'extract', 'summarise')),
tokens_used int,
model text -- 'llama3.2:1b' | 'gpt-4o-mini'
);
create index on public.ai_usage_log (user_id, created_at desc);
```
### Step 9 — subscriptions table
```sql
create table public.subscriptions (
user_id uuid primary key references public.profiles(id) on delete cascade,
created_at timestamptz default now(),
stripe_customer_id text unique,
stripe_sub_id text unique,
tier text not null default 'free', -- 'free' | 'pro' | 'unlimited'
status text not null default 'active'
check (status in ('active', 'cancelled', 'past_due')),
current_period_end date
);
create index on public.subscriptions (stripe_customer_id);
```
### Step 10 — match_entries function (RAG vector search)
```sql
create or replace function match_entries (
query_embedding vector(384),
match_user_id uuid,
match_count int default 5
)
returns table (
id uuid,
transcript text,
summary text,
created_at timestamptz,
valence double precision,
arousal double precision,
intensity double precision,
dominant_mood text,
similarity float
)
language sql stable
as $$
select
e.id,
e.transcript,
e.summary,
e.created_at,
a.valence,
a.arousal,
a.intensity,
a.dominant_mood,
1 - (e.embedding <=> query_embedding) as similarity
from public.entries e
left join public.entry_analysis a on a.entry_id = e.id
where e.user_id = match_user_id
order by e.embedding <=> query_embedding
limit match_count;
$$;
```
### Step 11 — usage accounting
```sql
-- Usage is tracked in ai_usage_log, so no profile counter reset is needed.
-- If limits are enforced in SQL later, add a dedicated usage summary table.
```
---
## 6. Storage Buckets
Run in **Supabase → SQL Editor** or create manually in **Storage** dashboard.
```sql
-- Recordings bucket (private)
insert into storage.buckets (id, name, public)
values ('recordings', 'recordings', false);
-- Avatars bucket (private)
insert into storage.buckets (id, name, public)
values ('avatars', 'avatars', false);
```
### File path conventions
```
recordings/
└── {user_id}/
└── {YYYYMMDD_HHMMSS}.m4a
e.g. recordings/abc-123/20260316_143022.m4a
avatars/
└── {user_id}/
└── avatar.jpg
e.g. avatars/abc-123/avatar.jpg
```
### Accessing files from Python (signed URL — expires in 1 hour)
```python
url = supabase.storage.from_("recordings").create_signed_url(
path=f"{user_id}/{filename}",
expires_in=3600
)
```
---
## 7. Row Level Security
RLS ensures every user can only see and modify their own data. Run in **SQL Editor**.
```sql
-- ── profiles ──
alter table public.profiles enable row level security;
create policy "Users can view own profile"
on public.profiles for select
using ((select auth.uid()) = id);
create policy "Users can update own profile"
on public.profiles for update
using ((select auth.uid()) = id);
-- ── entries ──
alter table public.entries enable row level security;
create policy "Users can view own entries"
on public.entries for select
using ((select auth.uid()) = user_id);
create policy "Users can insert own entries"
on public.entries for insert
with check ((select auth.uid()) = user_id);
create policy "Users can delete own entries"
on public.entries for delete
using ((select auth.uid()) = user_id);
-- ── entry_analysis ──
alter table public.entry_analysis enable row level security;
create policy "Users can view own analysis"
on public.entry_analysis for select
using (
exists (
select 1
from public.entries e
where e.id = entry_id
and e.user_id = (select auth.uid())
)
);
-- ── entry_mood_signals ──
alter table public.entry_mood_signals enable row level security;
create policy "Users can view own mood signals"
on public.entry_mood_signals for select
using (
exists (
select 1
from public.entries e
where e.id = entry_id
and e.user_id = (select auth.uid())
)
);
-- ── entry_tags ──
alter table public.entry_tags enable row level security;
create policy "Users can view own tags"
on public.entry_tags for select
using (
exists (
select 1
from public.entries e
where e.id = entry_id
and e.user_id = (select auth.uid())
)
);
-- ── entry_feedback ──
alter table public.entry_feedback enable row level security;
create policy "Users can view own feedback"
on public.entry_feedback for select
using ((select auth.uid()) = user_id);
create policy "Users can insert own feedback"
on public.entry_feedback for insert
with check (
(select auth.uid()) = user_id
and exists (
select 1
from public.entries e
where e.id = entry_id
and e.user_id = (select auth.uid())
)
);
create policy "Users can update own feedback"
on public.entry_feedback for update
using (
(select auth.uid()) = user_id
and exists (
select 1
from public.entries e
where e.id = entry_id
and e.user_id = (select auth.uid())
)
);
create policy "Users can delete own feedback"
on public.entry_feedback for delete
using (
(select auth.uid()) = user_id
and exists (
select 1
from public.entries e
where e.id = entry_id
and e.user_id = (select auth.uid())
)
);
-- ── ai_usage_log ──
alter table public.ai_usage_log enable row level security;
create policy "Users can view own usage"
on public.ai_usage_log for select
using ((select auth.uid()) = user_id);
-- ── subscriptions ──
alter table public.subscriptions enable row level security;
create policy "Users can view own subscription"
on public.subscriptions for select
using ((select auth.uid()) = user_id);
-- ── Storage: recordings ──
create policy "Users can upload own recordings"
on storage.objects for insert
with check (
bucket_id = 'recordings'
and (select auth.uid())::text = (storage.foldername(name))[1]
);
create policy "Users can view own recordings"
on storage.objects for select
using (
bucket_id = 'recordings'
and (select auth.uid())::text = (storage.foldername(name))[1]
);
create policy "Users can delete own recordings"
on storage.objects for delete
using (
bucket_id = 'recordings'
and (select auth.uid())::text = (storage.foldername(name))[1]
);
-- ── Storage: avatars ──
create policy "Users can manage own avatar"
on storage.objects for all
using (
bucket_id = 'avatars'
and (select auth.uid())::text = (storage.foldername(name))[1]
);
```
---
## 8. Python Dependencies
```bash
# Remove ChromaDB, add Supabase stack
uv remove chromadb
uv add supabase
uv add sentence-transformers
uv add vecs
uv add stripe
uv add python-jose # JWT token verification
uv add fastapi uvicorn
```
Full `pyproject.toml` dependencies section:
```toml
dependencies = [
"fastapi>=0.115.0",
"uvicorn>=0.30.0",
"supabase>=2.0.0",
"sentence-transformers>=3.0.0",
"vecs>=0.4.0",
"openai>=2.0.0",
"openai-whisper>=20250625",
"sounddevice>=0.5.0",
"scipy>=1.17.0",
"pydantic>=2.0.0",
"python-dotenv>=1.0.0",
"python-jose>=3.3.0",
"stripe>=10.0.0",
"python-multipart>=0.0.9",
]
```
---
## 9. Python db.py — Supabase Client
Replace your existing `db.py` entirely with this:
```python
"""
db.py — Supabase client and embedding model
Imported by store.py, query.py, and main.py
"""
import os
from dotenv import load_dotenv
from supabase import create_client, Client
from sentence_transformers import SentenceTransformer
load_dotenv()
# ── Supabase client ───────────────────────────────────────────────────────────
def get_supabase() -> Client:
"""Returns authenticated Supabase client using the service key."""
url = os.environ["SUPABASE_URL"]
key = os.environ["SUPABASE_SERVICE_KEY"] # service key for server-side ops
return create_client(url, key)
def get_storage():
"""Shortcut to the recordings storage bucket."""
return get_supabase().storage.from_("recordings")
# ── Embedding model ───────────────────────────────────────────────────────────
# Downloads ~80MB on first run, cached locally after that
_model = None
def get_embedding_model() -> SentenceTransformer:
global _model
if _model is None:
_model = SentenceTransformer("all-MiniLM-L6-v2")
return _model
def embed(text: str) -> list[float]:
"""Convert a string to a 384-dimensional embedding vector."""
model = get_embedding_model()
return model.encode(text).tolist()
```
---
## 10. Authentication Flow
Supabase Auth handles everything. Your FastAPI server verifies the JWT token on every request.
### How it works
```
1. User signs in on mobile app via Supabase Auth SDK
2. Supabase returns a JWT access token
3. Mobile app sends JWT in every API request header:
Authorization: Bearer eyJ...
4. FastAPI verifies the JWT using Supabase's public key
5. FastAPI extracts user_id from the token
6. All database queries are scoped to that user_id
```
### FastAPI JWT verification
```python
from fastapi import Depends, HTTPException, Header
from python_jose import jwt, JWTError
import os
SUPABASE_JWT_SECRET = os.environ["SUPABASE_JWT_SECRET"] # from Supabase dashboard
def get_current_user(authorization: str = Header(...)) -> str:
"""Extract and verify user_id from JWT. Use as a FastAPI dependency."""
try:
token = authorization.replace("Bearer ", "")
payload = jwt.decode(token, SUPABASE_JWT_SECRET, algorithms=["HS256"])
user_id = payload.get("sub")
if not user_id:
raise HTTPException(401, "Invalid token")
return user_id
except JWTError:
raise HTTPException(401, "Could not validate token")
# Usage in any endpoint:
@app.post("/entries/save")
def save_entry(data: EntryRequest, user_id: str = Depends(get_current_user)):
# user_id is verified and safe to use
...
```
---
## 11. Subscription Tiers
| Tier | Price | AI asks/month | AI extractions | Weekly digest | Storage |
| --------- | -------- | ------------- | -------------- | ------------- | ------- |
| Free | $0 | 30 | 30 | No | 100 MB |
| Pro | $4.99/mo | 500 | Unlimited | No | 2 GB |
| Unlimited | $9.99/mo | Unlimited | Unlimited | Yes | 10 GB |
### Tier limits by subscription tier
These limits live in application logic or a dedicated billing table, not `profiles`.
| Tier | Monthly ask limit | Extraction limit | Weekly digest |
| --------- | ----------------- | ----------------- | ------------- |
| free | 30 | 30 | No |
| pro | 500 | Unlimited | No |
| unlimited | Unlimited | Unlimited | Yes |
### What counts as an AI call
| Action | Call type | Counts against limit? |
| ----------------------------- | ----------- | --------------------- |
| User asks a question | `ask` | Yes |
| Auto-extract metadata on save | `extract` | Yes (free), No (pro+) |
| Weekly reflection summary | `summarise` | Unlimited only |
| Transcription (Whisper) | n/a | No — flat server cost |
---
## 12. Monetization — Stripe + RevenueCat
### Why RevenueCat
Apple App Store and Google Play both require in-app purchases for subscriptions sold inside a mobile app. RevenueCat abstracts both platforms plus web (Stripe) into one API. Without it you'd manage three separate billing integrations.
### Setup steps
1. Create a RevenueCat account at `revenuecat.com`
2. Create products in App Store Connect and Google Play Console
3. Link those products to RevenueCat entitlements
4. RevenueCat sends webhooks to your FastAPI server on subscription events
### FastAPI webhook handler
```python
@app.post("/webhooks/revenuecat")
async def revenuecat_webhook(request: Request):
payload = await request.json()
event_type = payload["event"]["type"]
user_id = payload["event"]["app_user_id"]
product_id = payload["event"].get("product_id", "")
# Map product ID to tier
tier_map = {
"nadir_pro_monthly": "pro",
"nadir_unlimited_monthly": "unlimited",
}
tier = tier_map.get(product_id, "free")
if event_type in ("INITIAL_PURCHASE", "RENEWAL"):
supabase.table("subscriptions").upsert({
"user_id": user_id,
"tier": tier,
"status": "active",
}).execute()
elif event_type in ("CANCELLATION", "EXPIRATION"):
supabase.table("subscriptions").update({
"status": "cancelled",
"tier": "free",
}).eq("user_id", user_id).execute()
return {"status": "ok"}
```
---
## 13. AI Call Enforcement Pattern
Add this check to every FastAPI endpoint that calls an LLM.
```python
def check_ai_limit(user_id: str, call_type: str):
"""
Raises HTTP 429 if user has exceeded their monthly AI limit for this call type.
Logs the call if allowed.
"""
supabase = get_supabase()
# Fetch current subscription tier
result = supabase.table("subscriptions")\
.select("tier, status")\
.eq("user_id", user_id)\
.limit(1)\
.execute()
subscription = result.data[0] if result.data else None
tier = subscription["tier"] if subscription and subscription["status"] == "active" else "free"
# Call-type limits are enforced in application logic.
# The database only stores the event log.
limit_map = {
"free": {"ask": 30, "extract": 30, "summarise": 0},
"pro": {"ask": 500, "extract": 999999, "summarise": 0},
"unlimited": {"ask": 999999, "extract": 999999, "summarise": 999999},
}
limit = limit_map.get(tier, limit_map["free"]).get(call_type, 0)
if limit == 0:
raise HTTPException(
status_code=429,
detail={
"error": "This AI action is not available on your tier",
"tier": tier,
"call_type": call_type,
"upgrade_url": "https://yourapp.com/upgrade"
}
)
# Count usage for the current month and call type from the log table.
# This keeps the profiles table identity-only.
month_start = datetime.now().replace(day=1, hour=0, minute=0, second=0, microsecond=0)
usage = supabase.table("ai_usage_log")\
.select("id", count="exact")\
.eq("user_id", user_id)\
.eq("call_type", call_type)\
.gte("created_at", month_start.isoformat())\
.execute()
used = usage.count or 0
if used >= limit:
raise HTTPException(
status_code=429,
detail={
"error": f"Monthly AI limit reached for {call_type}",
"used": used,
"limit": limit,
"tier": tier,
"upgrade_url": "https://yourapp.com/upgrade"
}
)
# Log the call
supabase.table("ai_usage_log").insert({
"user_id": user_id,
"call_type": call_type,
"model": "gpt-4o-mini",
}).execute()
```
### Usage in endpoints
```python
@app.post("/ask")
def ask_question(data: AskRequest, user_id: str = Depends(get_current_user)):
check_ai_limit(user_id, "ask") # ← call this before any LLM call
# ... rest of RAG logic
```
---
## 14. FastAPI Endpoints Reference
| Method | Path | Auth | Description |
| -------- | ----------------------- | -------- | -------------------------------------------- |
| `POST` | `/entries/upload-audio` | Required | Upload .m4a → transcribe → return transcript |
| `POST` | `/entries/save` | Required | Save transcript + analysis + signals + embedding |
| `GET` | `/entries` | Required | List user's recent entries |
| `GET` | `/entries/{id}` | Required | Get single entry |
| `DELETE` | `/entries/{id}` | Required | Delete entry + audio file |
| `POST` | `/ask` | Required | RAG question → AI answer |
| `GET` | `/profile` | Required | Get user profile + subscription info |
| `POST` | `/webhooks/revenuecat` | None | Handle billing events |
| `GET` | `/health` | None | Server health check |
### POST /entries/upload-audio
```python
@app.post("/entries/upload-audio")
async def upload_audio(
audio: UploadFile,
user_id: str = Depends(get_current_user)
):
audio_bytes = await audio.read()
filename = f"{user_id}/{datetime.now().strftime('%Y%m%d_%H%M%S')}.m4a"
audio_path = filename
# Upload to Supabase Storage
get_storage().upload(
path=filename,
file=audio_bytes,
file_options={"content-type": "audio/m4a"}
)
# Transcribe with Whisper (temp file on disk)
with tempfile.NamedTemporaryFile(suffix=".m4a", delete=False) as tmp:
tmp.write(audio_bytes)
tmp_path = tmp.name
transcript = transcribe(tmp_path) # your transcribe.py function
os.unlink(tmp_path)
return {"transcript": transcript, "audio_path": audio_path}
```
---
## 15. Full System Architecture
```
┌─────────────────┐ ┌──────────────────────┐ ┌─────────────────────────┐
│ Phone app │ │ FastAPI server │ │ Supabase │
│ React Native │ │ main.py │ │ │
│ │ │ │ │ PostgreSQL │
│ Microphone ────┼─────────┼→ POST /upload-audio │ │ ┌──────────────────┐ │
│ Temp .m4a │ │ transcribe.py │ │ │ profiles │ │
│ Chat UI ←────┼─────────┼─ Whisper → text ───┼────────┼→ │ entries │ │
│ │ │ store.py │ │ │ entry_analysis │ │
│ │─────────┼→ POST /ask │ │ │ entry_mood_signals│ │
│ │ │ query.py │ │ │ entry_tags │ │
│ │ │ embed → pgvector │ │ │ entry_feedback │ │
│ │ │ Ollama / OpenAI │ │ │ ai_usage_log │ │
│ │ │ POST /webhooks/ │ │ │ subscriptions │ │
│ RevenueCat ────┼─────────┼→ revenuecat │ │ └──────────────────┘ │
│ │ │ update tier │ │ │
│ │ │ │ │ Storage │
│ │ │ │ │ ┌──────────────────┐ │
│ │ │ │ │ │ recordings/ │ │
│ │ │ │ │ │ avatars/ │ │
│ │ │ │ │ └──────────────────┘ │
└─────────────────┘ └──────────────────────┘ └─────────────────────────┘
```
---
## 16. Build Order
Work through these phases in order. Each phase has a clear done-when checkpoint.
### Phase 1 — Supabase foundation
- [ ] Create Supabase project
- [ ] Run all SQL from Section 5 in SQL Editor
- [ ] Create storage buckets (Section 6)
- [ ] Apply RLS policies (Section 7)
- [ ] Add credentials to `.env`
- [ ] Install Python dependencies (Section 8)
- [ ] Write and test `db.py` (Section 9)
**Done when:** `python db.py` runs without errors and connects to Supabase
### Phase 2 — Rewrite store.py and query.py for Supabase
- [ ] Rewrite `store.py` to insert into `entries` table with embeddings
- [ ] Rewrite `query.py` to use `match_entries` RPC function
- [ ] Test: save an entry, run a vector search, get results back
**Done when:** You can save an entry and ask a question with results from Supabase
### Phase 3 — Voice recording
- [ ] Write `record.py` — mic capture → `.m4a` file
- [ ] Write `transcribe.py` — Whisper → text
- [ ] Test both independently from terminal
**Done when:** `python record.py` saves a file, `python transcribe.py recording.m4a` returns text
### Phase 4 — FastAPI server
- [ ] Write `main.py` with all endpoints from Section 14
- [ ] Add JWT auth middleware (Section 10)
- [ ] Add AI call enforcement (Section 13)
- [ ] Test all endpoints with Bruno or Postman
**Done when:** All endpoints return correct responses when called with a valid JWT
### Phase 5 — Mobile frontend
- [ ] Set up React Native + Expo project
- [ ] Integrate Supabase Auth SDK for sign-in
- [ ] Build record screen — calls `POST /entries/upload-audio`
- [ ] Build reflect screen — calls `POST /ask`
- [ ] Build entry list screen — calls `GET /entries`
**Done when:** Full flow works on a real device — record, save, ask, get answer
### Phase 6 — Billing
- [ ] Set up RevenueCat account and products
- [ ] Add webhook endpoint (Section 12)
- [ ] Test subscription flow end to end
- [ ] Verify tier enforcement works correctly
**Done when:** Subscribing to Pro updates the row in `subscriptions` and leaves `profiles` untouched
---
_Last updated: March 2026 — Nadir v0.1_

8
supabase/.gitignore vendored Normal file
View file

@ -0,0 +1,8 @@
# Supabase
.branches
.temp
# dotenvx
.env.keys
.env.local
.env.*.local

384
supabase/config.toml Normal file
View file

@ -0,0 +1,384 @@
# For detailed configuration reference documentation, visit:
# https://supabase.com/docs/guides/local-development/cli/config
# A string used to distinguish different Supabase projects on the same host. Defaults to the
# working directory name when running `supabase init`.
project_id = "Nadir"
[api]
enabled = true
# Port to use for the API URL.
port = 54321
# Schemas to expose in your API. Tables, views and stored procedures in this schema will get API
# endpoints. `public` and `graphql_public` schemas are included by default.
schemas = ["public", "graphql_public"]
# Extra schemas to add to the search_path of every request.
extra_search_path = ["public", "extensions"]
# The maximum number of rows returns from a view, table, or stored procedure. Limits payload size
# for accidental or malicious requests.
max_rows = 1000
[api.tls]
# Enable HTTPS endpoints locally using a self-signed certificate.
enabled = false
# Paths to self-signed certificate pair.
# cert_path = "../certs/my-cert.pem"
# key_path = "../certs/my-key.pem"
[db]
# Port to use for the local database URL.
port = 54322
# Port used by db diff command to initialize the shadow database.
shadow_port = 54320
# Maximum amount of time to wait for health check when starting the local database.
health_timeout = "2m"
# The database major version to use. This has to be the same as your remote database's. Run `SHOW
# server_version;` on the remote database to check.
major_version = 17
[db.pooler]
enabled = false
# Port to use for the local connection pooler.
port = 54329
# Specifies when a server connection can be reused by other clients.
# Configure one of the supported pooler modes: `transaction`, `session`.
pool_mode = "transaction"
# How many server connections to allow per user/database pair.
default_pool_size = 20
# Maximum number of client connections allowed.
max_client_conn = 100
# [db.vault]
# secret_key = "env(SECRET_VALUE)"
[db.migrations]
# If disabled, migrations will be skipped during a db push or reset.
enabled = true
# Specifies an ordered list of schema files that describe your database.
# Supports glob patterns relative to supabase directory: "./schemas/*.sql"
schema_paths = []
[db.seed]
# If enabled, seeds the database after migrations during a db reset.
enabled = true
# Specifies an ordered list of seed files to load during db reset.
# Supports glob patterns relative to supabase directory: "./seeds/*.sql"
sql_paths = ["./seed.sql"]
[db.network_restrictions]
# Enable management of network restrictions.
enabled = false
# List of IPv4 CIDR blocks allowed to connect to the database.
# Defaults to allow all IPv4 connections. Set empty array to block all IPs.
allowed_cidrs = ["0.0.0.0/0"]
# List of IPv6 CIDR blocks allowed to connect to the database.
# Defaults to allow all IPv6 connections. Set empty array to block all IPs.
allowed_cidrs_v6 = ["::/0"]
[realtime]
enabled = true
# Bind realtime via either IPv4 or IPv6. (default: IPv4)
# ip_version = "IPv6"
# The maximum length in bytes of HTTP request headers. (default: 4096)
# max_header_length = 4096
[studio]
enabled = true
# Port to use for Supabase Studio.
port = 54323
# External URL of the API server that frontend connects to.
api_url = "http://127.0.0.1"
# OpenAI API Key to use for Supabase AI in the Supabase Studio.
openai_api_key = "env(OPENAI_API_KEY)"
# Email testing server. Emails sent with the local dev setup are not actually sent - rather, they
# are monitored, and you can view the emails that would have been sent from the web interface.
[inbucket]
enabled = true
# Port to use for the email testing server web interface.
port = 54324
# Uncomment to expose additional ports for testing user applications that send emails.
# smtp_port = 54325
# pop3_port = 54326
# admin_email = "admin@email.com"
# sender_name = "Admin"
[storage]
enabled = true
# The maximum file size allowed (e.g. "5MB", "500KB").
file_size_limit = "50MiB"
# Uncomment to configure local storage buckets
# [storage.buckets.images]
# public = false
# file_size_limit = "50MiB"
# allowed_mime_types = ["image/png", "image/jpeg"]
# objects_path = "./images"
# Allow connections via S3 compatible clients
[storage.s3_protocol]
enabled = true
# Image transformation API is available to Supabase Pro plan.
# [storage.image_transformation]
# enabled = true
# Store analytical data in S3 for running ETL jobs over Iceberg Catalog
# This feature is only available on the hosted platform.
[storage.analytics]
enabled = false
max_namespaces = 5
max_tables = 10
max_catalogs = 2
# Analytics Buckets is available to Supabase Pro plan.
# [storage.analytics.buckets.my-warehouse]
# Store vector embeddings in S3 for large and durable datasets
# This feature is only available on the hosted platform.
[storage.vector]
enabled = false
max_buckets = 10
max_indexes = 5
# Vector Buckets is available to Supabase Pro plan.
# [storage.vector.buckets.documents-openai]
[auth]
enabled = true
# The base URL of your website. Used as an allow-list for redirects and for constructing URLs used
# in emails.
site_url = "http://127.0.0.1:3000"
# A list of *exact* URLs that auth providers are permitted to redirect to post authentication.
additional_redirect_urls = ["https://127.0.0.1:3000"]
# How long tokens are valid for, in seconds. Defaults to 3600 (1 hour), maximum 604,800 (1 week).
jwt_expiry = 3600
# JWT issuer URL. If not set, defaults to the local API URL (http://127.0.0.1:<port>/auth/v1).
# jwt_issuer = ""
# Path to JWT signing key. DO NOT commit your signing keys file to git.
# signing_keys_path = "./signing_keys.json"
# If disabled, the refresh token will never expire.
enable_refresh_token_rotation = true
# Allows refresh tokens to be reused after expiry, up to the specified interval in seconds.
# Requires enable_refresh_token_rotation = true.
refresh_token_reuse_interval = 10
# Allow/disallow new user signups to your project.
enable_signup = true
# Allow/disallow anonymous sign-ins to your project.
enable_anonymous_sign_ins = false
# Allow/disallow testing manual linking of accounts
enable_manual_linking = false
# Passwords shorter than this value will be rejected as weak. Minimum 6, recommended 8 or more.
minimum_password_length = 6
# Passwords that do not meet the following requirements will be rejected as weak. Supported values
# are: `letters_digits`, `lower_upper_letters_digits`, `lower_upper_letters_digits_symbols`
password_requirements = ""
[auth.rate_limit]
# Number of emails that can be sent per hour. Requires auth.email.smtp to be enabled.
email_sent = 2
# Number of SMS messages that can be sent per hour. Requires auth.sms to be enabled.
sms_sent = 30
# Number of anonymous sign-ins that can be made per hour per IP address. Requires enable_anonymous_sign_ins = true.
anonymous_users = 30
# Number of sessions that can be refreshed in a 5 minute interval per IP address.
token_refresh = 150
# Number of sign up and sign-in requests that can be made in a 5 minute interval per IP address (excludes anonymous users).
sign_in_sign_ups = 30
# Number of OTP / Magic link verifications that can be made in a 5 minute interval per IP address.
token_verifications = 30
# Number of Web3 logins that can be made in a 5 minute interval per IP address.
web3 = 30
# Configure one of the supported captcha providers: `hcaptcha`, `turnstile`.
# [auth.captcha]
# enabled = true
# provider = "hcaptcha"
# secret = ""
[auth.email]
# Allow/disallow new user signups via email to your project.
enable_signup = true
# If enabled, a user will be required to confirm any email change on both the old, and new email
# addresses. If disabled, only the new email is required to confirm.
double_confirm_changes = true
# If enabled, users need to confirm their email address before signing in.
enable_confirmations = false
# If enabled, users will need to reauthenticate or have logged in recently to change their password.
secure_password_change = false
# Controls the minimum amount of time that must pass before sending another signup confirmation or password reset email.
max_frequency = "1s"
# Number of characters used in the email OTP.
otp_length = 6
# Number of seconds before the email OTP expires (defaults to 1 hour).
otp_expiry = 3600
# Use a production-ready SMTP server
# [auth.email.smtp]
# enabled = true
# host = "smtp.sendgrid.net"
# port = 587
# user = "apikey"
# pass = "env(SENDGRID_API_KEY)"
# admin_email = "admin@email.com"
# sender_name = "Admin"
# Uncomment to customize email template
# [auth.email.template.invite]
# subject = "You have been invited"
# content_path = "./supabase/templates/invite.html"
# Uncomment to customize notification email template
# [auth.email.notification.password_changed]
# enabled = true
# subject = "Your password has been changed"
# content_path = "./templates/password_changed_notification.html"
[auth.sms]
# Allow/disallow new user signups via SMS to your project.
enable_signup = false
# If enabled, users need to confirm their phone number before signing in.
enable_confirmations = false
# Template for sending OTP to users
template = "Your code is {{ .Code }}"
# Controls the minimum amount of time that must pass before sending another sms otp.
max_frequency = "5s"
# Use pre-defined map of phone number to OTP for testing.
# [auth.sms.test_otp]
# 4152127777 = "123456"
# Configure logged in session timeouts.
# [auth.sessions]
# Force log out after the specified duration.
# timebox = "24h"
# Force log out if the user has been inactive longer than the specified duration.
# inactivity_timeout = "8h"
# This hook runs before a new user is created and allows developers to reject the request based on the incoming user object.
# [auth.hook.before_user_created]
# enabled = true
# uri = "pg-functions://postgres/auth/before-user-created-hook"
# This hook runs before a token is issued and allows you to add additional claims based on the authentication method used.
# [auth.hook.custom_access_token]
# enabled = true
# uri = "pg-functions://<database>/<schema>/<hook_name>"
# Configure one of the supported SMS providers: `twilio`, `twilio_verify`, `messagebird`, `textlocal`, `vonage`.
[auth.sms.twilio]
enabled = false
account_sid = ""
message_service_sid = ""
# DO NOT commit your Twilio auth token to git. Use environment variable substitution instead:
auth_token = "env(SUPABASE_AUTH_SMS_TWILIO_AUTH_TOKEN)"
# Multi-factor-authentication is available to Supabase Pro plan.
[auth.mfa]
# Control how many MFA factors can be enrolled at once per user.
max_enrolled_factors = 10
# Control MFA via App Authenticator (TOTP)
[auth.mfa.totp]
enroll_enabled = false
verify_enabled = false
# Configure MFA via Phone Messaging
[auth.mfa.phone]
enroll_enabled = false
verify_enabled = false
otp_length = 6
template = "Your code is {{ .Code }}"
max_frequency = "5s"
# Configure MFA via WebAuthn
# [auth.mfa.web_authn]
# enroll_enabled = true
# verify_enabled = true
# Use an external OAuth provider. The full list of providers are: `apple`, `azure`, `bitbucket`,
# `discord`, `facebook`, `github`, `gitlab`, `google`, `keycloak`, `linkedin_oidc`, `notion`, `twitch`,
# `twitter`, `x`, `slack`, `spotify`, `workos`, `zoom`.
[auth.external.apple]
enabled = false
client_id = ""
# DO NOT commit your OAuth provider secret to git. Use environment variable substitution instead:
secret = "env(SUPABASE_AUTH_EXTERNAL_APPLE_SECRET)"
# Overrides the default auth redirectUrl.
redirect_uri = ""
# Overrides the default auth provider URL. Used to support self-hosted gitlab, single-tenant Azure,
# or any other third-party OIDC providers.
url = ""
# If enabled, the nonce check will be skipped. Required for local sign in with Google auth.
skip_nonce_check = false
# If enabled, it will allow the user to successfully authenticate when the provider does not return an email address.
email_optional = false
# Allow Solana wallet holders to sign in to your project via the Sign in with Solana (SIWS, EIP-4361) standard.
# You can configure "web3" rate limit in the [auth.rate_limit] section and set up [auth.captcha] if self-hosting.
[auth.web3.solana]
enabled = false
# Use Firebase Auth as a third-party provider alongside Supabase Auth.
[auth.third_party.firebase]
enabled = false
# project_id = "my-firebase-project"
# Use Auth0 as a third-party provider alongside Supabase Auth.
[auth.third_party.auth0]
enabled = false
# tenant = "my-auth0-tenant"
# tenant_region = "us"
# Use AWS Cognito (Amplify) as a third-party provider alongside Supabase Auth.
[auth.third_party.aws_cognito]
enabled = false
# user_pool_id = "my-user-pool-id"
# user_pool_region = "us-east-1"
# Use Clerk as a third-party provider alongside Supabase Auth.
[auth.third_party.clerk]
enabled = false
# Obtain from https://clerk.com/setup/supabase
# domain = "example.clerk.accounts.dev"
# OAuth server configuration
[auth.oauth_server]
# Enable OAuth server functionality
enabled = false
# Path for OAuth consent flow UI
authorization_url_path = "/oauth/consent"
# Allow dynamic client registration
allow_dynamic_registration = false
[edge_runtime]
enabled = true
# Supported request policies: `oneshot`, `per_worker`.
# `per_worker` (default) — enables hot reload during local development.
# `oneshot` — fallback mode if hot reload causes issues (e.g. in large repos or with symlinks).
policy = "per_worker"
# Port to attach the Chrome inspector for debugging edge functions.
inspector_port = 8083
# The Deno major version to use.
deno_version = 2
# [edge_runtime.secrets]
# secret_key = "env(SECRET_VALUE)"
[analytics]
enabled = true
port = 54327
# Configure one of the supported backends: `postgres`, `bigquery`.
backend = "postgres"
# Experimental features may be deprecated any time
[experimental]
# Configures Postgres storage engine to use OrioleDB (S3)
orioledb_version = ""
# Configures S3 bucket URL, eg. <bucket_name>.s3-<region>.amazonaws.com
s3_host = "env(S3_HOST)"
# Configures S3 bucket region, eg. us-east-1
s3_region = "env(S3_REGION)"
# Configures AWS_ACCESS_KEY_ID for S3 bucket
s3_access_key = "env(S3_ACCESS_KEY)"
# Configures AWS_SECRET_ACCESS_KEY for S3 bucket
s3_secret_key = "env(S3_SECRET_KEY)"

View file

@ -0,0 +1,145 @@
create schema if not exists extensions;
create extension if not exists vector with schema extensions;
create extension if not exists pgcrypto with schema extensions;
-- ------------------------------------------------------------
-- profiles
-- ------------------------------------------------------------
create table public.profiles (
id uuid primary key references auth.users(id) on delete cascade,
created_at timestamptz not null default now(),
display_name text,
avatar_url text
);
-- ------------------------------------------------------------
-- entries
-- ------------------------------------------------------------
create table public.entries (
id uuid primary key default gen_random_uuid(),
user_id uuid not null references public.profiles(id) on delete cascade,
created_at timestamptz not null default now(),
transcript text not null,
audio_path text,
duration_secs int,
processing_status text not null default 'recorded'
check (
processing_status in (
'recorded',
'transcribing',
'transcribed',
'analyzing',
'pending_review',
'confirmed',
'error'
)
),
embedding vector(384),
summary text
);
create index entries_user_created_at_idx
on public.entries (user_id, created_at desc);
create index entries_user_status_created_at_idx
on public.entries (user_id, processing_status, created_at desc);
create index entries_embedding_idx
on public.entries
using ivfflat (embedding vector_cosine_ops)
with (lists = 100);
-- ------------------------------------------------------------
-- entry_analysis
-- ------------------------------------------------------------
create table public.entry_analysis (
entry_id uuid primary key references public.entries(id) on delete cascade,
created_at timestamptz not null default now(),
updated_at timestamptz not null default now(),
valence double precision check (valence between -1.0 and 1.0),
arousal double precision check (arousal between 0.0 and 1.0),
intensity double precision check (intensity between 0.0 and 1.0),
confidence double precision check (confidence between 0.0 and 1.0),
dominant_mood text,
analysis_status text not null default 'proposed'
check (analysis_status in ('proposed', 'pending_review', 'confirmed', 'corrected')),
model_version text
);
create index entry_analysis_status_idx
on public.entry_analysis (analysis_status);
create index entry_analysis_created_at_idx
on public.entry_analysis (created_at desc);
-- ------------------------------------------------------------
-- entry_mood_signals
-- ------------------------------------------------------------
create table public.entry_mood_signals (
id uuid primary key default gen_random_uuid(),
entry_id uuid not null references public.entries(id) on delete cascade,
mood text not null,
intensity double precision not null check (intensity between 0.0 and 1.0),
confidence double precision check (confidence between 0.0 and 1.0),
valence_weight double precision,
created_at timestamptz not null default now(),
unique (entry_id, mood)
);
create index entry_mood_signals_entry_id_idx
on public.entry_mood_signals (entry_id);
create index entry_mood_signals_mood_entry_id_idx
on public.entry_mood_signals (mood, entry_id);
-- ------------------------------------------------------------
-- entry_tags
-- ------------------------------------------------------------
create table public.entry_tags (
id uuid primary key default gen_random_uuid(),
entry_id uuid not null references public.entries(id) on delete cascade,
tag text not null,
confidence double precision check (confidence between 0.0 and 1.0),
created_at timestamptz not null default now(),
unique (entry_id, tag)
);
create index entry_tags_entry_id_idx
on public.entry_tags (entry_id);
create index entry_tags_tag_entry_id_idx
on public.entry_tags (tag, entry_id);
-- ------------------------------------------------------------
-- entry_feedback
-- ------------------------------------------------------------
create table public.entry_feedback (
id uuid primary key default gen_random_uuid(),
entry_id uuid not null references public.entries(id) on delete cascade,
user_id uuid not null references public.profiles(id) on delete cascade,
created_at timestamptz not null default now(),
field_name text not null,
old_value jsonb,
new_value jsonb,
reason text,
check (
field_name in (
'processing_status',
'analysis_status',
'valence',
'arousal',
'intensity',
'dominant_mood',
'mood_signals',
'tags',
'summary'
)
)
);
create index entry_feedback_user_created_at_idx
on public.entry_feedback (user_id, created_at desc);
create index entry_feedback_entry_id_idx
on public.entry_feedback (entry_id);