🗄️ Hybrid Data Engine: Registry → In-Memory Index (Dev) → Supabase (Prod)

This document defines the architecture for data sovereignty within Instant Ship™, moving from a simple TypeScript file for development to a global cloud authority for production.

1. The Strategy: "The 3-Tier Authority"

To avoid the dreaded fs.readFileSync is not a function errors in browser sandboxes (AI Studio), we utilize a Registry-First approach for development.

1. Tier 1: The Staging Registry (src/mocks/content/registry-*.ts)

   • Environment: Development & Sandbox.
   • What: A standard TypeScript file containing an array of objects.
   • Why: It requires ZERO environment configuration. AI can edit it easily, and the browser can import it directly without needing a filesystem (fs) module. This is the source for the in-memory index.

2. Tier 2: The Logic Engine for Development (In-Memory Index)

   • Environment: Development & Sandbox.
   • What: The useDocsDB hook automatically ingests the Registry (Tier 1) and builds a temporary, high-speed index in the browser's memory using JavaScript Map objects.
   • Why: It provides an instantaneous, database-like experience (O(1) lookups, simple search) without any backend, which is perfect for rapid prototyping in sandbox environments.

3. Tier 3: The Production Authority (Supabase)

   • Environment: Production.
   • What: A cloud-hosted PostgreSQL database.
   • Why: Once you are ready to launch, you migrate the data from the Registry to Supabase. This becomes the single source of truth for your live application, enabling multi-user editing, high performance, and persistent storage.

2. The "0-Code" Development Workflow

As a builder in a sandbox, you don't need to write complex data queries manually.

• To add a page: Tell Gemini: "Add a new item to registry-docs.ts for a tool called 'AI SEO Analyzer'."
• AI Action: It updates the TS file. The app detects the change and refreshes via HMR.
• Result: You manage your data by simply "editing a list," while the in-memory engine handles the technical complexity of indexing and retrieval for you during development. The migration to production is a separate, well-defined step.