Draw your systems the way you think about them. Fork. Comment. Review. Ship.
ArchFlow is an open-source alternative to IcePanel — a collaborative, real-time workspace for modeling software architecture using the C4 model.
Unlike Figma-for-architecture tools that end at "pretty boxes", ArchFlow treats your architecture as a first-class data model: every object has a type (system, container, component, actor…), a lifecycle status, relationships, drafts, version history, and team-level access control. Drill from a system landscape all the way down to components — the model stays consistent at every zoom level.
L1 System Landscape ──▶ System Context
│
L2 Container
│
L3 Component
- React Flow-powered editor with snap-to-group, smart containment, and edge routing.
- Live cursors, presence roster, and selection sync — see your teammates edit in real time.
- Optimistic drag & resize — zero snap-back, WebSocket cache patching under the hood.
- Comments on the canvas — question pins, inaccuracy flags, ideas, notes.
- Objects (
system/external_system/actor/app/store/component/group) with status, technology, tags, owner team. - Per-diagram positions — the same object can live on L1, L2, L3 with different coordinates on each canvas.
- C4-aware quick-create: place the right types for the level you're on, but also allow cross-level references.
- ~170 built-in technologies (Python, PostgreSQL, Kafka, Figma, gRPC, Kubernetes…) with Iconify-backed logos and brand colors.
- Picker in the object sidebar (multi-select) and edge sidebar (single-select, filtered to protocols) — results group by category with fuzzy search over name / slug / aliases.
- Canvas renders the primary technology as a corner badge on every node and resolves protocol icons onto edge labels.
- Create workspace-level custom technologies — pick any Iconify icon for the logo, set your own name / slug / color / aliases.
- Dedicated
/technologiesmanagement page lists built-in + custom entries with scope + category filters.
- Fork any diagram into a draft that lives in isolation from live data.
- Edit the fork freely — compare diffs, resolve conflicts with the live model, then merge.
- Full version snapshots with revert-to-version.
- Multi-workspace with per-workspace roles (
owner/admin/editor/viewer). - Per-diagram ACL via teams — grant a team
read/edit/manageaccess on individual diagrams. - Pending-approval invite flow (invitee accepts; owner/admin approves).
- Notification inbox for mentions, invites, and activity.
- Packs — group diagrams into logical collections (like folders, but reorderable).
- Pinned / Recent on the Overview dashboard.
- Full-text search across all objects and diagrams (⌘K / Ctrl+K).
- REST API (OpenAPI / Swagger UI at
/docs) + orval-generated TypeScript client. - API keys with prefix-based detection (
ak_…), first-class citizens alongside JWT. - Webhooks for
object.*,connection.*,diagram.*, and more. - Optional AI insights (Claude) — summarize an object's role, spot missing connections.
- JSON export / import for migration or CI snapshotting.
- One workspace-level WebSocket firehose + per-diagram channels.
- Keeps React Query cache in sync across tabs / users / browsers — no manual refresh.
| Backend | Frontend | Infra |
|
|
|
One-time bootstrap (installs deps, spins up Postgres/Redis, runs migrations):
make setupThen any time you want to code:
make devThat launches, in parallel:
| Service | URL |
|---|---|
| Backend (FastAPI) | http://localhost:8000 |
| API docs | http://localhost:8000/docs |
| Frontend (Vite) | http://localhost:5173 |
| Postgres | localhost:5432 |
| Redis | localhost:6379 |
One Ctrl+C tears both app processes down. Infra keeps running — make down stops the containers.
| Command | What it does |
|---|---|
make dev |
Deps → infra → migrations → backend + frontend in parallel |
make dev-deps |
uv sync backend, npm install frontend |
make dev-infra |
Start Postgres + Redis via docker compose |
make dev-backend |
Backend only (uvicorn --reload) |
make dev-frontend |
Frontend only (vite) |
| Command | What it does |
|---|---|
make db-upgrade |
Apply all pending migrations |
make db-migrate msg="..." |
Generate a new Alembic migration from model diff |
make db-downgrade |
Roll back the last migration |
| Command | What it does |
|---|---|
make test |
Backend pytest + frontend tests |
make test-backend |
Backend only |
make test-frontend |
Frontend only |
make lint |
ruff check + ruff format --check + npm run lint |
make api-codegen |
Regenerate the typed frontend client from OpenAPI (run after schema changes) |
| Command | What it does |
|---|---|
make build |
Build prod docker images |
make up |
Start the prod stack |
make down |
Stop the prod stack |
ArchFlow/
├── backend/ FastAPI app
│ ├── app/
│ │ ├── api/v1/ REST endpoints (one router per resource)
│ │ ├── models/ SQLAlchemy 2.0 models
│ │ ├── schemas/ Pydantic request/response schemas
│ │ ├── services/ Business logic layer
│ │ ├── realtime/ WebSocket manager + Redis fanout
│ │ └── core/ Config, DB, security
│ ├── alembic/ Migrations
│ └── tests/ Pytest suite
├── frontend/ Vite + React SPA
│ └── src/
│ ├── pages/ Top-level routes
│ ├── components/ Canvas, sidebar, toolbar, modals…
│ ├── hooks/ React Query hooks + WebSocket client
│ ├── stores/ Zustand stores (auth, canvas, workspace)
│ ├── lib/ Shared axios client (auth + workspace + 401 → /login)
│ └── types/ Shared TypeScript models
├── docker/ docker-compose.dev.yml + docker-compose.yml
├── charts/archflow/ Helm chart
└── docs/architecture/ ADRs + design notes
Workspace → your org's top-level container. Everything (diagrams, objects, teams, packs) belongs to exactly one workspace.
Diagram → a single C4-level canvas. Has a type (system_landscape · system_context · container · component · custom) and an optional scope_object_id linking it to its parent in the drill-down hierarchy.
ModelObject → a piece of your architecture (system, container, component, actor…). Lives in a workspace; can appear on many diagrams via a DiagramObject junction that stores per-diagram coordinates and size.
Connection → a directed or bidirectional edge between two ModelObjects. Rendered on any diagram that contains both endpoints.
Draft → a forked universe of a diagram + its objects + its connections. Changes stay isolated until you merge back into live.
Pack → a named collection of diagrams within a workspace, for organizing large architectures.
Config lives in .env at the repo root (copied from .env.example on first make setup). Knobs you'll touch most:
DATABASE_URL=postgresql+asyncpg://archflow:archflow@localhost:5432/archflow
JWT_SECRET=change-me-in-production
BACKEND_CORS_ORIGINS=http://localhost:5173
# Optional — enables AI insights on ModelObjects
ANTHROPIC_API_KEY=sk-ant-...Port 8000 or 5173 already in use
lsof -ti tcp:8000 | xargs kill # or tcp:5173Migrations out of sync after pulling
make db-upgradeStale frontend types after changing API
make api-codegenNuke Postgres (wipes the volume — you'll lose all data)
docker compose -f docker/docker-compose.dev.yml down -v
make dev-infra && make db-upgrade- C4 canvas with drill-down (L1 → L2 → L3)
- Real-time collaboration (presence, cursors, selection, optimistic CRUD)
- Drafts + diffs + conflict resolution
- Version history with revert
- Team-level per-diagram ACL
- API keys + webhooks
- Packs, pinned, search
- Import from Structurizr DSL
- Export to Mermaid / PlantUML
- SSO (OIDC)
- Deployment diagrams (C4 L4)
See docs/architecture/ for ADRs and ongoing design.
PRs welcome — bug fixes, features, docs, everything. Full workflow in CONTRIBUTING.md.
TL;DR:
-
mainis protected. Branch off:git switch -c feat/my-thing. -
Small, focused commits. Conventional prefixes:
feat/,fix/,refactor/,docs/,chore/,test/. -
Before pushing:
make lint make test -
Open a PR targeting
main. CI runsbuild-backendandbuild-frontend— both must be green to merge. -
Squash merge keeps
mainlinear.
Bugs → GitHub issues. Security issues → private advisories.
AGPL-3.0 — free to use, modify, and self-host. If you run a modified version as a network service, you must offer the source under the same license.