Forgejo

Why Forgejo?

Most organisations store their records in proprietary databases owned by corporations outside their jurisdiction. Smartup Zero does the opposite.

Ground Rule #1 — Prove Your Work

If not logged, it didn't happen.

Forgejo is a self-hosted, EU-sovereign, open-source git platform — the same technology that powers software version control, repurposed here as a constitutional ledger. Every record is a file. Every change is a commit. Every commit is signed, timestamped, and permanently auditable by anyone with access.

No vendor lock-in. No proprietary APIs. No data leaving EU jurisdiction. Ever.

• Open Source

  ---

  Forgejo is fully open-source. The ledger infrastructure is owned by the community, not a corporation.

• EU Sovereign

  ---

  Hosted at forge.timeline0.org. All data resides on EU infrastructure under EU law.

• Append-Only

  ---

  Records are never deleted or overwritten. Every mutation is a new commit in an immutable git history.

• Auditable by Default

  ---

  Ground Rule #5: Act in the Open. Every change is traceable to an actor, a timestamp, and a script.

---

The Repository Structure

SmartupOS organises all of its work across repositories that mirror its governance layers. Each repo ID maps directly to the OSOT layer system.

graph TD
    ORG["🏛️ Smartup_Zero (Forgejo Org)"]

    ORG --> R1["1_general_forum\n📂 Public\nGovernance & MkDocs source"]
    ORG --> R2["2_workplace\n📂 Private\nThe Ledger — single source of truth"]
    ORG --> R3["3_X_team_repos\n📂 Private\n7 team repos (issues + scripts)"]
    ORG --> R37["3_7_operational_team\n📂 Private\nEngelbot source code"]
    ORG --> R31["3_1_leadership_team\n📂 Private\nToolbox scripts + API"]

Repo	Visibility	Purpose
1_general_forum	🌍 Public	Democracy layer. MkDocs source that auto-generates timeline0.org
2_workplace	🔒 Private	The Ledger. All CSV indexes + wiki markdown content
3_1_leadership_team	🔒 Private	Toolbox scripts, Flask API, constitutional enforcement
3_7_operational_team	🔒 Private	Engelbot (Node.js/TypeScript)
3_X_team_repos	🔒 Private	Team issues, objectives, task tracking (7 teams)

One Branch — Always Master

All repositories operate on a single master branch. There are no feature branches, no pull request debates. Changes are committed directly by authenticated scripts acting on behalf of verified owners.

---

The Ledger Architecture

Forgejo doesn't just store code — it stores every economic and governance event in Smartup Zero. The architecture separates indexing from content into two complementary layers.

CSV Layer (The Index) Wiki Layer (The Content)

CSV files are the machine-readable index. They store IDs, statuses, budgets, role assignments, and short summaries — structured data that scripts can query and update atomically.

Every CSV row includes a wiki_path pointer to the full content.

Location: 2_workplace/currency-ledger/

File	What It Tracks
ownership/book-of-owners.csv	Every owner: alias, roles, SK balance, status
ledger/objectives/registry.csv	All objectives (global + team)
ledger/task-management/task-budgets.csv	All tasks: budget, status, assignment
ledger/task-management/work_clock.csv	Clock-in / clock-out events
ledger/task-management/session_logs.csv	Completed work sessions
ledger/smartup-credits/transactions.csv	Validated SC awards
ledger/pending-sc/transactions.csv	SC awaiting captain validation
ledger/social-karma/transactions.csv	SK awards and peer nominations
ledger/treasury/balance.csv	EUR + SC outstanding snapshots
master-events.csv	Complete audit trail — every action, every actor

Markdown files in wiki/ hold the human-readable full record — the Why, How, and What behind every task, objective, and role.

Scripts write markdown first, then update the CSV index. This write order is constitutional.

Entity	Wiki Path
Task	wiki/6_tasks/{task_id}.md
Objective	wiki/5_objectives/{obj_id}/{obj_id}.md
Role description	wiki/4_roles/{role_id}/briefing/role_description.md
Owner portfolio	wiki/2_workplace/2_book_of_owners/portfolios/{alias}/

