test-repo/DB_TABLE_NAMING.md

---

🗄️ 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:

mission_control_documents
blog_messages
gantt_tasks
heartbeat_status

❌ INCORRECT:

mission-control_documents  -- No hyphens!
documents                  -- No prefix, will collide
mc_docs                    -- Abbreviation unclear

Creating New Tables

Always follow this pattern:

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:

-- 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!