MakerFlow PM is an open-source project management and operations platform built for makerspaces, labs, and service teams that need to track work, equipment, consumables, partnerships, and people enablement in one self-hostable, low-cost system.
- Primary site: https://makerflow.org
- Repository: https://github.com/ianroy/makerflowPM
- License: Creative Commons Attribution-ShareAlike 4.0 International (
CC BY-SA 4.0)
- MakerFlow PM (Python) — the current, shipping product: a server-rendered WSGI app (web only). Everything below the "Pivot" section documents it.
- MakerFlow PM (Dart rebuild) — a greenfield Flutter + Serverpod rebuild for web, mobile, and desktop, with offline/push/camera/biometric. Actively developed under
makerflow_dart/: a monday.com-style interface (Vibe-derived design system, boards sidebar, the grouped inline-editing Main Table) with a live customization platform — resizable/reorderable/hideable columns, nine custom-field types with server-validated values, and saved/shared views. CI-gated (server + app suites green over live PostgreSQL), and the entire demo deploys to DigitalOcean App Platform from one spec (API + web UI on one domain). Tracked inFLUTTER_REBUILD_PLAN.md§14.1 andmakerflow_dart/NEXTSTEPS.md. It is new deployments only — it does not replace the Python app for existing installs. See Pivot to Flutter / Dart.
- What it is
- Who built it
- Tech stack
- Architecture at a glance
- How it works
- Data model
- Authorization model
- Quick start (local)
- Deploying on GitHub
- Deploying on DigitalOcean
- Environment variables
- Testing and verification
- Repository map
- Roadmap
- Federal accessibility compliance (ADA Title II + Section 504)
- Pivot to Flutter / Dart
- Deploying the Dart rebuild on GitHub
- Documentation index
- Contributing
- License
MakerFlow PM is a single-binary-feeling, stdlib-first Python web application that bundles into one repo all of the routines a small ops/engineering team actually runs day to day:
- Projects, tasks, and kanban / list / calendar workflows with custom views, saved filters, and per-org custom fields.
- Meeting agendas and minutes that can convert items directly into tasks or projects.
- Equipment, consumables, and partnerships tracking with soft-delete and audit history.
- Onboarding templates and assignments so role-based checklists travel with new hires.
- Imports and exports as a first-class portability contract — CSV in, CSV out, plus PDF/DOCX note import.
- Google Calendar bidirectional sync linking tasks to calendar events.
- Reports and insight snapshots plus an
audit_logtable that records every mutation for accountability.
It is designed to run cheaply: on a $6 DigitalOcean Droplet, on App Platform with managed PostgreSQL, or on a single developer machine with SQLite.
MakerFlow PM is built by Ian Roy, leveraging the OpenAI Codex (GPT-5.3 family) workflow for implementation, iterative debugging, test simulation, and documentation refinement. The product is shipped under CC BY-SA 4.0 so universities, labs, and community workshops can self-host, fork, and adapt it without per-seat fees.
| Layer | Choice | Notes |
|---|---|---|
| Runtime | Python 3.11.9 | declared in runtime.txt |
| WSGI server | Gunicorn ≥ 21.0 (Linux) · Waitress ≥ 2.1 (Windows) | from requirements.txt |
| Framework shell | Flask ≥ 3.0 + Werkzeug ≥ 3.0 | thin WSGI bridge in app/flask_app.py; core logic remains stdlib |
| Default DB | SQLite (stdlib, WAL mode) | data/makerspace_ops.db |
| Production DB | PostgreSQL via psycopg ≥ 3.1.18 (binary) | enabled by setting MAKERSPACE_DATABASE_URL |
| Frontend | server-rendered HTML + vanilla JS + hand-rolled CSS | no build step, no framework |
| Edge (Droplet) | nginx + certbot + systemd on Ubuntu 24.04 LTS | provisioned by scripts/deploy_production.sh |
| Managed runtime | DigitalOcean App Platform + DO Managed PostgreSQL | spec in .do/app.yaml, deploy-on-push |
| Source / CI | Git + GitHub · deploy_on_push today; GitHub Actions tracked in roadmap |
see FEATUREROADMAP_workplan.md |
| AI-assisted build | OpenAI Codex (GPT-5.3 family workflow) | implementation, debugging, tests, documentation refinement |
| License | CC BY-SA 4.0 | see LICENSE and the License section below |
The runtime is a server-rendered WSGI application:
- Backend: Python 3.11.9, stdlib-first, with a thin Flask/Werkzeug compatibility shell (
app/flask_app.py) on top of the monolithic core (app/server.py). - Frontend: server-rendered HTML + progressive vanilla JavaScript (
app/static/app.js) and hand-rolled CSS (app/static/style.css). No build step. No framework lock-in. - Data layer: SQLite by default; PostgreSQL when
MAKERSPACE_DATABASE_URLis set. The SQL layer adapts placeholders and types transparently. - WSGI server: Gunicorn in production; the stdlib server is used for local dev.
- Edge: nginx + certbot on Droplet deploys; DO load balancer + managed health checks on App Platform.
Every request follows the same lifecycle: WSGI entry → schema bootstrap check → session/org resolution → auth and CSRF gates → RBAC check → route dispatch → org-scoped SQL → audit + side effects → HTML or JSON response with security headers. The contract is enforced consistently in app/server.py so feature work can focus on rendering and queries rather than reinventing security primitives.
End-to-end, a unit of work flows across four product surfaces:
39 tables across six domains:
- Tenancy & identity —
organizations,users,memberships,sessions,password_resets - Project management —
projects,tasks,custom_views,field_configs,item_comments,item_watchers,report_templates - Operations & meetings —
meeting_agendas,meeting_items,meeting_item_updates,meeting_item_files,intake_requests,equipment_assets,consumables,partnerships - People enablement —
spaces,teams,team_members,onboarding_templates,onboarding_assignments,user_preferences,role_nav_preferences - Calendar & sync —
calendar_events,calendar_sync_settings,calendar_sync_links,meeting_note_sources - Governance & analytics —
audit_log,insight_snapshots,email_messages
Operational entities are soft-deleted via deleted_at + deleted_by_user_id before any permanent purge. See docs/DATA_MODEL.md.
Roles, least to most privileged: viewer → student → staff → manager → workspace_admin → owner. Workspace admins are pinned to a single organization to limit blast radius; the is_superuser flag on users is the only path to cross-workspace administration. See docs/SECURITY.md and docs/DECISIONS.md.
git clone https://github.com/ianroy/makerflowPM.git
cd makerflowPM
cp .env.example .env
python3 app/server.pygit clone https://github.com/ianroy/makerflowPM.git
cd makerflowPM
cp .env.example .env
pip install -r requirements.txt
./run_flask.shOpen http://127.0.0.1:8080/login.
Default bootstrap account (rotate immediately in any shared environment):
admin@makerflow.local/ChangeMeMeow!2026
Seed sample data while iterating:
python3 scripts/load_sample_data.pyMakerFlow PM uses GitHub as the single source of truth. The repo supports two GitHub-native deployment paths:
The .do/app.yaml spec wires App Platform to redeploy on every push to main:
github:
repo: ianroy/makerflowPM
branch: main
deploy_on_push: trueFork the repo, update .do/app.yaml with your fork name, then create the app:
doctl apps create --spec .do/app.yamlEvery subsequent git push origin main to your fork triggers a build (pip install -r requirements.txt) and a run (scripts/bootstrap_db.py && gunicorn wsgi:application). Health checks hit /readyz every 10 seconds.
The MakerFlow Website/ directory ships an HTML landing page plus a wiki of mirrored markdown docs. To publish it via GitHub Pages:
- In your fork, go to Settings → Pages.
- Source: Deploy from a branch.
- Branch:
main, folder:/MakerFlow Website. - Click Save. GitHub serves the site within a minute or two at
https://<your-username>.github.io/makerflowPM/.
Keep the wiki in sync with docs/*.md by running:
python3 scripts/sync_website_content.pyThe repo-root .github/workflows/ directory is being established; the Dart CI workflow is being moved there from makerflow_dart/.github/workflows/ (a nested location GitHub never read). For the Python app, a reasonable starter pipeline runs the verification scripts on PRs to main. The roadmap (see FEATUREROADMAP_workplan.md) tracks this as an explicit P1 task — ci-smoke-and-security — with a complete spec.
Three options:
Already covered in Quick start.
One-shot bootstrap of an Ubuntu 24.04 Droplet:
./scripts/deploy_production.sh \
--ssh ubuntu@YOUR_SERVER_IP \
--domain makerflow.org \
--admin-email admin@yourdomain.edu \
--admin-password 'REPLACE_WITH_STRONG_PASSWORD'Optional flags: --letsencrypt-email, --no-certbot, --no-ufw, --no-swap, --swap-gb 2.
This installs nginx + systemd + certbot, drops MakerFlow at /opt/makerflow-pm, and provisions a nightly DB backup cron.
doctl apps create --spec .do/app.yaml
# or, for an existing app:
doctl apps update <APP_ID> --spec .do/app.yamlIf configuring manually in the DO UI:
- Build command:
pip install -r requirements.txt - Run command:
bash -lc "python3 scripts/bootstrap_db.py && gunicorn wsgi:application --bind 0.0.0.0:$PORT --workers 2 --threads 2 --timeout 120" - HTTP port:
8080 - Health check path:
/readyz
SQLite is ephemeral on App Platform — point
MAKERSPACE_DATABASE_URLat a DO Managed PostgreSQL cluster for any non-throwaway data. Optionally migrate existing SQLite data:MAKERSPACE_DATABASE_URL='postgresql://USER:PASSWORD@HOST:25060/defaultdb?sslmode=require' \ python3 scripts/migrate_sqlite_to_postgres.py --source data/makerspace_ops.db
Common App Platform failure modes (run command invalid, health checks failing, missing tables, login loops, CSRF mismatches, Postgres SQL edge cases) are documented in docs/DEPLOYMENT.md.
Copy .env.example to .env and adjust.
| Variable | Required | Default | Purpose |
|---|---|---|---|
MAKERSPACE_SECRET_KEY |
✅ prod | change-this-secret-in-production |
HMAC signing key for cookies/sessions. 64+ chars in production. |
MAKERSPACE_COOKIE_SECURE |
✅ prod | 0 |
Set to 1 behind HTTPS. |
MAKERSPACE_HOST |
— | 127.0.0.1 |
Bind address. |
MAKERSPACE_PORT |
— | 8080 |
Listen port. |
MAKERSPACE_SESSION_DAYS |
— | 14 |
Server-side session lifetime in days. |
MAKERSPACE_DEFAULT_ORG_NAME |
— | Default Workspace |
Bootstrap workspace display name. |
MAKERSPACE_DEFAULT_ORG_SLUG |
— | default |
Bootstrap workspace slug. |
MAKERSPACE_ADMIN_EMAIL |
✅ | admin@makerflow.local |
Bootstrap admin email. |
MAKERSPACE_ADMIN_PASSWORD |
✅ | ChangeMeMeow!2026 |
Bootstrap admin password — rotate immediately. |
MAKERSPACE_ADMIN_NAME |
— | MakerFlow Admin |
Bootstrap admin display name. |
MAKERSPACE_DB_PATH |
— | data/makerspace_ops.db |
SQLite file path override. |
MAKERSPACE_DATABASE_URL |
✅ prod | — | PostgreSQL DSN. When set, MakerFlow uses Postgres for app data + sessions. |
MAKERSPACE_SMTP_HOST / _PORT / _USER / _PASSWORD / _FROM |
— | — | Optional outbound email. |
MAKERSPACE_GCAL_CLIENT_ID / _CLIENT_SECRET / _REFRESH_TOKEN / _CALENDAR_ID |
— | — | Optional Google Calendar OAuth. |
FEATURE_INTAKE_ENABLED |
— | False |
Toggle for the intake queue module. |
python3 scripts/smoke_test.py
python3 scripts/usability_test.py
python3 scripts/accessibility_audit.py
python3 scripts/comprehensive_feature_security_test.pyFull release preflight (documentation audit + functional + a11y + security + collaboration sim + cleanup + website resync + clean-state reset):
./scripts/pre_release_audit.shClean state for a fresh release:
python3 scripts/reset_release_state.pyThere is currently no pytest suite — testing is script-based. Introducing one is tracked in FEATUREROADMAP_workplan.md.
| Path | Purpose |
|---|---|
app/server.py |
Monolithic WSGI core: routes, render functions, DB, RBAC, audit, calendar sync. ~14k LOC. |
app/flask_app.py |
Flask shell that wraps the WSGI core so Gunicorn/uWSGI/Waitress can serve it. |
app/static/app.js |
Vanilla JS for CSRF, modals, kanban drag-and-drop, fetch helpers. |
app/static/style.css |
Hand-rolled CSS — no Tailwind, no build step. |
wsgi.py |
Production WSGI entrypoint. |
scripts/ |
Deploy, bootstrap, smoke, usability, accessibility, security, migration, import scripts. |
docs/ |
Architecture, data model, decisions, deployment, security, testing, diagrams. |
docs/diagrams/ |
SVG architecture diagrams referenced from this README and ProductSpec.md. |
MakerFlow Website/ |
Static landing site + wiki, deployable to GitHub Pages. |
.do/app.yaml |
DigitalOcean App Platform spec (deploy on push). |
data/ |
Local SQLite database (gitignored). |
analysis_outputs/ |
Snapshot artifacts from the release audit scripts. |
ProductSpec.md |
Developer onboarding guide. |
FEATUREROADMAP_workplan.md |
Resumable, agent-executable feature roadmap. |
MakerFlow PM ships its roadmap as a resumable, agent-executable file: FEATUREROADMAP_workplan.md. It contains a recursive regeneration prompt (to seed new tasks), an execution prompt (to build the top-ready task), 45 seeded task cards across P0–P3 (22 general + 23 accessibility), and a checkpoint log so any agent or human can pick the work up cold.
New feature work now targets the Dart rebuild — task cards live in FLUTTER_REBUILD_PLAN.md §13. FEATUREROADMAP_workplan.md remains the queue for Python-app maintenance and security work.
MakerFlow PM is built to meet WCAG 2.1 Level AA, the technical standard adopted by:
- 28 CFR Part 35, Subpart H — DOJ ADA Title II (state and local government). Compliance deadlines (post-2026 IFR extension): April 26, 2027 for entities with population ≥ 50,000; April 26, 2028 for smaller entities and special-district governments.
- 45 CFR Part 84, Subpart I — HHS Section 504 (federally-funded recipients). Compliance deadlines: May 11, 2027 for recipients with ≥ 15 employees; May 10, 2028 for smaller recipients.
The diagram below maps regulatory requirements to the 23 accessibility task cards in FEATUREROADMAP_workplan.md:
See also docs/ACCESSIBILITY.md once it lands — planned under P0-a11y-policy-baseline.
MakerFlow is being rebuilt as a single-language Dart stack — a Flutter client across six platforms on a Serverpod backend — to go beyond the web-only Python app with native mobile/desktop apps and offline, push, camera, and biometric capabilities.
What it is. One Flutter codebase compiled to web · iOS · Android · macOS · Windows · Linux, talking to a Serverpod server (PostgreSQL + Redis) via a generated, type-safe client. End-to-end type safety, an ORM, serverpod_auth, streaming endpoints, and scheduled jobs — in Dart, top to bottom.
Four locked decisions (FLUTTER_REBUILD_PLAN.md §1): Serverpod backend · all six platforms · greenfield (new deployments only, no data migration) · full parity plus native-only features.
Status — actively developed; the customization platform is live. The rebuild lives under makerflow_dart/ (37 Serverpod models + 14 endpoints behind one security contract: role guard → org-scoped queries → optimistic-concurrency versioning → audit trail → soft delete). The front end wears a monday.com-style interface (makerflow_dart/UI_REDESIGN_PLAN.md): the Vibe-derived design system, the grey-frame shell with a boards sidebar, and the signature Main Table (colored collapsible groups, inline status/date editing, ghost add-item rows, board battery) alongside keyboard-accessible kanban and List views. Phase 8 — PoC → customizable tool — is shipping: the Main Table is a real column system (drag-resize with double-click autofit, drag-reorder, show/hide, per-user persisted layouts), nine custom-field types work end-to-end (text, long-text, number, date, dropdown, tags, person, checkbox, colored labels with AA-contrast ink) with server-side validation on a JSON property-bag storage model (decision D6) and an Airtable-style type-change conversion flow, and saved views turn the view tabs into named, shareable CustomViews with dirty-state save flows. Next up: the filter builder, multi-sort, and group-by-any-field, then subitems → templates → dashboards → automations; Phase 9 (enterprise readiness ranked for university/makerspace procurement: VPAT, OIDC SSO with JIT membership, org + audit export, cohort user lifecycle, PATs, private boards/guest grants, CSV import, a public REST API + webhooks, and ops hardening) follows. Quality gates: the server integration suite runs green over live PostgreSQL, the app suite (including flutter build web) is green, and both run in CI on every push (.github/workflows/dart-ci.yml). The full demo — Serverpod API + Flutter web UI on one domain — deploys to DigitalOcean App Platform from a single spec with managed PostgreSQL + Valkey; the runbook is copy-paste from doctl auth init onward — see makerflow_dart/DEPLOY.md. Current state: makerflow_dart/BUILD_STATUS.md.
Honest caveat. The Python app is server-rendered HTML — the most accessible substrate there is — and MakerFlow carries a WCAG 2.1 AA mandate (ADA Title II + § 504, above). Flutter Web accessibility lags real HTML, so the rebuild treats web-target conformance as a Phase-0 gate with a server-rendered fallback in reserve. Native mobile/desktop a11y is strong.
Start here:
FLUTTER_REBUILD_PLAN.md— the resumable, agent-executable plan (embedded regeneration + execution prompts, phased task cards, deep-dive appendices A–M).makerflow_dart/NEXTSTEPS.md— current milestone roadmap and next steps.Flutter_ProductSpec.md— developer onboarding for the Dart stack.makerflow_dart/README.md— local bring-up.
The Dart rebuild ships from GitHub across all six targets plus the server. CI is live at the repo root (.github/workflows/dart-ci.yml) and gates every PR and every push to main/staging; per-platform release pipelines are roadmap task fl-7-release-pipelines.
| Target | GitHub mechanism |
|---|---|
| CI (every PR/push) | ✅ Live: server job — dart analyze + the integration suite against an ephemeral PostgreSQL 17 service container; app job — flutter analyze + widget tests + flutter build web. |
| Web | ✅ Live: the DO app spec (below) builds makerflow_dart/makerflow_flutter/Dockerfile.web on push and serves the bundle at the app domain. GitHub Pages/CDN remain options for standalone hosting. |
| Android | flutter build appbundle in Actions → upload to Play Console (internal track) via Fastlane; attach the APK to a GitHub Release for sideload testing. |
| iOS | flutter build ipa on a macOS runner (signing via Fastlane match) → TestFlight. |
| macOS / Windows / Linux | flutter build {macos,windows,linux} on matching runners → notarized .dmg / signed MSIX / Flatpak-Snap-AppImage → GitHub Releases. |
| Server + web demo | DigitalOcean App Platform (the required target) builds both images on every push to staging from one spec — the Serverpod API (Dockerfile, routed under /api) and the Flutter web demo (Dockerfile.web, served at /) — with DO Managed PostgreSQL 17 + Valkey. Spec: makerflow_dart/.do/app.yaml; runbook: makerflow_dart/DEPLOY.md. |
Per-platform store/signing requirements (privacy manifests, entitlements, notarization) are in FLUTTER_REBUILD_PLAN.md Appendix K.
ProductSpec.md— developer onboarding guideFEATUREROADMAP_workplan.md— recursive, resumable feature roadmapFLUTTER_REBUILD_PLAN.md— resumable, agent-executable plan for the greenfield Flutter + Serverpod (Dart) rebuild across web, mobile, and desktop (embedded regen + execution prompts, phased task cards, appendices A–M)Flutter_ProductSpec.md— developer onboarding guide for the Dart rebuildmakerflow_dart/— the Dart rebuild monorepo (Serverpod + Flutter + design) withBUILD_STATUS.mddocs/ARCHITECTURE.md— system shape, request lifecycle, deployment patternsdocs/DATA_MODEL.md— entities, roles, deletion modeldocs/DECISIONS.md— architectural decision logdocs/DEPLOYMENT.md— runbooks for local, Droplet, App Platformdocs/SECURITY.md— built-in controls and production baselinedocs/TESTING.md— verification matrixdocs/CONTRIBUTING.md— how to propose changesdocs/LICENSE.md— CC BY-SA 4.0 attribution + ShareAlike requirementsdocs/diagrams/— twelve SVG diagrams onboarding a new developer (architecture, lifecycle, data model, RBAC, deployment, components, feature flow, roadmap loop, tech stack, ADA Title II + § 504 compliance map, Flutter/Serverpod target architecture, rebuild roadmap)MakerFlow Website/wiki/— published wiki mirror
See docs/CONTRIBUTING.md. When proposing new features, add a task card to FLUTTER_REBUILD_PLAN.md §13 — new feature work targets the Dart rebuild. FEATUREROADMAP_workplan.md stays open for Python-app maintenance and security cards. Both files document their card schema at the top and are designed so an agent can pick the work up later without losing context.
Contributions are accepted under the same license as the project: CC BY-SA 4.0. By opening a pull request, you agree that your contribution is licensed accordingly.
This project is licensed under Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0).
Copyright © 2026 Ian Roy.
You are free to share (copy and redistribute the material in any medium or format) and adapt (remix, transform, and build upon the material) for any purpose, including commercially, under the following terms:
- Attribution — you must give appropriate credit to Ian Roy, provide a link to this repository (github.com/ianroy/makerflowPM), link to the license deed, and indicate if changes were made.
- ShareAlike — if you remix, transform, or build upon this project, you must distribute your contributions under the same license (
CC BY-SA 4.0). - No additional restrictions — you may not apply legal terms or technological measures that legally restrict others from doing anything the license permits.
Full text:
LICENSE— license summary in this repositorydocs/LICENSE.md— required attribution details- License deed · Legal code
MakerFlow PM · © 2026 Ian Roy · CC BY-SA 4.0 · github.com/ianroy/makerflowPM