ApprovalFlow
A self-hosted approval-workflow app. Requests arrive by email (or through a login-protected web form), get redirected to an approver, and once approved or denied, everyone involved up to that point is notified by email. Every request keeps a full audit log of everything that happened to it.
What it does
- Email intake. An IMAP poller watches a mailbox. Incoming messages become requests and enter the workflow's approval chain with one-click Approve / Deny links.
- Sequential multi-step approval. Every workflow has an ordered chain of approvers. The request goes to the first person; each approval sends it on to the next; the last approval completes it. A denial at any step stops the workflow immediately — nobody later in the chain is contacted.
- Decisions notify everyone. On the final outcome (approved or denied), the requester, anyone CC'd on the original email, and every approver involved up to that point receive the outcome email.
- Full log. Every request records: received, matched workflow, each approval request sent, each step's decision, notifications, and any mail errors — each with a timestamp.
- Multiple named workflows, each personalized: its own approval chain and the wording of all three emails (approval request, approved notice, denied notice) with
{placeholders}. - Main page (login required): users pick a workflow they have access to and submit a request from the browser.
- Admin pages: create/edit/pause workflows, monitor all requests and open their full logs, decide directly from the UI, manage users, and set which users can access which workflows.
Quick start (Docker)
cp .env.example .env # edit it: SECRET_KEY, BASE_URL, IMAP_*, SMTP_*
docker compose up -d
Open http://localhost:8000 and sign in with ADMIN_USERNAME / ADMIN_PASSWORD from .env (defaults admin / changeme — change them). The SQLite database lives in ./data/.
Quick start (bare Python)
pip install -r requirements.txt
cp .env.example .env
set -a; source .env; set +a # or export the variables another way
python app.py
Leaving SMTP_HOST empty prints outgoing mail to the console and leaving IMAP_HOST empty disables email intake — handy for trying the app before wiring up a mailbox.
How email intake targets a workflow
- Plus-addressing: mail sent to
inbox+<workflow-slug>@your-domaintargets that workflow. - Subject tag: a subject containing
[<workflow-slug>]. - Fallback: if exactly one active workflow exists, it is used.
Unmatched mail is ignored.
The request lifecycle
email / web form
│ received + logged
▼
approval request → approver 1 ── deny ──► STOP: DENIED notice to
│ approve everyone involved so far
▼
approval request → approver 2 ── deny ──► STOP: DENIED notice ...
│ approve
▼
⋮ (… every approver in the chain, in order)
▼
last approver approves ──► APPROVED notice to everyone involved
(requester + CCs + all approvers)
Each step gets a fresh secret link, so an earlier approver's link cannot decide later steps.
Personalization placeholders
Usable in every workflow's subject and body templates:
{workflow}, {requester}, {subject}, {body}, {request_id}, {step}, {total_steps}, {decided_by}, {approve_url}, {deny_url}.
Security notes
- Set a strong
SECRET_KEYand put the app behind HTTPS (a reverse proxy such as Caddy or nginx) — the approve/deny links are secrets. - Decision links are unguessable random tokens and work only once; a second click shows "already decided."
- Passwords are stored hashed (Werkzeug PBKDF2). Change the bootstrap admin password immediately.
- Non-admin users only ever see and use the workflows they've been granted.
Project layout
app.py Flask routes, auth, admin pages
db.py SQLite schema + audit-log helpers
pipeline.py approval request + decision/notification logic
poller.py IMAP inbox watcher (background thread)
mailer.py SMTP sending + template rendering
templates/ pages static/style.css styling