Skip to content

Serverside

The Foundation. The Jurisdiction. The Ground.

Every command processed. Every commit stored. Every page rendered.
All of it runs on infrastructure the community controls.

Why Infrastructure Sovereignty Matters

Most digital tools run on servers owned by corporations headquartered outside the EU — subject to foreign law, foreign data requests, and foreign shutdown decisions.

SmartupOS makes a different choice. Every component runs on EU-sovereign, open-source infrastructure. Not because it's easier — it isn't — but because an experiment in democratic collective ownership cannot depend on infrastructure that is itself not democratically owned.

Ground Rule #5 — Act in the Open

All actions are auditable by default. That guarantee is only meaningful if the infrastructure it runs on cannot be closed, sold, or subpoenaed into silence.

  • EU Jurisdiction

    All servers, all data, all processing under EU law. No data crosses to US-jurisdiction infrastructure at any point.

  • 100% Open Source

    Forgejo, Matrix/Synapse, MkDocs, Node.js, Python, Flask. No proprietary tools. Ever. The stack can be audited, forked, or migrated by the community at any time.

  • Self-Hosted

    No managed SaaS. No vendor lock-in. The community owns the infrastructure the same way it owns the ledger.

  • No Proprietary APIs

    No Slack. No Notion. No GitHub. No Google. Every integration uses open protocols (Matrix federation, git, REST).

The Full Stack

Every layer of SmartupOS maps to a specific piece of infrastructure. Together they form a complete, self-contained sociotechnical operating system.

flowchart TD
    subgraph FRONT["Front Office (Human Layer)"]
        M["Matrix / Synapse\nsmartup0.org\nFederated chat protocol"]
        EL["Element\nowners.smartup0.org\nWeb client"]
    end

    subgraph MID["Middleware (Coordination Layer)"]
        EB["Engelbot\nNode.js / TypeScript\n3_7_operational_team"]
        TB["Toolbox API\nFlask / Python\n3_1_leadership_team"]
    end

    subgraph BACK["Back Office (Record Layer)"]
        FG["Forgejo\nforge.timeline0.org\nCSV Ledgers + Wiki"]
        CC["Clever Cloud\nCI/CD + Hosting"]
    end

    subgraph PUB["Public Layer (Transparency)"]
        MK["MkDocs Build\n1_general_forum"]
        TL["timeline0.org\nPublic website"]
    end

    EL --> M
    M --> EB
    EB --> TB
    TB --> FG
    FG --> MK
    MK --> CC
    CC --> TL

Layer by Layer

What it is: An open, federated, end-to-end encrypted messaging protocol. Matrix is to chat what email is to messaging — a standard, not a product.

What SmartupOS uses it for: The primary interface for all owner interactions. Every !command is a Matrix message. Every Engelbot reply is a Matrix message. The workspace, the team rooms, the governance discussions — all Matrix.

Hosting: - Homeserver: smartup0.org (self-hosted Synapse) - Element client: owners.smartup0.org - Defederated: the homeserver does not federate with the public Matrix network. Access requires an invitation — the workspace is token-gated by design.

Why Defederated?

Defederation means only owners with verified accounts on smartup0.org can participate in the workspace. This is not censorship — it is jurisdictional clarity. The ledger is a legal and economic record. Public federation would allow unverified actors to interact with it.

What it is: A self-hosted, open-source git forge — the same technology that powers software version control, repurposed as a constitutional ledger.

What SmartupOS uses it for: Single source of truth. Every CSV record, every wiki page, every audit trail entry lives here. No external database. No separate CMS. Git commits are the write-ahead log.

Hosting: forge.timeline0.org

Full Forgejo documentation →

What it is: A EU-based Platform-as-a-Service (PaaS) provider — the European alternative to Heroku or AWS Elastic Beanstalk.

What SmartupOS uses it for: Two things:

  1. Continuous deployment of timeline0.org — every push to master on 1_general_forum triggers a MkDocs build and deploys the public site.
  2. Runtime hosting for Engelbot and the Toolbox API.

Why Clever Cloud and not AWS/GCP/Azure? Clever Cloud is headquartered in Nantes, France. Data sovereignty, GDPR compliance, and EU infrastructure are built into the product — not bolted on.

What it is: A static site generator built for documentation, using the Material theme.

What SmartupOS uses it for: Public transparency layer. The private ledger in Forgejo is selectively published to timeline0.org via generate-public-pages.py — stripping private data, rendering objectives, task progress, and owner portfolios as readable markdown.

The site you are reading now is the output of this pipeline. It is rebuilt automatically on every push to 1_general_forum/master.

The Toolbox — Where Rules Are Enforced

