🧪 Sandbox Data Ingestion Mechanism

Question: In a Sandbox environment (like Google AI Studio or StackBlitz), does the application actually load data from a source?

Answer: Yes. However, the "Source" is a memory structure, not a file system read operation.

1. The Data Source Paradox

In a production environment (Cloudflare Pages), the build script (scripts/generate-docs-db.mjs) scans the physical file system (.md files).

In a Sandbox, the browser cannot access the file system to run that build script.

• Physical Files: Exist in the virtual folder tree, but are inaccessible to the runtime code via fs.
• The Solution: We treat TypeScript Files as our "In-Memory File System".

The Registry as Source

Instead of reading docs/my-file.md, the app imports src/mocks/content/registry-docs.ts. This file contains the full content of the documentation, hardcoded into TypeScript objects.

typescript
// src/mocks/content/registry-docs.ts
export const docRegistry = [
  {
    id: "1001",
    slug: "project-plan",
    content: "# Project Plan\n\n..." // Full Markdown content lives here
  }
];

2. The Ingestion Process (Hydration)

When the application boots, the useDocsDB hook triggers the hydration sequence.

Step 1: Indexing

The hook imports the static registry array and builds a Map for O(1) lookup.

typescript
// hooks/useDocsDB.ts
const idIndex = new Map<string, RegistryItem>();
registry.forEach(item => {
  idIndex.set(`${item.lang}_${item.id}`, item);
});

Step 2: Querying

The UI components query this Map directly.

3. Verification & Telemetry

To confirm this process is working in your Sandbox:

1. Console Logs: Open DevTools. You will see:
   • [DB-INIT] 🚀 Using Local Registry (Mock Engine)...
   • [DB-HIT] Lookup ID: 1001
2. System Telemetry: On the Home page, the "Engine Telemetry" section visualizes the data flow from "Static Registry" to "In-Memory Engine".

4. Why This Matters

This architecture allows Instant Ship™ to provide a "Full Stack" experience (Content, Search, Filtering) within a "Client-Only" environment. It bridges the gap between rapid prototyping and production engineering.