GitHub - MapleSpire/maplespire: Collaborative C4 architecture modelling and diagramming — offline-first, real-time, self-hostable (AGPL-3.0)

Architecture clarity that moves teams forward.
Collaborative C4 modelling and diagramming — one trusted model instead of scattered drawings.

Website · Video tour · Get started · Develop locally · Sponsors · Governance · License

Watch the 2½-minute tour

From a system description to a living C4 model: AI, connected views, offline editing, decision records, drafts, live collaboration, MCP and 3D.
Audio and captions in 11 languages: pick yours in the player's settings. More on the MapleSpire YouTube channel.

Architecture diagrams rot. They live in slides and wikis, each one a slightly different copy of the truth, and nobody knows which one is current.

MapleSpire keeps one model of your systems — people, software systems, containers, components and the relationships between them — and every diagram is a view of that model. Rename a service once and every diagram, table and export follows. Move between levels of detail with a click, see who depends on what, and keep the decisions that shaped it right next to it.

What you can do with it

Model, not just draw

• C4 modelling: System Context → Container → Component, with drill-down between levels
• A fast canvas editor with automatic layout (ELK) and readable edge routing
• Model Objects, Connections and Dependencies pages: the whole model as searchable tables
• Read-only Model Viewer in 2D or an interactive 3D board

Work together

• Real-time collaboration on the same diagram, with presence and comments
• Offline-first: keep working when the server is down; changes sync back when it returns (Automerge CRDT)
• Drafts: fork the model, propose changes, review a three-way diff, then merge
• Architecture Decision Records linked to the elements they affect

Govern and share

• Organisations, teams and role-based access control; single sign-on with Google and Microsoft Entra ID
• Tags, technology catalogue with icons, reference-integrity checks
• Interactive read-only share links (public, organisation or email-domain audience), pinned to a version if you want
• Import from Structurizr DSL; export to JSON, CSV, PDF, Markdown, HTML, Structurizr, Mermaid, SVG and PNG

Extend it

• AI assistant with your own provider key (OpenAI, Anthropic, Google, OpenAI-compatible, LM Studio) and an MCP server so external agents can read and edit the model
• Theme plugins through a sandboxed Theme SDK
• English and French interface

Run it yourself

• Three containers and two commands to try the whole application locally
• Production add-ons — monitoring, alerting, backup drills, multi-cell sync and cloud deployment kits — documented for sponsors

Screenshots

AI assistant — describe your system and it builds a real C4 model, with your own provider key.	One model — every box is a real object: rename it once and every diagram, table and export follows.
Flows — step-by-step message sequences, played right on the diagram.	Drafts — fork the model, review exactly what changed, resolve conflicts, merge.
Decision records — let the AI draft the ADR from your model; the "why" stays linked to the architecture.	3D board — present any diagram in 3D, with themes, skins and decorations.

Quick start

git clone https://github.com/MapleSpire/maplespire.git
cd maplespire
node scripts/init-env.mjs                                # creates .env and generates secrets
docker compose -f compose.quickstart.yml up -d --build   # PostgreSQL + API + web

Open http://localhost:8088 and create your account. The step-by-step guide — first administrator, confirming your email, settings and troubleshooting — is docs/getting-started.md.

To work on the code with hot reload (no Docker needed):

npm install
cd server && npm install && cd ..
npm run dev:local        # embedded Postgres + API + Vite on http://localhost:5173

See docs/running-locally.md.

How it works

 Browser (React + canvas, IndexedDB)
     │  offline edits kept locally, synced when the server is reachable
     ▼
   nginx ── REST + Automerge WebSocket ──►  API (Node)  ──►  PostgreSQL
                                                              Automerge documents (source of truth)
                                                              + rebuildable read model

• Automerge documents are authoritative; the PostgreSQL read model is a cache that can always be rebuilt from them.
• The quickstart runs a single API process. At scale, workspaces are spread over several sync cells: each workspace is owned by one cell at a time through a Redis lease, and an owner-aware router sends every WebSocket straight to that cell (see Going further).

Architecture and every server setting: docs/architecture-and-configuration.md.

Going further: production add-ons

Everything in this repository is free and open source, and the quickstart runs the complete application. When you take MapleSpire to production, you can add around it the same pieces that run the public demo:

Production deployment kits

The production-shaped Compose file (compose.maplespire.yml) and the monitoring configuration (infra/monitoring/) are in this repository. The guides to configure, run and operate them, plus the managed-cloud and Kubernetes kits, are in the private MapleSpire sponsor kit, available by sponsoring the project on GitHub:

• the production stack guide for compose.maplespire.yml;
• operations runbooks: sync cells and routing, backups and restore drills, alerting (email pages and external heartbeat), security checklist;
• infrastructure as code for AWS (CDK: ECS Fargate, Aurora PostgreSQL, ElastiCache, CloudFront);
• Azure and portable Kubernetes modules (Terraform: AKS, EKS, GKE, OpenShift);
• the matching deployment pipeline and production guides — managed Redis, capacity and scaling, WebSocket fan-out, Redis observability and rotation.

Sponsorship funds the development of MapleSpire.

Sponsors

MapleSpire is made possible by its GitHub sponsors. Thank you to everyone who supports the project — every sponsor is listed on the sponsors page.

Business sponsors

Your company logo here — become a Business sponsor.

Governance

MapleSpire is an open-source project stewarded by the MapleSpire organisation on GitHub.

• Maintainers. The project is led by its founding maintainer, who has the final say on the roadmap, releases and what gets merged. Regular contributors may be invited to become maintainers.
• How decisions are made. Proposals start as GitHub issues or discussions. Significant changes (architecture, data model, sync protocol, licensing) are discussed in the open before code is written, and the reasoning is kept with the decision.
• Contributions. Pull requests are welcome — see CONTRIBUTING.md. Every change goes through review and the automated checks before it is merged. Commits must be signed off under the Developer Certificate of Origin (git commit -s) so that we are sure to have the right to distribute the code submitted; a GitHub check (DCO) verifies it on every pull request.
• Security. Please do not open public issues for vulnerabilities — see SECURITY.md.
• Website. The marketing site lives in its own repository, MapleSpire/maplespire-website, and is published at maplespire.ca.

License

MapleSpire is released under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).

You may use, study, modify and redistribute it — including commercially and as a hosted service — provided that you publish your modifications under the same license and offer the corresponding source code to the users who interact with a modified version over a network.