Developer documentation
Design Principles
The architecture philosophy behind the current Quanta Workspaces MVP.
Quanta Workspaces is built around explicit ownership boundaries. The control plane owns state and policy. Workspace nodes run user sessions and services. Public edges serve visitor traffic. Integrations connect external systems without becoming the source of truth for everything.
Separate The Planes
The system is split into four planes:
| Plane | Design intent |
|---|---|
| Control | Make decisions, persist state, expose APIs, and audit changes. |
| Workspace | Run user-owned Linux environments and supervised processes. |
| Edge | Serve public HTTP traffic and route approved dynamic requests. |
| Integration | Connect LDAP, Forgejo, Nextcloud, Matomo, and shared assets. |
This keeps high-traffic request serving away from privileged orchestration and keeps user runtime behavior away from global state mutation.
Keep Identity Authoritative
LDAP is the identity and entitlement authority. Quanta can cache or project identity information into runtime systems, but it should not silently invent a conflicting identity model.
SSH, Linux users, Nextcloud users, and workspace ownership should all resolve back to the same identity vocabulary.
Publish Immutable Releases
Draft workspaces are mutable. Published sites are immutable releases.
draft workspace
-> Forgejo accepted event
-> release artifact
-> route update
-> edge hydration
This makes rollback, audit, and cache hydration tractable. It also prevents public site serving from depending on a live writable workspace.
Treat OpenResty As A Router And Server
OpenResty is on the public hot path, so it should make request-time routing decisions and serve cached content efficiently. It should not become the privileged orchestrator for LDAP, volume mutation, deployment state, or workspace lifecycle.
Route lookup, cache state, CGI dispatch, and service proxying are valid edge responsibilities. Durable state changes belong behind the control-plane API or worker processes.
Isolate User Runtime Behavior
Workspace shells, CGI scripts, and runit services are user runtime surfaces. They should be isolated with bwrap profiles, resource limits, filesystem ownership, and explicit route policies.
The default posture is narrow exposure:
- SSH goes through the gateway.
- Public static content is served from selected public trees or immutable releases.
- CGI is opt-in per site.
- Services are exposed only through approved routes.
Prefer Log-Based Analytics By Default
The MVP imports Matomo analytics from structured edge logs instead of injecting tracking scripts into user sites by default. This keeps analytics close to the actual serving path and avoids changing client website HTML just to measure traffic.
JavaScript analytics can remain a future option for cases that need browser-side events.
Use The Deep-Dive Docs For Details
This page explains the design posture. The canonical implementation references remain under the repository docs/ directory, especially the architecture, public edge routing, security model, observability, and operations documents.