FuturnFlow · Technical documentation

System diagrams & data model

How FuturnFlow fits together: the deployment architecture, the entity-relationship model behind every screen, and the workflows that move work from intake to done.

1 · Deployment architecture

FuturnFlow is four Docker containers on one office server. Teammates' browsers only ever talk to the frontend; integrations talk to the server's REST API.

Team browsers any device on the LAN http://<server-ip>:8080 Integrations REST · X-Api-Key header OFFICE SERVER · Docker Compose frontend Next.js app · port 8080→3000 UI, auth/sessions, server actions, reads/writes DB via Prisma server Express API · port 4000 REST /api/v1 · email service · health checks · bootstrap (migrations + admin seed) database PostgreSQL 16 not exposed to the LAN volume: futurnflow_pgdata mailpit test email inbox · port 8025 or real SMTP via .env HTTP :8080 HTTP :4000 Prisma / SQL SQL emails (service token) SMTP
All four containers restart automatically. Data persists across restarts in the futurnflow_pgdata volume. Both the frontend and the server talk to PostgreSQL directly; the frontend calls the server only to send email.

2 · The chain every piece of work follows

Every screen in the app maps to one link in this chain:

Client needs something Form structured intake Project container · key Tasks atomic work units Approvals sign-off gates Reports derived, live convert break down
Forms are optional (projects can be created directly) but are the recommended intake path — an approved form converts to a project with its deliverables as starter tasks. Sprints, boards, calendars and timelines are all just views over tasks.

3 · Entity-relationship diagram (core)

