---

## 🗄️ Shared Supabase Database - Table Naming Convention

**Date Documented:** February 22, 2026  
**Applies To:** All web apps using shared Supabase project (`qnatchrjlpehiijwtreh`)

### The Rule

**ALWAYS use `<project_name>_<table_name>` format with underscores (NO hyphens)**

### Why This Matters

- All Vercel-deployed web apps share ONE Supabase project
- Prevents table name collisions between apps
- Maintains clean separation of data per app
- Enables cross-app queries when needed (via user_id or shared keys)

### Current Apps & Table Prefixes

| App | URL | Table Prefix | Example Tables | Notes |
|-----|-----|--------------|----------------|-------|
| **Gantt Board** | https://gantt-board.twisteddevices.com | *(none - legacy)* | `tasks`, `projects`, `sprints`, `users` | **First app** - created before naming convention. Tables have no prefixes. |
| **Blog Backup** | https://blog.twisteddevices.com | `blog_` | `blog_messages`, `blog_tags` | Uses prefix convention ✅ |
| **Mission Control** | https://mission-control.twisteddevices.com | `mission_control_` | `mission_control_documents`, `mission_control_folders` | Uses prefix convention ✅ |
| **Heartbeat Monitor** | http://localhost:3005 | `heartbeat_` | `heartbeat_status`, `heartbeat_logs` | Uses prefix convention ✅ |

### Legacy Tables (No Prefix)

**Gantt Board** was the first app and predates the naming convention. Its tables remain without prefixes:
- `tasks`
- `projects`
- `sprints`
- `users` (shared)

**Future Consideration:** If we need to avoid confusion, we could migrate these to `gantt_tasks`, `gantt_projects`, etc. But for now, they remain as-is since Gantt Board is the primary app.

**All NEW apps MUST use prefixes.**

### Naming Convention Details

**✅ CORRECT:**
```sql
mission_control_documents
blog_messages
gantt_tasks
heartbeat_status
```

**❌ INCORRECT:**
```sql
mission-control_documents  -- No hyphens!
documents                  -- No prefix, will collide
mc_docs                    -- Abbreviation unclear
```

### Creating New Tables

**Always follow this pattern:**

```sql
CREATE TABLE <project_name>_<table_name> (
  id uuid DEFAULT gen_random_uuid() PRIMARY KEY,
  -- your columns
  created_at timestamptz DEFAULT now(),
  updated_at timestamptz DEFAULT now(),
  user_id uuid REFERENCES auth.users(id)
);

-- Enable RLS
ALTER TABLE <project_name>_<table_name> ENABLE ROW LEVEL SECURITY;

-- Add policies
CREATE POLICY "Allow all" ON <project_name>_<table_name>
  FOR ALL USING (true) WITH CHECK (true);
```

### Shared Tables (No Prefix)

These tables are shared across ALL apps:
- `users` — Auth users (managed by Supabase Auth)
- `profiles` — User profiles (shared)
- `auth` tables — Managed by Supabase

### When Adding a New App

1. **Choose a prefix:** Short, clear, unique
   - Example: `finance_`, `habit_`, `inventory_`

2. **Document it:** Add to the table above

3. **Use consistently:** Every table gets the prefix

4. **Update .env.local:** Copy from existing project:
   ```
   NEXT_PUBLIC_SUPABASE_URL=https://qnatchrjlpehiijwtreh.supabase.co
   NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
   ```

### Querying Across Apps

Since tables are prefixed, you can join across apps if needed:

```sql
-- Example: Get user's tasks from Gantt + documents from Mission Control
SELECT 
  gantt_tasks.title as task,
  mission_control_documents.title as doc
FROM gantt_tasks
JOIN mission_control_documents 
  ON gantt_tasks.user_id = mission_control_documents.user_id
WHERE gantt_tasks.user_id = '<user-id>';
```

### Migration Checklist

When moving an app from LocalStorage to Supabase:

- [ ] Choose table prefix (if not already set)
- [ ] Create tables with prefix in Supabase SQL Editor
- [ ] Update frontend to use Supabase client
- [ ] Migrate existing data (if any)
- [ ] Test CRUD operations
- [ ] Document the prefix in this file

### Related Files

- **Supabase Project:** https://supabase.com/dashboard/project/qnatchrjlpehiijwtreh
- **Connection String:** In each app's `.env.local`
- **Shared Config:** `SPECIALIZED_AGENTS.md` (web-dev section)

---

**Remember:** When in doubt, use the full project name with underscores. No hyphens, no abbreviations, no exceptions!