Write Order is Constitutional

Markdown first → CSV second → master-events.csv last.
This sequence is enforced in every Toolbox script. Inverting it risks an index pointing to content that doesn't exist yet.

---

How the Ledger Becomes the Public Site

The public-facing website you are reading now is generated directly from Forgejo.

flowchart LR
    F["2_workplace\n(Private Ledger)"]
    G["1_general_forum\n(Public Repo)"]
    M["MkDocs Build\n(Clever Cloud)"]
    W["timeline0.org\n(Public Website)"]

    F -->|"generate-public-pages.py\n(strips private data)"| G
    G -->|"git push → CI trigger"| M
    M -->|"mkdocs build"| W

generate-public-pages.py runs on a schedule and extracts only public-safe data from the private ledger — owner aliases (never real names), objective progress, task completion rates — and writes them as markdown into 1_general_forum. MkDocs then builds this into the site you're reading.

Transparency by Architecture

The pipeline enforces transparency structurally. Private data (identity mapping, real names, emails) cannot reach the public site — they live in a separate CSV that the generator never reads.

---

Conflict Safety & Immutability

Git's content-addressable storage makes every record tamper-evident. But a live system with multiple concurrent writers needs an additional safety layer.

SmartupOS uses SHA-based optimistic locking: before writing any CSV, the script reads the file's current SHA from Forgejo's API. If another script committed a change between the read and the write, Forgejo returns a 409 Conflict. The Toolbox retries automatically with exponential backoff.

This means: - No record is ever silently overwritten - Concurrent writes are safe by default - Every retry is a fresh read — data is always current

Technical: How SHA Locking Works in Practice

Every write operation in the Toolbox follows this flow:

# 1. Read current state + SHA (the lock token)
rows, sha = api.fetch_csv(repo, path, branch)

# 2. Modify in memory
def modifier(rows):
    rows.append(new_row)
    return rows

# 3. Write with retry — if SHA has changed, re-read and retry
api.write_with_retry(repo, path, modifier, commit_msg, actor, branch)
# Max 3 retries with exponential backoff. 409s are transparent to users.

The modifier function is designed to be idempotent — safe to call multiple times with the same input. Sequential IDs are derived inside the modifier after the fresh re-read, making them concurrency-safe even under contention.

Technical: The master-events.csv Audit Trail

Every mutation in SmartupOS — task creation, SC award, role assignment, clock-in — appends a row to master-events.csv. This file is the forensic record of the entire experiment.

timestamp | smartup_id | actor | script | event_type | ref_file | description

It is append-only by design. Scripts never use write_with_retry() on this file — they always use append_csv_row(), which routes to a special handler that preserves the file's immutable append semantics and legacy format.

---

Forgejo in the SmartupOS Stack

flowchart TD
    H["Human\n(Matrix / Element)"]
    E["Engelbot\n(Node.js / TypeScript)"]
    T["Toolbox API\n(Flask / Python)"]
    S["Toolbox Scripts\n(Python — constitutional enforcement)"]
    F[("Forgejo\nAll CSV ledgers\n+ Wiki markdown")]
    P["timeline0.org\n(MkDocs — public transparency)"]

    H -->|"!command"| E
    E -->|"HTTP POST"| T
    T -->|"python3 script.py"| S
    S -->|"Forgejo REST API\n(SHA-based locking)"| F
    F -->|"auto-generates"| P

Forgejo sits at the bottom of the stack — the gravitational centre. Every other component (Engelbot, the Toolbox, the public website) reads from or writes to it. It is never bypassed.

Next: The Back-Office in Detail

Forgejo is where records live. Engelbot is how owners interact with those records without ever touching a CSV directly. Element is where those interactions happen.

---

Hosted at forge.timeline0.org · Organisation: Smartup_Zero · All repos: EU-sovereign, open-source ```