The heart of the data model. Every entity belongs to the single Organization; the diagram shows the relationships that shape the app (crow's-foot style: 1—∗ reads "one … has many …").

User role · status · email assignee / reporter / PM / owner / approver / account manager on other entities ↳ Department · Team Client company · contact · status accountManager → User active | prospect | paused | archived Project projectKey (FUT-001) · type status · priority · dates · budget owner / projectManager → User members: ProjectMember[*] taskCounter for key numbering Sprint goal · capacity · dates planned | active | completed one active per project Task number → KEY-n · type · status priority · severity (bugs) · dates estimate · storyPoints · labels assignee / reporter → User parentTask → Task (subtasks) epic → Task (Epic type) sprint · department · client · campaign links (all optional) TaskChecklist text · completed · createdBy TaskWatcher user follows task updates TimeLog hours · note · date · user Campaign channel · stage · launch date Idea → … → Live → Completed owner → User · client · project links (optional) Form 7 brief types · payloadJson Draft → … → Approved → Converted to Project convertedProjectId → Project Approval entityType + entityId (any item) stage: Internal | Management | Client Review requestedBy / approver → User Comment · ActivityLog · Asset attach to any entity via entityType + entityId (same pattern as Approval) 1 — ∗ 1 — ∗ 1 — ∗ 1 — ∗ assigned 1 — ∗ 1 — ∗ 1 — ∗ converts to gates any entity
Simplified: Organization (the single workspace), Department/Team/TeamMember, Notification, Doc, and the four configuration entities (Workflow, CustomField, Template, AutomationRule) are omitted here — see the full data dictionary below.

4 · Full data dictionary

Every table in the PostgreSQL schema (source of truth: database/schema.prisma). Blue lines are relationships.

Organization & people

Organization workspace
  • name · logoUrl · settings (JSON)
  • → has all departments, teams, users, clients, projects, tasks, campaigns, forms, assets, rules, docs, workflows, fields, templates
Department people
  • name · description
  • → Organization · has Users, Teams, Tasks
Team people
  • name · leadUserId
  • → Organization · Department? · lead → User · members via TeamMember
TeamMember people
  • join table · unique (team, user)
  • → Team · User
User people
  • name · email (unique) · passwordHash
  • role: Owner | Admin | Project Manager | Team Lead | Team Member | Client Viewer | Guest
  • status: active | invited | disabled · jobTitle · avatarColor · timezone · notificationPrefs (JSON)
  • → Organization? · Department? · referenced as assignee, reporter, watcher, PM, owner, account manager, approver, uploader, author across the model

Clients & delivery

Client crm
  • name · company · contactName · email · phone · website · industry · notes
  • status: active | prospect | paused | archived
  • → accountManager → User · has Projects, Tasks, Campaigns, Forms
Project delivery
  • projectKey (unique, e.g. FUT-001) · name · type (9 types) · description
  • status: Planning | Active | On Hold | In Review | Completed | Archived · priority · startDate/dueDate · budget · tags
  • taskCounter — feeds per-project task numbering
  • → Client? · owner/projectManager → User · has members (ProjectMember), Tasks, Sprints, Campaigns
ProjectMember delivery
  • role (default Member) · unique (project, user)
  • → Project · User
Sprint delivery
  • name · goal · capacity (points) · startDate/endDate
  • status: planned | active | completed
  • → Project · has Tasks
Task delivery · core
  • number (unique per project → KEY-n) · title · description
  • type: 14 types (Epic, Task, Subtask, Bug, Design Task, …)
  • status: 11 statuses (see task lifecycle) · priority: Critical→Backlog · severity (bugs)
  • startDate/dueDate · estimatedHours · storyPoints · labels · brand · approvalRequired · customFields (JSON) · rank
  • → Project · Client? · Sprint? · Department? · Campaign? · assignee/reporter → User · parentTask → Task (subtasks) · epic → Task · has Checklist, Watchers, TimeLogs
TaskChecklist / TaskWatcher / TimeLog delivery
  • Checklist: text · completed — Watcher: unique (task, user) — TimeLog: hours · note · date
  • each → Task · User

Marketing & intake

Campaign marketing
  • name · brand · objective · channel (8 channels) · budget · startDate/launchDate/endDate
  • status: Idea → Planning → Content Creation → Design → Internal Review → Client Review → Scheduled → Live → Completed | Archived
  • → Client? · Project? · owner → User · has Tasks
Form intake
  • type: 7 brief types · title · payloadJson (the filled fields) · dueDate
  • status: Draft → Submitted → Under Review → (Information Missing ⇄) → Approved → Converted to Project | Archived
  • convertedProjectId — set when converted
  • → Client? · submittedBy → User
Approval governance
  • entityType+entityId (task | campaign | form | asset | project) · title · versionNote · comments · dueDate
  • stage: Internal Review | Management Review | Client Review
  • status: Pending | Approved | Changes Requested | Rejected
  • requestedBy / approver → User

Collaboration & content

Comment collab
  • body · visibility: internal | client · edited
  • → User · attaches to any entity (entityType + entityId)
ActivityLog audit
  • action · oldValue/newValue — powers Activity tabs and the Audit log
  • → User? · attaches to any entity
Asset files
  • fileName · fileType (10 types) · fileUrl? · version · approvalStatus
  • metadata records — binary upload is a planned feature
  • → uploadedBy → User? · attaches to any entity
Notification collab
  • type · title · message · read · links to an entity
  • → User (indexed by user + read)
Doc knowledge
  • space (6 spaces) · title · content (plain text)
  • → parent → Doc (nested pages) · createdBy → User?

Configuration

Workflow config
  • workType: Creative | Campaign | Product Form | Development | Operations | Default · statusesJson (ordered status names)
CustomField config
  • entityType · fieldType (9 types) · optionsJson · required
Template config
  • kind: project | task · payloadJson (the pre-filled shape)
AutomationRule config
  • trigger · conditionJson · actionJson · enabled
  • event-driven rules run today; time-based ones await a scheduler

5 · Status workflows

Task lifecycle (11 statuses → 7 board columns)

Backlog→ To Do→ In Progress→ Internal Review · Client Review · Waiting for Client · Changes Requested→ Approved→ Done
Blocked⇄ reachable from any active status Cancelled— terminal, shares the Done column

The four review-ish statuses collapse into a single Review column on boards; dropping a card there sets Internal Review.

Campaign stages

Idea→ Planning→ Content Creation→ Design→ Internal Review→ Client Review→ Scheduled→ Live→ Completed
Built-in automation

Moving a campaign to Client Review automatically creates an approval task for the campaign owner.

Intake form lifecycle

Draft→ Submitted→ Under Review→ Approved→ Converted to Project
Information Missing⇄ Under Review (submitter notified, fills gaps, resubmits)

Approval decision flow

Request (pick approver + stage)→ Pending→ Approvedor Changes Requestedor Rejected

Stages escalate: Internal Review → Management Review → Client Review. An internally-approved item can be sent onward to client review with one click.

6 · Role permission matrix

Permissions are hierarchical — each capability has a minimum role (source: frontend/src/lib/permissions.ts).

CapabilityOwnerAdminPMTeam LeadTeam MemberClient ViewerGuest
Manage org settings, workflows, automation✓✓—————
Invite / edit / disable users✓✓—————
Create/manage projects, sprints, campaigns, clients✓✓✓————
Assign work to others, approve internal reviews✓✓✓✓———
Create/update tasks, comment, log time✓✓✓✓✓——
See internal comments & internal projects✓✓✓✓✓——
View shared work, decide approvals addressed to them✓✓✓✓✓✓✓

Client Viewers and Guests also get a reduced sidebar: Dashboard, Projects, Campaigns, Approvals, Calendar only.

7 · What happens when you click something

Browser click / form submit Server Action session + role check (requireRole / can.*) Prisma → SQL write + ActivityLog + Notifications revalidatePath UI refreshes with fresh data Email service (server) welcome / reset mails via SMTP only for account emails
The Next.js frontend owns all business logic via server actions; every mutation is permission-checked, logged to ActivityLog, and triggers in-app notifications. The Express server is used for email delivery, the REST API, and startup bootstrap.