Architecture
How the Neutrino platform is structured — from the API gateway down to your feature packages.
Architecture
Neutrino is a platform orchestration layer built on Cloudflare. It provisions cloud infrastructure for you, manages a multi-tenant runtime, and gives your users a console shell composed from pluggable feature packages.
The simplest mental model:
Neutrino = Infrastructure provisioner + Feature package runtime + Multi-tenant shell + CLI toolchainRequest flow
Every API call from your users travels the same path:
Browser / API client
↓
Gateway (single entry point — auth, rate limiting, routing)
↓
Internal services (Registry, IAM, Billing, Provisioning, …)
↓
Cloudflare D1 / R2 / KV (per-platform resources)The Gateway is the only public surface. All internal services are reachable only through it.
Caveat: Per-platform auth Workers are also publicly addressable at
auth.svc.{stackId}.{platformId}.nno.appand bypass the Gateway. Sign-in flows go directly to those Workers; only application API calls flow through the Gateway.
Class 1 vs Class 2 projects
Neutrino hosts two distinct kinds of project on the same infrastructure (per ADR-016):
| Class 1 — Platform console | Class 2 — End-user project | |
|---|---|---|
| Audience | Neutrino operators / partners | End-user developers |
| Created by | services/cli POST /api/v1/platforms (operator action) | nno project init (user action) |
| Source code | This monorepo (nno-app-builder) | Cloned from github.com/neutrino-io/nno-app-starter |
| GitHub repo | Mandatory; NNO-managed via Trees API (per ADR-015) | Optional; user-managed |
| Feature activation | git commit to platform repo | Future ADR (likely runtime registry-fetch) |
| CF Pages source | Git-source binding to platform repo | Direct upload (future nno project deploy) |
| Registry row | platforms.class = 'platform' | platforms.class = 'user_project' |
| Auth audience | Operator API key + per-platform sessions | nno-cli session (gateway-mediated) |
The two share the gateway, the IAM service, and the platforms table — but lifecycle, ownership, and feature semantics differ. The CLI commands nno project init, nno project dev, nno project build operate on Class 2 projects.
Core services
| Service | What it does |
|---|---|
| Gateway | Routes all API traffic. Enforces auth, rate limiting, CORS, and request tracing. |
| IAM | Identity and access management for Neutrino itself. Issues API keys per platform. |
| Registry | Source of truth for all platforms, tenants, stacks, resources, and active features. |
| Provisioning | Calls the Cloudflare API to create Workers, Pages apps, D1 databases, R2 buckets, and KV namespaces on your behalf. |
| Billing | Stripe-backed subscriptions, usage metering, and quota enforcement. |
| Stack Registry | Versioned catalogue of Neutrino-authored stack templates that platform admins can activate. |
| CLI Service | Manages per-platform GitHub repositories and triggers Cloudflare Pages builds. |
Four layers
Neutrino organises everything into four layers:
- Neutrino Core — the meta-platform itself (Gateway + services above). You interact with it via the console or CLI.
- Platform — your product. One platform per client. Gets its own isolated Cloudflare resources.
- Tenant / Sub-Tenant — logical partitions within a platform (business units, customer accounts, teams).
- Feature Packages & Stacks — the UI and backend Workers that make up your application, grouped into Stacks.
Your users only ever see Layer 3 (the console shell) and the features inside it. Layers 1 and 2 are infrastructure that Neutrino operates on your behalf.
Suspension enforcement window: Gateway caches IAM session validations for 5 minutes (in-memory per Worker isolate). A platform suspension may take up to 5 minutes to fully propagate to running sessions; the Gateway's KV-backed
platform:{id}:statuslookup (60s TTL) is the faster path for real-time suspension.
What Neutrino provisions for you
When you onboard a platform, Neutrino automatically creates:
- An auth Worker and D1 database (
{platformId}-default-auth) - A console shell deployed to Cloudflare Pages
- DNS entries under
*.{platformId}.nno.app - Additional resources per Stack you activate
All resource names embed your platform ID so they are uniquely identifiable and never conflict with other platforms sharing the same Cloudflare account.