Frontend
Next.js App Router, global marketing pages, dashboard screens, documentation hub, auth callbacks, server components, and API route handlers.
Build, configure, deploy, and extend UmamiEdge.
Follow this sequence to move from a clean local project to a production-ready global distributed AI compute control plane.
Quick commands
Developer quick reference.
| Task | Command or endpoint |
|---|---|
| Local setup | npm install && npm run dev |
| Build | npm run build |
| Schema order | docs/supabase-schema.sql → docs/rls-policies.sql → docs/seed-demo.sql |
| Health check | GET /api/health |
| Readiness check | GET /api/readiness/check |
| OpenAI-compatible gateway | GET /api/v1/models · POST /api/v1/chat/completions · POST /api/v1/embeddings |
Architecture
The control-plane layers.
Supabase
Postgres tables, RLS policies, OAuth, magic links, tenant membership, node telemetry, usage events, incidents, audit events, and seed data.
Node Agent
Linux TypeScript collector starter that reports GPU, power, latency, temperature, memory, and heartbeat telemetry.
Routing
Explainable routing stubs that score nodes by health, latency, available power, region policy, runtime status, and tenant quota.
Gateway
OpenAI-compatible API surfaces for /api/v1/models, /api/v1/chat/completions, and /api/v1/embeddings.
Operations
Incidents, SLA, failover, billing control, compliance evidence, runtime marketplace, customer success, support, and admin/audit screens.
Implementation path
Eight engineering steps from local setup to production.
Each step includes owner, outcome, actions, and acceptance evidence so the team can execute consistently.
Prepare the local workspace
Owner: Developer
A clean Next.js project running locally without legacy route leftovers.
- Extract the ZIP into a new empty folder instead of overwriting an old project.
- Run npm install from the project root.
- Copy .env.example to .env.local.
- Run npm run dev and open http://localhost:3000.
Acceptance evidence: Homepage loads, /docs opens, and /api/health returns a JSON response.
Configure environment variables
Owner: Developer + Supabase admin
The app can connect to Supabase from browser, server routes, and admin-only workflows.
- Set NEXT_PUBLIC_SITE_URL for local and production domains.
- Set NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY.
- Set SUPABASE_SERVICE_ROLE_KEY only in server-side environment variables.
- Restart the dev server after editing environment variables.
Acceptance evidence: Login page renders without missing configuration warnings.
Run database compatibility fixes
Owner: Database owner
Older Supabase databases are upgraded before the main schema and seed scripts run.
- Open Supabase SQL Editor.
- Run docs/database-compatibility-fixes.sql first.
- Run docs/supabase-schema.sql second.
- Run docs/rls-policies.sql third.
- Run docs/seed-demo.sql only after schema and policies complete successfully.
Acceptance evidence: No missing column, duplicate enum, function parameter, or not-null seed errors appear.
Configure Supabase Auth
Owner: Platform admin
Google, GitHub, and magic-link sign-in work locally and in production.
- Enable Google and GitHub providers in Supabase Auth.
- Add http://localhost:3000/auth/callback to redirect URLs.
- Add https://YOUR_DOMAIN/auth/callback to production redirect URLs.
- Use Supabase provider callback URLs in the Google/GitHub developer consoles.
- If stale sessions appear, open /api/auth/clear?next=/login and sign in again.
Acceptance evidence: Login with Google or GitHub returns to / by default and /login?next=/operator returns to /operator.
Verify tenant onboarding
Owner: Developer + operator
A signed-in user can create an organization, site, node, and node API key.
- Open /onboarding.
- Create an organization.
- Create a site with region, city, power capacity, and connectivity tier.
- Register a node and copy the generated key once.
- Check /nodes, /nodes/keys, and /operator.
Acceptance evidence: Organization switcher appears in the header and node inventory shows the new node.
Install and test the node agent
Owner: Infrastructure engineer
A Linux node can send authenticated telemetry into the control plane.
- Copy agent/config.example.json to agent/config.json.
- Set the API base URL, node ID, organization ID, and node API key.
- Run the agent manually first with ts-node or your preferred TypeScript runner.
- On GPU hosts, verify nvidia-smi is available.
- Install the systemd service only after the manual test succeeds.
Acceptance evidence: Telemetry events appear in /telemetry and the node heartbeat updates in /operator.
Validate APIs and routing
Owner: API engineer
Gateway routes, routing simulation, and readiness APIs respond predictably.
- Call GET /api/v1/models.
- Call POST /api/v1/chat/completions with a sample message.
- Call POST /api/v1/embeddings with a sample input.
- Open /routing and test /api/router/simulate.
- Open /readiness and /api/readiness/report.
Acceptance evidence: Responses include model/runtime metadata, routing reasons, and readiness status.
Deploy and verify production
Owner: Release owner
Vercel production deployment is authenticated, monitored, and ready for pilot users.
- Create a fresh Vercel project from the clean repository.
- Add environment variables in Vercel.
- Run npm run build locally before pushing.
- Deploy and verify /api/health, /login, /operator, /docs, and /status.
- Run docs/deployment-health-checks.md as the release checklist.
Acceptance evidence: Production domain passes health, auth, dashboard, and API smoke tests.
Smoke tests
Minimum checks before handing the system to users.
| Area | Endpoint | Purpose |
|---|---|---|
| Health | GET /api/health | Confirms the Next.js API layer is responding. |
| Readiness | GET /api/readiness/report | Checks production-readiness gates. |
| Models | GET /api/v1/models | Verifies OpenAI-compatible model discovery. |
| Routing | GET /api/router/simulate | Confirms routing simulation is available. |
| Enablement | GET /api/enablement/checklist | Returns the developer and user step checklist. |
| Status | GET /api/status | Checks operational status surface. |
Troubleshooting
Common build, auth, and migration fixes.
Legacy routes still compile
Run bash scripts/cleanup-legacy-routes.sh, then remove .next and rebuild from a fresh extraction.
Invalid refresh token
Open /api/auth/clear?next=/login and sign in again. This clears stale Supabase auth cookies.
CREATE TYPE already exists
Run docs/database-compatibility-fixes.sql before the main schema.
Missing key_prefix, metadata, connectivity_tier, or deployment version
Run docs/database-compatibility-fixes.sql, then rerun schema and seed scripts.
Google login returns to the wrong page
Check NEXT_PUBLIC_SITE_URL and Supabase redirect URLs for /auth/callback.
Node telemetry rejected
Confirm the node key prefix/hash is active, the key is not revoked, and the agent points to the correct API base URL.