Implementation Roadmap
Current status: protocol specifications (draft). Runtimes are planned deliverables — not yet available.
Faberio — reproducible self-hosted runtime for portable, user-owned distributed applications on NixOS.
Faberio is designed to enable applications whose data lives on a network of nodes — participants' personal devices (smartphones, tablets, laptops, personal computers) and/or always-on servers run by users or independent operators — with cryptographic identity, administrator-gated trust, and background replication, without dependence on centralized SaaS infrastructure.
This page describes the full platform roadmap and the current development scope focused on the reference Runtime, NixOS deployment, and multi-node validation.
The immediate goal is to prove the architecture with a working reference implementation before expanding to additional platforms and application categories.
Faberio targets data decoupling (participant-owned state, not vendor SaaS storage), service portability (same runtime and protocol across nodes and deployments), and NixOS (reproducible self-hosted nodes).
Current Scope: Reference Runtime & Validation
The first development cycle covers Phase 2 (reference Runtime and deployment) and Phase 3 (multi-node validation with a demonstration application). Earlier protocol work (Phase 1) continues in parallel as specifications are refined during implementation.
Server-side NixOS runtime first; mobile Runtime later. The current scope delivers an operator-deployable Laravel Runtime on NixOS (and containers) and on PC/laptop nodes, validated through a Federated Community Hub demo (browser application). A Flutter-based Runtime for phones and tablets is Phase 4 — after the server reference implementation is proven.
Reference implementation milestones
The milestones below deliver a credible end-to-end proof within the current development cycle — not every capability listed in the full protocol specifications. M1–M2 build platform infrastructure (identity through replication and deployment); M3 implements, validates, and releases the Federated Community Hub on top. What sits outside this cycle is listed in Out of scope below and in specs/index — Reference MVP coverage.
| Milestone | Timeline | Deliverables |
|---|---|---|
| M1 — Platform foundation | Months 1–4 | Ed25519 identity; node discovery and information-space membership; MongoDB as the local storage engine and file storage (local); simplified peer connectivity between dev nodes |
| M2 — Replication, deploy & trust | Months 5–8 | Node-level DB replication (MongoDB-backed records) and node-level FS replication between server peers; NixOS module and container image; node and user admin approval flows; DAC on platform paths; stable connectivity between server nodes |
| M3 — Community Hub validation & release | Months 9–12 | Laravel SDK for Community Hub records; Federated Community Hub demo as an in-runtime application (core flows); 3-node validation — approved membership, participant/event/document and attachment replication, offline recovery, access denial for unapproved users; operator docs; CI; basic security review; open release under Apache-2.0 / CC BY 4.0 |
Each milestone spans four months. Platform plumbing and replication (including file storage) complete in M2; all Community Hub work — SDK, demo application, multi-node validation, operator docs, CI, security review, and release — sits in M3. The reference MVP uses MongoDB as the storage engine on each node for M1–M3 (see Technology Stack); the Faberio Protocol remains engine-neutral.
Delivery sequence
The delivery path is server-side first:
- A Linux or container hosted reference Runtime on Laravel (PHP) for servers and PC/laptop nodes
- Multi-node validation with a Federated Community Hub demo (browser UI)
- A separate Flutter-based Runtime for phones and tablets after the server reference is proven (Phase 4)
Laravel/PHP rationale
Laravel (PHP) is chosen for the server and PC/laptop reference Runtime because it minimises time-to-validation: mature HTTP, queue, database, and filesystem tooling allow a small team to ship a NixOS-deployable node and a Federated Community Hub demo in the first development cycle.
The Faberio Protocol stays implementation-neutral. Laravel is the first conforming reference for server-class and desktop-class hosts, not the universal Runtime for every device class.
| Host class | Reference Runtime | Status |
|---|---|---|
| Servers (NixOS, containers, VPS, on-prem) | Laravel (PHP) | Current scope |
| PC / laptop | Laravel (PHP) | Current scope |
| Mobile (iOS, Android) and additional server-side stacks (Go, Rust, …) | Flutter (mobile); future Runtimes (Go, Rust, …) | Phase 4 |
The Flutter Runtime is a full Runtime on the device — hosting applications, maintaining a local replica, and participating in background replication — not merely a mobile UI client talking to a remote Laravel server.
In scope
| Area | Deliverable |
|---|---|
| Reference Runtime | Laravel (PHP) on server, PC, and laptop nodes — platform services M1–M2; Laravel SDK M3 |
| Distributed database | MongoDB on each node for application records (M1–M3); protocol remains engine-neutral |
| Deployment | NixOS module and OCI container image — reproducible self-hosted nodes (M2) |
| Replication | Node-level background replication of database records and file storage objects between server nodes (M2) |
| Distributed file storage | Local file engine (M1); node-level FS replication between server peers (M2); Community Hub attachments in the demo (M3) |
| Validation | Multi-node test environment (NixOS + containers) — M3 |
| Demonstration app | Federated Community Hub (M3) — in-runtime browser UI via Laravel SDK; local-first Community Hub records, admin approval, and replication |
| Operations | CI pipeline, operator deployment documentation (see Operator deployment expectations), basic security review — M3 |
Out of scope
| Area | Planned phase |
|---|---|
| Full distributed file storage replication — large-scale hardening, flexible full sync (lazy loading, metadata-first), and CRDT content merge beyond node-level peer replication in the reference MVP | Phase 4 |
| User-level background replication (user devices) | Phase 4 |
| Native access (direct DB client / filesystem) | Phase 4 |
| External HTTP API (external applications) | Phase 4 |
| Full NAT/P2P connectivity (consumer-device topology) | Phase 4 |
| Flutter Runtime (mobile) and additional server-side Runtimes (Go, Rust, …) | Phase 4 |
| External federation adapters (third-party social protocols) | Phase 4 |
| Complete protocol specification for all edge cases | Ongoing (Phase 1) |
Success criteria
When Phase 2 and Phase 3 are complete, the project will demonstrate that:
- An operator deploys a Faberio node with one command on NixOS (or container equivalent)
- Three nodes form an information space with administrator-approved node membership
- Users register with cryptographic identity, are approved by an administrator, and use core Community Hub flows (participants, events, documents) through the demo application (browser UI)
- Community Hub records replicate across nodes through background replication — no user-initiated cross-node requests
- A node going offline and rejoining recovers state from peers
- All Runtime code and deployment configuration are published under the Apache License 2.0; specifications and operator documentation under CC BY 4.0
Together, these outcomes demonstrate decoupled data on operator nodes, portable services via the open protocol, and reproducible hosting on NixOS.
Sustainability (open maintenance, community self-hosting, Phase 4 expansion) is described in Sustainability. High-level security assumptions and threats are in Threat Model. Related work (CouchDB/PouchDB, Automerge, Solid, ATProto, Yjs) is in Related Work.
Full Platform Roadmap
Development proceeds in four phases. Each phase produces a concrete deliverable that validates assumptions before the next phase begins.
| Phase | Focus | Outcome | Status |
|---|---|---|---|
| 1. Protocol Specification | Define open, interoperable protocol | Published specification documents | Ongoing |
| 2. Reference Runtime & SDK | Laravel Runtime for server, PC, and laptop; Laravel SDK | Working node on NixOS and in containers (planned) | Current scope |
| 3. Idea Validation | End-to-end proof of distributed operation | Validated architecture with Community Hub demo | Current scope |
| 4. Applications & Multi-platform | Distributed apps and additional Runtimes | Production applications; Flutter Runtime for mobile | Future |
Phase 1: Protocol Specification
The foundation of Faberio is the open protocol — not a specific Runtime implementation. All subsequent work depends on a clear, complete specification that independent implementations can follow.
Scope
Protocol specifications define how independently operated nodes identify themselves, discover peers, establish connectivity, replicate state, and enforce access control. See the current Specs section for work in progress.
| Area | Specification |
|---|---|
| Identity | Identity Model, Object Identifier |
| Networking | Node Discovery, Node Connectivity |
| Runtime-internal | Messaging, RPC |
| Application state | Distributed Database, Distributed File Storage |
| Security | Data Access Control |
Goals
- Define message formats, service contracts, and behavioral requirements with enough precision for independent implementations.
- Ensure specifications are implementation-neutral — they describe what nodes MUST do, not how a particular Runtime achieves it.
- Publish specifications as living documents that evolve based on implementation feedback from Phase 2.
Phase 1 continues in parallel with Phase 2: specifications are refined as the reference Runtime reveals gaps and edge cases.
Phase 2: Reference Runtime & Laravel SDK
The first Runtime implementation validates the protocol through working software on servers and PC/laptop nodes. It serves as the reference implementation — the baseline against which protocol compliance and interoperability are measured.
Platform scope: Laravel (PHP) is the reference Runtime for server-side deployment (NixOS, VPS, datacenter, home server) and for PC and laptop nodes. It is not intended for mobile phones or tablets — those require a separate Flutter Runtime (Phase 4).
Technology Stack
| Component | Choice | Rationale |
|---|---|---|
| Runtime | Laravel (PHP) | Server and PC/laptop reference implementation — see Laravel/PHP rationale |
| Database | MongoDB | Reference storage engine for M1–M3; document model fits flexible Community Hub records; change streams enable future native engine access (deferred from MVP). Protocol remains engine-neutral — see Distributed Database — Storage Engine Abstraction |
| SDK | Laravel package | Native integration with the Runtime; in-runtime Community Hub demo in M3 |
| HTTP API | Runtime REST/HTTP endpoints | External application access — Phase 4 (see Introduction — Runtime-managed Applications) |
| Native access | Direct database client and filesystem operations | Full protocol target; deferred from reference MVP (MongoDB change streams are the planned path) |
Runtime Capabilities
The full protocol defines a complete platform. The reference Runtime implements platform services in M1–M2, then the Community Hub validation and release path in M3. See Reference implementation milestones.
| Capability | Reference MVP | Full protocol target (spec / later) |
|---|---|---|
| Node identity and authentication | ✅ M1 — Ed25519, node records | — |
| Peer discovery and membership | ✅ M1 — information space; M2 — admin approval | — |
| Peer connectivity | ✅ M1–M2 — between server nodes (simplified) | Full NAT/P2P (Node Connectivity) |
| Distributed database + replication | ✅ M1 MongoDB local engine; M2 node-level sync | User-level sync; full engine abstraction |
| Distributed file storage + replication | ✅ M1 local engine; M2 node-level sync | Large-scale hardening; flexible sync §9.4 |
| Data access control | ✅ M2 — platform policies | Full DAC surface |
| HTTP API | ⏸ Phase 4 — external applications | Full external API |
| Native access | ⏸ Phase 4 | DB client / filesystem paths |
| Laravel SDK | ✅ M3 — in-runtime Community Hub demo | General-purpose SDK |
Applications running inside the Runtime use the Faberio Laravel SDK. The Federated Community Hub demo is an in-runtime application on that path. External applications interact through the HTTP API in Phase 4.
Deployment Targets
The Laravel reference Runtime is designed for server-class and desktop-class hosts — not mobile devices:
| Target | Description |
|---|---|
| NixOS server | Declarative system configuration; reproducible deployments on bare metal, VPS, and datacenter |
| Container | Docker/OCI-compatible image for portable deployment across server environments |
| PC / laptop | Developer or personal always-on node on desktop operating systems (same Laravel Runtime codebase) |
Both NixOS and container targets use the same Runtime codebase. NixOS provides reproducible system-level deployment; containers provide portability for development, CI, and cloud-adjacent hosting. Neither deployment model implies centralized infrastructure — operators run nodes wherever they choose. See Application Examples — Decentralized Server Placement.
This split directly supports reproducible self-hosting: NixOS for declarative production nodes, containers for service portability across environments, and the Runtime protocol layer for data decoupling — application services run on any node while state remains with participants in the information space.
Operator deployment expectations
The reference cycle delivers operator-facing deployment artefacts in M2 (NixOS module + container image) and M3 (operator documentation). This section states what operators SHOULD expect when self-hosting a Faberio node — aligned with reproducible self-hosting and with protocol rules in Node Discovery §10 (backup, export, migration).
Deployment paths
| Path | Operator experience (target) | Primary use |
|---|---|---|
| NixOS module | Declarative enablement — e.g. services.faberio.enable = true; plus options for information space, peers, TLS, and secrets | Production and home-server nodes; reproducible declarative config |
| OCI container | Same Runtime image with environment variables or mounted config for space membership, bootstrap peers, and secrets | CI, VPS, development, portable hosting |
| PC / laptop | Container or local Laravel install for dev and personal always-on nodes | Validation, contributors, small deployments |
Success criterion #1 — deploy with one command on NixOS (or container equivalent) — means a documented default module/container profile that starts the Runtime, MongoDB, and web demo UI without manual Laravel setup.
Configuration the operator owns
Operators MUST supply and maintain:
| Area | Operator responsibility |
|---|---|
| Node identity | Node Ed25519 key pair — generated on first boot or injected from secret store; never committed to git |
| Information space | Join existing space (bootstrap peer + admin approval) or create a new space as founding administrator |
| Connectivity | Listen addresses, TLS certificates, firewall rules; bootstrap peer list for discovery (Node Discovery) |
| STUN/TURN policy | Optional relay configuration per Node Connectivity §7.6 — reference MVP uses simplified connectivity between server nodes |
| Secrets | Database credentials, TURN credentials, TLS keys — via NixOS sops/agenix, container secrets volume, or host secret store |
| Backup | Local replica backup and node key backup per Distributed Database §10.1; no default upload to a Faberio cloud |
Applications and end-user data remain in the operator’s information space on nodes the operator controls — not on Faberio-operated infrastructure.
NixOS module (M2 deliverable — expectations)
The reference NixOS module SHOULD expose at minimum:
services.faberio.enable— master switch- Information space identifier or creation mode (join vs founding node)
- Bootstrap peer addresses and ports
- TLS / reverse-proxy integration hooks (or documented nginx/caddy pattern)
- Paths for persistent state (database, file attachments if enabled)
- Secret references for node private key and optional TURN credentials
- Versioned module interface documented in operator docs (M3)
Upgrades SHOULD follow normal NixOS rebuild / roll-back — declarative config in git, reproducible closure. The module MUST NOT require a proprietary control plane.
Container image (M2 deliverable — expectations)
The OCI image SHOULD:
- run the same Runtime entrypoint as NixOS
- accept equivalent configuration via environment variables or mounted config files
- persist state on a named volume
- document required ports (HTTP/HTTPS for demo UI and API; peer connectivity between nodes)
- ship with a compose example for single-node and three-node validation layouts
Operator documentation (M3 deliverable)
Operator documentation (CC BY 4.0) SHOULD cover:
- First boot — generate or import node key; join or create information space; approve pending nodes/users
- Multi-node layout — three-node validation topology (on-premise + VPS + container)
- Backup and recovery — local backup; restore; peer snapshot recovery (RPC)
- Node migration — redeploy on new host, same space (Node Discovery §10.4)
- Updates — NixOS channel or container image tag policy; dependency security updates via CI
- Observability — local logs and replication health; no mandatory vendor telemetry (Threat Model — No tracking or exploitation)
- Community Hub demo — browser URL and admin flows for operators hosting the demo UI
Full portable export/import CLI may ship after M3; M2–M3 prioritizes peer snapshot recovery and operator backup as in specs/index — Reference MVP coverage.
Reference MVP limitations (operator-facing)
Operators SHOULD be aware that the first release intentionally limits scope:
- Server nodes first — not user-device Flutter nodes (Phase 4)
- Node-level DB and FS replication — validated in M2; Community Hub tables and attachments exercise both in M3
- Simplified peer connectivity between server nodes — not full consumer NAT topology
- Federated Community Hub demo — not native mobile/desktop clients
These limits are documented so operators do not expect production mobile clients or external federation adapters from the reference package alone.
Deliverables
- Faberio Runtime (Laravel) implementing reference MVP capabilities in the table above
- Faberio Laravel SDK for the in-runtime Federated Community Hub demo
- NixOS module and container image for node deployment
- Operator deployment documentation — setup, backup, migration, updates (see Operator deployment expectations)
- Documentation for SDK usage and validation results
- Deferred from reference MVP: external HTTP API; full native access layer; user-level device replication; Community Hub work before M3
Phase 3: Idea Validation
Before expanding to multiple platforms and application categories, the reference Runtime must prove the core architectural ideas in realistic scenarios.
The current scope validates the architecture through a Federated Community Hub demonstration application (browser UI on the server Runtime) on a three-node test network. Full application categories (Local Civic Platform, Resilient Emergency Collaboration, and other business applications) and additional validation scenarios are planned for Phase 4.
Validation Criteria (current scope)
| Criterion | What it proves |
|---|---|
| Multi-node replication | Database records and file objects (attachments) synchronize correctly across server nodes — platform replication in M2, Community Hub validation in M3 |
| Information spaces | Approved nodes form trusted networks with independent access policies |
| Administrator approval | Node and user membership require explicit administrator approval |
| Cryptographic identity | Users authenticate with key pairs registered in the information space |
| Offline operation | The Federated Community Hub demo functions against the local replica while a server node is disconnected; state reconciles after reconnection |
| Background replication | Node-level sync between server nodes — no user-initiated cross-node operations; user-level device replication is Phase 4 |
| Decentralized deployment | Nodes run on NixOS and in containers at different locations |
Validation Criteria (future — Phase 4)
| Criterion | What it proves |
|---|---|
| HTTP API interoperability | External applications access replicated state through the API |
| Native access | Co-located tools read and write data with low latency |
| Server-optional operation | Networks of personal devices function; adding always-on servers run by users or operators improves stability |
Validation Approach
Validation uses a controlled three-node test environment — NixOS deployments and containers representing different node locations (on-premise, VPS, local development).
The Federated Community Hub demo exercises the patterns described in Application Examples — Federated Community Hub as an alternative to vertical SaaS community platforms: local hub state, administrator-approved users, background replication, and optional 24/7 organization node — without dependence on a third-party community SaaS provider or a native mobile client.
Phase 3 is complete when the reference Runtime and Community Hub demo demonstrate end-to-end distributed operation according to the protocol specification. Gaps discovered during validation feed back into Phase 1 (spec updates) before Phase 4 begins.
Phase 4: Distributed Applications & Multi-platform Runtimes
Future work — not part of the current reference Runtime and validation scope.
With a validated reference implementation, development expands in two directions: applications that exercise the platform in production scenarios, and additional Runtimes and SDKs that broaden platform reach.
Distributed Applications
Development of real applications on the validated platform — starting with categories outlined in Application Examples:
- Production Federated Community Hub — native mobile/desktop clients, richer federation between organization nodes, production hardening (the validation demo is current scope, not Phase 4)
- Local Civic Platform — initiatives, volunteer groups, hearings, local news, voting, documents, resource maps; per-community servers with federation
- Resilient Emergency Collaboration — local-first messages, tasks, map, contacts, resources, and event logs under intermittent connectivity
- Other business applications — operator-owned operational software with local-first records and optional always-on company nodes
These applications serve dual purposes: they deliver user value and stress-test the platform under realistic workloads. Application development reveals protocol and Runtime improvements needed for production use.
Platform hardening (planned)
Later platform work SHOULD add flexible full synchronization for large datasets and mobile clients:
| Capability | Purpose |
|---|---|
| Lazy loading | Fetch full record or file content only when read or prefetched |
| Paginated snapshot | Extended offline recovery without monolithic RPC transfers |
| Metadata-first replication | Replicate headers/index first; download payload on demand |
Specified in Distributed Database §9.4 and Distributed File Storage §9.4. Authorization remains source-side on every page and fetch (Data Access Control §9.5).
Multi-platform Runtimes
The Laravel reference Runtime validates the protocol on servers and PC/laptop nodes first. Mobile devices need a separate full Runtime — not Laravel on PHP:
| Priority | Runtime | Target hosts | Role |
|---|---|---|---|
| Reference (current scope) | Laravel (PHP) | NixOS servers, containers, PC, laptop | First conforming implementation; Federated Community Hub validation |
| First additional (Phase 4) | Flutter | Mobile — iOS, Android | Full device Runtime with local replica and user-level replication |
| Subsequent | Go, Rust, Python, Node, .NET | Server-side and specialized hosts | Alternative or complementary server Runtimes |
The Flutter Runtime is a full Runtime on the device — hosting applications, maintaining a local replica, and participating in background replication — not merely a mobile UI client talking to a remote Laravel server. It is not part of the current scope; the first development cycle validates the Laravel server/PC Runtime and a Federated Community Hub demo before investing in the mobile Runtime.
Each Runtime MUST maintain protocol compatibility. Applications on Laravel nodes and Flutter mobile nodes interoperate within the same information space when connected through the Faberio Protocol.
Timeline Principles
This roadmap describes sequencing and dependencies, not fixed dates. Development follows these principles:
- Protocol before implementation — specifications define the contract; the Runtime implements it.
- One server Runtime first — the Laravel reference implementation (server, PC, laptop) validates the full stack before the Flutter mobile Runtime and other platforms.
- Validate before scaling — multi-node proof confirms the architecture before building applications and additional SDKs.
- Applications drive platform maturity — real distributed apps reveal production requirements that laboratory tests miss.
- Flutter Runtime for mobile (Phase 4) — after the Laravel server reference is validated; phones and tablets get a dedicated Runtime, not Laravel on PHP.
Summary
| Step | Deliverable | Status |
|---|---|---|
| 1 | Protocol specification — open, implementation-neutral | Ongoing |
| 2 | Reference Runtime on Laravel with Laravel SDK (external HTTP API and native DB/filesystem access deferred to Phase 4) | Current scope |
| 3 | Deployment on NixOS and in containers | Current scope |
| 4 | Validation — multi-node Federated Community Hub demo, admin approval, database replication | Current scope |
| 5 | Production distributed applications — Local Civic Platform, Resilient Emergency Collaboration, other business applications, production Community Hub (beyond validation demo) | Future |
| 6 | Multi-platform Runtimes — Flutter Runtime for mobile first, then Go, Rust, Python, Node, .NET for server-side | Future |
The current scope is intended to deliver a reproducible self-hosted runtime and prove that distributed, local-first applications work as designed. Future phases expand the platform to additional Runtimes, application categories, and production hardening.