zenFlow is a standalone, institutional-grade, real-time workload orchestration platform engineered for high-velocity creative, content, and design agencies. It balances individual cognitive loads, enforces Work-In-Progress (WIP) limits, provides universal cross-board task delegation, and persists all workspace records and compliance audit logs directly to Google Cloud Firestore while maintaining strict zero-trust security and compliance auditability.
- Core Capabilities
- System Architecture
- Technology Stack
- Directory Structure
- Getting Started
- Available Scripts
- Security & Access Control
- Data Persistence & Storage Modes
- Testing & Quality Assurance
- Production Deployment
- Audit & Compliance Trail
- Dynamic Load Scoring: Tasks are weighted by cognitive strain (
Low = 1,Medium = 2,High = 3), dynamically calculating active workload pressure per team member. - WIP Limits & Demand Alarms: Configurable Work-In-Progress thresholds flag overloaded members with immediate visual warnings and demand alerts before task assignments breach capacity.
- Billable Hours & Cycle Metrics: Active time accumulation while tasks reside in
in_progress, alongside manual time adjustments, cycle tracking, and historical activity trails.
ZenFlow structures workflows across dedicated disciplines:
- Delivery Boards (Content & Design): Partitioned by delivery teams under designated Creative Directors with quick team switcher dropdowns.
- Shared Agency Disciplines (Video & UI/UX): Shared agency-wide teams operating cross-functionally across all delivery teams without board dropdown isolation.
- Swimlane Stages:
- Pipeline: Backlog ideation space for uncommitted initiatives; deadlines remain optional.
- Retainer: Ongoing, recurring client engagements without deadlines and with direct
+ Subtaskgeneration. - To Do: Prioritized queue ready for immediate execution.
- In Progress: Active execution lane with live billable duration tracking.
- In Review: Creative Director, Lead, and client review staging.
- Done & Archived: Completed milestones with timestamped cycle analytics.
- Idle Capacity Detection: A persistent glassmorphic floating pill continuously monitors members across Content, Design, Video, and UI/UX, identifying individuals with zero active tasks in
To DoorIn Progress. - Instant Allocation: Filter idle capacity by role (
All,Content,Design,Video,UI/UX) and instantly allocate tasks without leaving the active board view.
- Member Roles: Supports
Administrator,Account Manager,Content,Design,Video, andUI/UX. - Leadership Designations: Configurable designations for
Administrator,Creative Director,Cluster Lead,Content Lead, andArt Directorwith specific role tags. - Cluster Lead Association: Direct
Assigned Cluster Leadmapping while boards continue to followCreative Directoras the primary leader of a cluster. - Strict Provisioning Access: Member onboarding and role management permissions are strictly restricted to
Superadmin,Administrator,Creative Director, andCluster Lead.
- Universal Subtask Delegation: Any authenticated team member can delegate subtasks across boards. Subtasks link hierarchically under the parent task (
parentTaskId,parentTaskTitle,isSubtask: true). - Native Cloud Persistence: Tasks and team accounts save directly to Google Cloud Firestore (
users,tasks, andcompliance_audit_logs). - Resilient Fallback: Zero-crash startup resilience gracefully falls back to local storage when cloud credentials are pending configuration.
- Server-Sent Events (SSE): Bounded output streaming (256 KiB backpressure limit) ensures low latency and memory safety under multi-client loads.
- Optimistic UI with FIFO Replay: Offline changes, reorders, and creations are applied instantly to local state and replayed sequentially upon network reconnection.
flowchart TD
Client["ZenFlow Web App (React 19 + Tailwind v4 + Motion)"]
SSE["SSE Connection (/api/events)"]
AuthCookie["HttpOnly Strict Session Cookie"]
subgraph Backend["Express & TypeScript Server (Node 22)"]
SecMiddleware["Security & Auth Middleware (Google Token Verification)"]
RBAC["Role-Based Access Control (Superadmin / CD / Member)"]
Store["In-Memory App Store + Atomic Store Serializer"]
SSEHub["Bounded SSE Event Broadcaster"]
AuditEngine["Compliance Audit Log (NDJSON Tail Engine)"]
end
subgraph External["External Services"]
GoogleAuth["Google Identity Platform (zen-flow-7173d)"]
FirestoreAdmin["Google Cloud Firestore (Admin SDK)"]
LocalStorage["Local Store (data/store.json & data/audit.ndjson)"]
end
Client -->|Google ID Token Exchange| SecMiddleware
SecMiddleware -->|Verify Token| GoogleAuth
SecMiddleware -->|Set Session Cookie| AuthCookie
Client <-->|REST API Requests| SecMiddleware
SecMiddleware --> RBAC --> Store
Store --> SSEHub -->|Live Updates| SSE --> Client
Store <-->|Primary Persistence| FirestoreAdmin
Store <-->|Local Fallback Volume| LocalStorage
AuditEngine -->|Append Log Entry| FirestoreAdmin
AuditEngine -->|Local NDJSON Stream| LocalStorage
| Layer | Technologies |
|---|---|
| Frontend Framework | React 19 + TypeScript |
| Build & Tooling | Vite 6 + esbuild |
| Styling & Animation | Tailwind CSS v4 + Motion (Framer Motion v12) |
| Icons & UI | Lucide React |
| Backend Server | Express 4 on Node.js >= 22 (ES Modules & tsx) |
| Database & Cloud Storage | Firebase Admin SDK + @google-cloud/firestore |
| Authentication | Google Identity Platform (zen-flow-7173d) via Firebase Auth + HttpOnly Session Cookies |
| Testing | Node.js Test Runner (node --test), @firebase/rules-unit-testing, Firebase Emulators |
| Deployment | Docker (Multi-stage build), Railway, Nixpacks, Procfile |
c:/ZenFlow/
βββ .github/workflows/ # CI/CD workflows (Node 22 / Java 21)
βββ data/ # Local volume data (store.json, audit.ndjson, webhooks.json)
βββ docs/
β βββ READINESS.md # Enterprise readiness & deployment verification guide
βββ public/ # Static assets & favicons
βββ server/
β βββ resources.ts # Audit tail reader & bounded SSE transport
β βββ security.ts # Auth middleware, cookie issuance & payload redaction
βββ src/
β βββ components/ # Reusable UI components & modals (Swimlanes, FreePool, etc.)
β βββ context/ # DashboardContext (state management, offline queue)
β βββ lib/ # Firebase client initialization & session management
β βββ utils/ # Workload calculations, date formatting & audit helpers
β βββ App.tsx # Main application layout & swimlane orchestrator
β βββ index.css # Design tokens & Tailwind theme definitions
β βββ main.tsx # React DOM entry point
β βββ types.ts # TypeScript interfaces (User, Task, AuditLog)
βββ tests/
β βββ benchmark-audit.ts # Synthetic benchmark for asynchronous audit log reading
β βββ client-session.test.ts # Client session migration & token race tests
β βββ firestore.emulator.ts # Firestore Security Rules unit test suite
β βββ fixtures.ts # Mock server, store & identity fixtures
β βββ resources.test.ts # SSE backpressure & audit tail unit tests
β βββ security.test.ts # Comprehensive RBAC & security verification tests
β βββ smoke-production.ts # Compiled server artifact production smoke test
βββ Dockerfile # Multi-stage container definition
βββ firestore.rules # Server-owned Firestore security rules
βββ package.json # Project dependencies and script declarations
βββ server.ts # Central Express application and Firestore persistence
βββ vite.config.ts # Vite frontend configuration
- Node.js:
v22.0.0or higher - npm:
v10.0.0or higher - Java: JRE 21+ (optional, required only for running local Firestore Emulator tests)
- Google Cloud / Firebase Project: Dedicated Firebase project for Firestore storage (Google Identity uses
zen-flow-7173d)
-
Clone the repository:
git clone https://github.com/schultz911/ZenFlow.git cd ZenFlow -
Install dependencies:
npm ci
Create a .env file in the project root:
cp .env.example .envPopulate the configuration values:
# Application URL where the app is hosted (e.g. http://localhost:3000)
APP_URL=http://localhost:3000
# Server Port and Node Environment
PORT=3000
NODE_ENV=development
# Firebase Service Account Key (JSON string, base64-encoded string, or path to serviceAccountKey.json)
FIREBASE_SERVICE_ACCOUNT_KEY=
# Optional local persistent storage directory (defaults to ./data)
ZENFLOW_DATA_DIR=./dataStart the full-stack server (serves the Vite frontend and the Express backend concurrently):
npm run devVisit http://localhost:3000 in your browser.
| Command | Action |
|---|---|
npm run dev |
Starts the server in development mode using tsx server.ts. |
npm run build |
Compiles the Vite frontend to dist/ and bundles server.ts into dist/server.cjs via esbuild. |
npm run start |
Runs the compiled production server (node dist/server.cjs). |
npm run lint |
Runs TypeScript compiler checks without emitting files (tsc --noEmit). |
npm test |
Runs the complete Node.js test suite across security, sessions, and resources. |
npm run test:rules |
Executes Firestore Security Rules unit tests against the local Firebase Emulator. |
npm run clean |
Cleans build artifacts (dist/ and temporary server outputs). |
ZenFlow adopts a Zero-Trust, Server-Owned security posture:
+--------------------------------------------------------------------------+
| RBAC Role Hierarchy |
+--------------------------------------------------------------------------+
| Superadmin (kiran.s@zensciences.com) |
| βββ Full system administration, member provisioning & CD assignment |
| βββ Firebase credential management & database status inspection |
| βββ SOC2 Compliance audit trail downloads & monitoring |
| |
| Creative Director (CD) |
| βββ Board oversight for assigned team (Content / Design) |
| βββ Task review, workload balancing & team member task management |
| |
| Team Member |
| βββ Universal cross-board subtask delegation to any peer |
| βββ Personal task creation, status updates & billable adjustments |
+--------------------------------------------------------------------------+
- HttpOnly Cookie Sessions: Verified Google ID tokens are exchanged for an
HttpOnly,SameSite=Strictsession cookie scoped strictly to/api. Tokens are never exposed in URLs or client-accessible web storage. - CSRF & Same-Origin Mutation Protection: All state-modifying requests require custom headers validated against the application origin.
- Firestore Security Rules: Direct client reads and writes are denied unconditionally (
allow read, write: if false;). Data is manipulated exclusively by the backend via the Firebase Admin SDK through IAM credentials.
ZenFlow operates under two coordinated persistence tiers:
- Cloud Persistence (Primary):
- Powered by Firebase Admin and
@google-cloud/firestore. - Collections:
users,tasks, andcompliance_audit_logs. - Active whenever
FIREBASE_SERVICE_ACCOUNT_KEYis supplied in the environment or uploaded by Superadmin.
- Powered by Firebase Admin and
- Local Volume Fallback:
- Persisted as structured JSON in
data/store.jsonand append-only NDJSON indata/compliance-audit.jsonl. - Guaranteed atomic writes using temporary swap files (
.tmp) to eliminate corruption during sudden process restarts.
- Persisted as structured JSON in
The test suite exercises real extracted handlers behind live authorization middleware without accessing production services:
# 1. Run all unit and security integration tests
npm test
# 2. Run Firestore Security Rules emulator tests (requires Java 21)
npm run test:rules
# 3. Perform static analysis and TypeScript verification
npm run lint
npx tsc --noEmit --noUnusedLocals --noUnusedParameters
# 4. Run the synthetic audit tail performance benchmark
node --expose-gc --import tsx tests/benchmark-audit.tsZenFlow includes a multi-stage Dockerfile optimized for minimal attack surface and resource efficiency:
# Build the production container image
docker build -t zenflow:latest .
# Run container with persistent local storage and environment credentials
docker run -d \
-p 3000:3000 \
-e PORT=3000 \
-e NODE_ENV=production \
-e FIREBASE_SERVICE_ACCOUNT_KEY="<SERVICE_ACCOUNT_KEY_JSON>" \
-v zenflow_data:/app/data \
--name zenflow zenflow:latestZenFlow provides pre-configured railway.json, nixpacks.toml, and Procfile manifests for deployment. Ensure the following steps are performed:
- Provide
FIREBASE_SERVICE_ACCOUNT_KEYin platform environment variables. - Mount a persistent volume to
/app/data(or specifyZENFLOW_DATA_DIR). - Deploy frontend and backend together.
- Deploy Firestore security rules via
npx firebase deploy --only firestore:rules --project <YOUR_STORAGE_PROJECT>. - Access the Connections & Compliance modal as Superadmin to register the ClickUp HMAC webhook.
For a detailed deployment runbook, refer to docs/READINESS.md.
All critical system actions (task creations, edits, status transitions, user updates, credential modifications, and webhook deliveries) are recorded to an append-only compliance log:
- Streaming NDJSON: Stored in
data/audit.ndjsonand mirrored to Firestorecompliance_audit_logs. - Tail-Optimized Reads: Backend reverse-reads recent log entries in 64 KiB blocks, providing fast initial log hydration without loading multi-megabyte audit histories into memory.
- Exportable Compliance Logs: Superadmins can stream and download complete compliance records via
/api/audit/download.
Designed and maintained for ZenSciences. All rights reserved.