MakerFlow PM

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)

Two codebases in this repo

1. MakerFlow PM (Python) — the current, shipping product: a server-rendered WSGI app (web only). Everything below the "Pivot" section documents it.
2. MakerFlow PM (Dart rebuild) — a greenfield Flutter + Serverpod rebuild for web, mobile, and desktop, with offline/push/camera/biometric. Currently a planned walking skeleton under makerflow_dart/, tracked in FLUTTER_REBUILD_PLAN.md. It is new deployments only — it does not replace the Python app for existing installs. See Pivot to Flutter / Dart.

---

Table of contents

• 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

---

What it is

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_log table 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.

Who built it

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.

Tech stack

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
Document import	pypdf ≥ 4.3.1	used by scripts/import_project_notes.py
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

Architecture at a glance

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_URL is 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.

How it works

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:

Data model

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.

Authorization model

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.

Quick start (local)

Option 1: Fast start (SQLite, stdlib server)

git clone https://github.com/ianroy/makerflowPM.git
cd makerflowPM
cp .env.example .env
python3 app/server.py

Option 2: Production-like start (Gunicorn + Flask shell)

git clone https://github.com/ianroy/makerflowPM.git
cd makerflowPM
cp .env.example .env
pip install -r requirements.txt
./run_flask.sh

Open 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.py

Deploying on GitHub

MakerFlow PM uses GitHub as the single source of truth. The repo supports two GitHub-native deployment paths:

1) GitHub → DigitalOcean App Platform (continuous deploy)

The .do/app.yaml spec wires App Platform to redeploy on every push to main:

github:
  repo: ianroy/makerflowPM
  branch: main
  deploy_on_push: true

Fork the repo, update .do/app.yaml with your fork name, then create the app:

doctl apps create --spec .do/app.yaml

Every 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.

2) GitHub Pages for the static site (MakerFlow Website/)

The MakerFlow Website/ directory ships an HTML landing page plus a wiki of mirrored markdown docs. To publish it via GitHub Pages:

1. In your fork, go to Settings → Pages.
2. Source: Deploy from a branch.
3. Branch: main, folder: /MakerFlow Website.
4. 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.py

3) Recommended GitHub Actions (suggested)

The repo does not yet ship a .github/workflows/ directory. 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.

Deploying on DigitalOcean

Three options:

A) Local development (SQLite)

Already covered in Quick start.

B) Single Droplet (recommended for small production)

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.

C) DigitalOcean App Platform + Managed PostgreSQL

doctl apps create --spec .do/app.yaml
# or, for an existing app:
doctl apps update <APP_ID> --spec .do/app.yaml

If 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_URL at 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.

Environment variables

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.

Testing and verification

python3 scripts/smoke_test.py
python3 scripts/usability_test.py
python3 scripts/accessibility_audit.py
python3 scripts/comprehensive_feature_security_test.py

Full release preflight (documentation audit + functional + a11y + security + collaboration sim + cleanup + website resync + clean-state reset):

./scripts/pre_release_audit.sh

Clean state for a fresh release:

python3 scripts/reset_release_state.py

There is currently no pytest suite — testing is script-based. Introducing one is tracked in FEATUREROADMAP_workplan.md.

Repository map

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.

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.

Federal accessibility compliance (ADA Title II + Section 504)

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 as part of P0-a11y-policy-baseline.

Pivot to Flutter / Dart

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 — walking skeleton that compiles. Phase 0 + a Phase 1 vertical slice live under makerflow_dart/ (37 Serverpod models + 14 endpoints with the RBAC/tenancy/audit contract; ported design tokens; a keyboard-accessible kanban + feature screens). On Dart 3.12.2 / Flutter 3.44.2 / Serverpod 3.4.10 it builds green: serverpod generate, dart analyze + server tests, flutter analyze + widget test, flutter build web, and the first DB migration (112 tables) all pass. Not yet run against a live database. See 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, 30 task cards, deep-dive appendices A–M).
• Flutter_ProductSpec.md — developer onboarding for the Dart stack.
• makerflow_dart/README.md — local bring-up.

Deploying the Dart rebuild on GitHub

The Dart rebuild is built to ship from GitHub across all six targets plus the server. (CI is scaffolded in makerflow_dart/.github/workflows/dart-ci.yml; release pipelines are roadmap task fl-7-release-pipelines.)

Target	GitHub mechanism
CI (every PR)	GitHub Actions: melos bootstrap → serverpod generate → melos run analyze + melos run test + Flutter build (web + Android), with ephemeral Postgres + Redis service containers.
Web	flutter build web → GitHub Pages (Settings → Pages → GitHub Actions), or push the static bundle to a CDN.
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	Build the Serverpod Docker image in Actions → push to GitHub Container Registry (GHCR) → a deploy job ships it to your host (DigitalOcean, etc.).

Move makerflow_dart/.github/workflows/ to the repo-root .github/workflows/ so GitHub picks the workflows up. Per-platform store/signing requirements (privacy manifests, entitlements, notarization) are in FLUTTER_REBUILD_PLAN.md Appendix K.

Documentation index

• ProductSpec.md — developer onboarding guide
• FEATUREROADMAP_workplan.md — recursive, resumable feature roadmap
• FLUTTER_REBUILD_PLAN.md — resumable, agent-executable plan for the greenfield Flutter + Serverpod (Dart) rebuild across web, mobile, and desktop (embedded regen + execution prompts, 30 task cards, appendices A–M)
• Flutter_ProductSpec.md — developer onboarding guide for the Dart rebuild
• makerflow_dart/ — the Dart rebuild monorepo (Serverpod + Flutter + design) with BUILD_STATUS.md
• docs/ARCHITECTURE.md — system shape, request lifecycle, deployment patterns
• docs/DATA_MODEL.md — entities, roles, deletion model
• docs/DECISIONS.md — architectural decision log
• docs/DEPLOYMENT.md — runbooks for local, Droplet, App Platform
• docs/SECURITY.md — built-in controls and production baseline
• docs/TESTING.md — verification matrix
• docs/CONTRIBUTING.md — how to propose changes
• docs/LICENSE.md — CC BY-SA 4.0 attribution + ShareAlike requirements
• docs/diagrams/ — eleven 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)
• MakerFlow Website/wiki/ — published wiki mirror

Contributing

See docs/CONTRIBUTING.md. When proposing new features, add a task card to FEATUREROADMAP_workplan.md using the schema documented at the top of that file — the roadmap is 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.

License

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 repository
• docs/LICENSE.md — required attribution details
• License deed · Legal code

---

_{MakerFlow PM · © 2026 Ian Roy · CC BY-SA 4.0 · github.com/ianroy/makerflowPM}