MetaShift

MetaShift is the overall application (frontend + backend). ObserverShift is the System Intelligence Layer (telemetry, conflict detection, auto-resolution).

• Stack: Node.js (Express) backend, React + Vite + Tailwind frontend, Supabase DB.
• Real-time: WebSockets for live events; optional Supabase Realtime.
• Privacy: Telemetry only—no user content, screen data, camera/mic, or PII stored. See Trust & Privacy.

Primary job: See what needs attention and what was done about it. Run the demo, watch conflicts and resolutions, and replay any incident.

Monorepo layout

Folder	Purpose
backend/	Node + Express API, WebSocket, ObserverShift
frontend/	React + Vite + Tailwind UI
supabase/	SQL migrations + notes

Setup

Backend

cd backend
cp .env.example .env
npm install
npm run dev

• Server: http://localhost:3001
• Health (for Render / load balancers): GET /health → { "ok": true, "app": "MetaShift" }
• API health: GET /api/v1/health/ping → { "ok": true, "app": "MetaShift" }
• Pipeline status: GET /api/v1/health/pipeline → { last_telemetry_at, last_conflict_at }
• WebSocket: ws://localhost:3001/ws
• API versioning: use /api/v1/ prefix; legacy /api/ still works. See backend/openapi.yaml.

Frontend

cd frontend
cp .env.example .env
npm install
npm run dev

• UI: http://localhost:5173 (Vite proxies /api and /ws to the backend; leave VITE_BACKEND_URL empty or set to http://localhost:3001).
• Page shows MetaShift Online and ObserverShift Layer: Connected.

Supabase

• Run migrations in supabase/migrations/ in order (001–010: tenant_id, topology_edges, conflict_engine_cache, tenants_and_auth, RLS, usage_metrics, notification_webhooks, audit_log, api_keys).
• See supabase/NOTES.md and backend/frontend .env.example for SUPABASE_URL, SUPABASE_JWT_SECRET, and keys.

Auth and production features

• Auth: Supabase Auth (sign up / sign in). Backend verifies JWT (SUPABASE_JWT_SECRET) or API key (X-API-Key). Without JWT secret, dev mode allows unauthenticated access.
• Tenants: Workspace selector in the UI; all API requests send X-Tenant-ID. Tenants and membership in tenants and tenant_members.
• RLS: Tenant-scoped Row Level Security on all ObserverShift tables (see migration 006).
• Usage & billing: usage_metrics table and GET /api/v1/usage; Settings → Usage in the UI.
• Webhooks: Configure notification URLs in Settings → Webhooks; called on conflict_detected and conflict_resolved.
• Audit log: Actions logged to audit_log; read-only GET /api/v1/audit and Settings → Audit log.
• API keys: Create/revoke in Settings → API keys; use header X-API-Key for programmatic access.
• Export: GET /api/v1/export/events and GET /api/v1/export/conflicts with ?from=&to=&format=json|csv.
• Status: GET /api/v1/health/status and /status in the UI; footer links to System status and Help & contact.
• Retention: Optional node backend/scripts/retention-cleanup.js (see RETENTION_DAYS in env and Trust & Privacy).
• Tests: Backend npm run test (Jest); frontend npm run test (Vitest).

Optional: MetaShift + agent

• The "Advanced: Realtime session" in the UI is for use with an external agent service that posts events to this backend. Camera/mic are not used by this app unless that agent is configured to use them. See Trust & Privacy.

Deploy (Render + Vercel)

Do not commit .env or any file containing real keys or secrets. Copy .env.example to .env locally and set values in the host dashboard for production.

Render (backend + frontend)

1. Supabase: Create a project, run migrations from supabase/migrations/, and copy URL, anon key, service role key, and JWT secret.
2. Render: New → Blueprint → connect this repo. Render creates metashift-backend and metashift-frontend from render.yaml.
3. Backend: In the backend service, set env: SUPABASE_URL, SUPABASE_SERVICE_KEY, SUPABASE_JWT_SECRET, and CORS_ORIGIN (your frontend URL(s), comma-separated). Health check is GET /health.
4. Frontend: In the frontend service, set env: VITE_BACKEND_URL (backend URL, no trailing slash), VITE_SUPABASE_URL, VITE_SUPABASE_ANON_KEY. Redeploy so the build picks them up.
5. Open the frontend URL; dashboard and WebSocket should connect.

Vercel (frontend only)

1. Deploy the backend first (e.g. on Render) and note its URL.
2. Vercel → Add New → Project → import this repo. Set Root Directory to frontend.
3. Add env: VITE_BACKEND_URL (backend URL), VITE_SUPABASE_URL, VITE_SUPABASE_ANON_KEY. Deploy.
4. Set the backend’s CORS_ORIGIN to include your Vercel URL.

Full deploy guide — env var reference, checklist, and GitHub CI.

Docs

• Trust & Privacy – what we store, what we don’t, retention, agent sessions.
• Packaging & metrics – units for productizing (per env, per conflict, per events).

Checkpoint

• npm run dev in backend starts the Express server (MetaShift branding in logs and /api/v1/health/ping).
• npm run dev in frontend starts the Vite UI (dashboard, demo, incident replay).