Mycelium

Welcome to Mycelium.

Mycelium is a Postgres-centric platform for building multi-tenant business applications. It keeps durable business truth in SQL, lets FastAPI orchestrate requests and rendering, and gives each app a clear filesystem home for routes, templates, metadata, transport aliases, static assets, and database logic.

The project is currently shaped around a simple idea: every layer should do the job it is best suited for. Postgres owns business state and set-based logic, Python owns request flow, templates own presentation, and Redis/MQTT are used as explicit infrastructure for fast keyed state or retained transport snapshots.

What Is Here

• A FastAPI runtime with session auth, route dispatch, tenant selection, and Jinja2 rendering.
• A control-plane app, metadminer, for users, tenants, app access, roles, and runtime metadata.
• A sample business app, cashier, with tenant-local business tables and SQL-backed screens and mutations.
• App scaffolding for creating new app modules under apps_logic/<app>.
• Postgres migrations split by control plane, app-public metadata, and tenant business schemas.
• Redis and MQTT alias manifests that let routes opt into explicit app-owned reads and writes without hard-coding keys or topics in templates.
• A small design system under peripheral_design_language.

Architecture At A Glance

Mycelium has three main data boundaries:

• The control-plane database stores apps, tenants, users, app access, control roles, and audit records.
• Each app database public schema stores app-control and runtime metadata such as routes, endpoints, roles, settings, and SQL query metadata.
• Each tenant schema stores tenant-local business data for that app.

Request handling follows the same boundary. A user selects an app and tenant, the runtime resolves route and endpoint metadata, app routes run inside a transaction-local tenant schema scope, Postgres functions return business data, and templates render the resulting payload.

Quick Start

Requirements:

• Docker
• Docker Compose
• make

Start the local demo stack:

make demo_init ENV=dev

Then open:

• App: http://localhost:7150
• Adminer: http://localhost:7153

Seeded demo users:

• Superadmin: superadmin / superadmin
• Tenant user: tenant / tenant

Useful follow-up commands:

make logs ENV=dev
make test ENV=dev
make down ENV=dev

Project Layout

src/                         FastAPI runtime, dispatch, auth, cache, CLI
apps_logic/metadminer/       Control-plane app
apps_logic/cashier/          Example tenant business app
apps_logic/<app>/routes/     Python handlers, HTML templates, Redis/MQTT aliases
apps_logic/<app>/sql_logic/  SQL functions and metadata
apps_logic/<app>/db_migrations/
scaffolding/app/             Template for new app modules
peripheral_design_language/  Shared UI components and styling
dev_docs/                    Architecture, operations, and review notes
tests/                       Unit, integration, and property tests

Adding An App

Create a new app scaffold:

make scaffold-app APP_SLUG=<app_slug> APP_NAME="Display Name"

The generated app gives you the expected structure for routes, templates, metadata, SQL logic, migrations, and static assets. From there, the usual flow is to add route metadata, write SQL-backed business behavior, create templates, sync runtime metadata, and grant access through metadminer.

Reading Guide

For a first technical pass, start here:

• dev_docs/reviewer_brief.md
• dev_docs/architecture.md
• dev_docs/proterative.md
• dev_docs/routing_and_templates.md
• dev_docs/auth_and_access.md
• dev_docs/devops.md

Historical changelogs and smoke reports are useful timeline records, but the reviewer brief and architecture docs are the current source of truth.

Status

Mycelium is under active development. The current runtime supports the demo control plane and cashier app, local Docker-based development, route and endpoint synchronization, SQL metadata synchronization, tenant-scoped request paths, Redis aliases, MQTT aliases, and a Docker-backed regression test flow.

Known productization limits include production-disabled metadminer writes and local-process cache invalidation until a distributed invalidation backend is added.

License

Mycelium is licensed under the Apache License, Version 2.0. See LICENSE for the full license terms.

The repository also includes a NOTICE file. Redistributed copies or derivative works must preserve that attribution notice when required by Apache-2.0.