The Toolbox is the constitutional enforcement layer between Engelbot and Forgejo. It is not a user-facing tool — owners never interact with it directly. But it is where every permission check, every ledger write, and every audit trail entry is produced.

flowchart LR
    EB["Engelbot\n!command"] -->|"HTTP POST\n/api/endpoint"| API["Toolbox API\nFlask app.py"]
    API -->|"python3 script.py --json"| SC["Toolbox Scripts\nPython"]
    SC -->|"1. Permission check\n2. Markdown write\n3. CSV write\n4. Audit log"| FG["Forgejo"]

The Toolbox has three script tiers, each with distinct permissions:

Folder Who Can Run Purpose
queries/ Everyone Read-only lookups — balances, task lists, entity resolution
workers/ All role holders Work actions — claim task, start/stop work, apply for role
teamcaptain/ Captains + Founder only Write actions — create task, assess work, award SK

The Write Order is Law

Every Toolbox script follows the same sequence, without exception:

  1. Markdown first — write the wiki file to Forgejo
  2. CSV second — update the index with the wiki_path pointer
  3. master-events.csv last — append the audit trail entry

Inverting this order risks orphaned content or unlogged mutations. The sequence is enforced structurally — not by convention.

Technical: How a Script Reaches Forgejo

Every Toolbox script is a standalone Python process. The Flask API receives the HTTP POST from Engelbot, validates required fields, constructs the argument list, and calls:

result = execute_script(script_path, args)
# Internally: python3 script.py --actor alias --field value --json
# Timeout: 120s
# Returns: parsed JSON dict

The script itself handles all Forgejo interaction via common/forgejo_api.py — SHA-based optimistic locking, retry logic, and the append-only master-events handler are all centralised there. No script writes to Forgejo directly.

Technical: Error Handling & Partial Write Failures

SmartupOS has no rollback mechanism. Write order is the safety net:

Failure point Impact Recovery
Wiki write fails Nothing written — abort safely Retry the command
Wiki succeeds, CSV fails Orphan wiki exists, no index entry Retry — duplicate check in modifier catches it
CSV succeeds, audit fails Mutation happened, unlogged Visible in git history — log manually if detected

409 conflicts (concurrent writes) are handled automatically with exponential backoff and are never surfaced to the owner.

Deployment Pipeline

flowchart LR
    DEV["Developer\nLocal commit"] -->|"git push\nmaster"| FG["Forgejo\n1_general_forum"]
    FG -->|"Webhook trigger"| CC["Clever Cloud\nCI/CD"]
    CC -->|"mkdocs build"| SITE["timeline0.org\nLive in ~60s"]

    FG2["Forgejo\n2_workplace\n(private ledger)"] -->|"generate-public-pages.py\n(scheduled)"| FG

The pipeline from commit to live site takes approximately 60 seconds:

  1. git push to 1_general_forum/master
  2. Forgejo webhook fires to Clever Cloud
  3. Clever Cloud pulls the repo and runs mkdocs build
  4. Static files deployed to timeline0.org

Build Safety — Missing Files

If any file listed in mkdocs.yml nav does not exist, the build will fail silently. Always create placeholder files before adding new nav entries. When in doubt: echo "# Coming Soon" > docs/path/to/file.md and commit first.

Security Model

SmartupOS is transparent by default — but not naive about it.

Layer Access Control
Matrix workspace Invitation-only. Defederated homeserver.
Forgejo private repos Token-gated. FORGEJO_TOKEN per service account.
Forgejo public repos Read-only public access.
Toolbox API Internal network only. Not exposed to public internet.
timeline0.org Fully public. Contains no private data by pipeline design.
identity-mapping.csv Never read by any public-facing script. Private forever.

Privacy by Architecture

The separation between book-of-owners.csv (public aliases) and identity-mapping.csv (real names + emails) is not a policy — it is a structural guarantee. The public site generator does not have a code path to identity-mapping.csv. It cannot leak what it cannot reach.

The Principle Behind the Stack

Every tool in this stack was chosen against the same criteria:

  • Is it open source?
  • Is it EU-sovereign or self-hostable in the EU?
  • Does it use open protocols (not proprietary APIs)?
  • Can the community migrate away from it without losing data?

If the answer to any of these is no, the tool is not in the stack.

This is not ideological purity. It is constitutional consistency — the same principle that governs ownership (one vote, no matter how much money you paid) applies to infrastructure (community-owned, no matter how convenient the corporate alternative).

The Litmus Test

If the founding team disappeared tomorrow, could the community continue operating SmartupOS within 24 hours? The answer is yes — because every component is open, documented, and self-hostable.

Part of the SmartupOS stack · Engelbot ← Serverside