ClientFlow is a multi-tenant client and project management SaaS for freelancers and small agencies. Teams manage clients, projects, milestones, tasks, and versioned deliverables. Clients receive a restricted portal to track shared progress and approve or request changes to submitted work.
- Next.js App Router, React Server Components, Server Actions, Route Handlers
- TypeScript strict mode
- PostgreSQL and Prisma 7
- Auth.js Credentials with JWT sessions
- Argon2id password hashing
- Tailwind CSS
- Zod validation
- Vitest and Playwright
- Vercel deployment target with Neon PostgreSQL
- Local private file storage in development; S3-compatible private object storage in production
The seed script creates an OWNER account and a linked CLIENT portal account. In a seeded demo environment, use:
| Role | Password | |
|---|---|---|
| Owner | owner@clientflow.local |
ClientFlowDemo!2026 |
| Client | client@clientflow.local |
ClientFlowDemo!2026 |
Public demo warning: this is shared demo data, not a private workspace. Other visitors can create, edit, or delete demo records. The demo database may be reset without notice. Never upload confidential files or reuse these credentials elsewhere. Set SEED_DEMO_PASSWORD to override the seed password.
Start PostgreSQL and the Next.js app, apply migrations, and seed the Owner/Client demo accounts:
docker compose up --buildThen open http://localhost:3000. The Compose setup uses local file storage and a disposable PostgreSQL volume; it is for local development/demo only, not production. Use docker compose down -v to remove the local database and uploaded demo files.
flowchart TD
Browser[Owner / Team / Client browser] --> Next[Next.js App Router on Vercel]
Next --> Auth[Auth.js JWT + role authorization]
Next --> Actions[Server Actions and Route Handlers]
Actions --> Validate[Zod validation]
Validate --> Services[Domain services and state machines]
Services --> Prisma[Prisma ORM]
Prisma --> Neon[(Neon PostgreSQL)]
Services --> Storage[Private S3 / R2 object storage]
Services --> Mail[Resend invitation email]
flowchart LR
Upload[Upload deliverable] --> Submit[Submit for client review]
Submit --> Decision{Client decision}
Decision -->|Approve| Approved[Approved version]
Decision -->|Request changes| Changes[Changes requested]
Changes --> Revision[Upload revised version]
Revision --> Submit
For isolated PostgreSQL integration and E2E testing on Windows, follow Local testing. The integration and E2E commands block non-local or non-test databases.
Requirements: Node.js 22+, npm, and Docker Desktop / Docker Engine.
-
Start the local PostgreSQL database:
docker compose up -d postgres
-
Install dependencies:
npm ci
-
Create
.env:PowerShell
Copy-Item .env.example .envmacOS / Linux
cp .env.example .env
-
Configure
DATABASE_URLand a randomAUTH_SECRET(at least 32 characters). -
Generate the Prisma Client:
npm run db:generate
-
Apply the Prisma migration(s):
npm run db:migrate
-
Seed the local database with demo workspaces, roles, clients, and projects:
npm run db:seed
-
Start the app:
npm run dev
Open http://localhost:3000, create an account, and create a workspace.
- Account registration and Credentials sign-in with Argon2id verification.
- Workspace creation and OWNER membership.
- Workspace-scoped client and project creation.
- Project milestones and task creation/status changes.
- Client portal account linking to an existing account with a matching email.
- Restricted client portal project overview; only tasks marked
visibleToClientare returned. - Deliverable drafts, submission, client approval or change requests, and version creation after requested changes.
- Optimistic revision checks to prevent duplicate deliverable decisions.
- Transactional Activity records for supported mutations.
- Workspace invitations with hashed, expiring tokens and acceptance.
- Database-backed login and invitation rate limits.
- Private file upload/download through local storage in development and S3-compatible storage in production.
Configure these environment variables in Vercel (or the deployment environment):
S3_BUCKETS3_REGIONS3_ACCESS_KEY_IDS3_SECRET_ACCESS_KEY- Optional
S3_ENDPOINTfor S3-compatible services such as Cloudflare R2.
The production storage adapter uses server-side credentials and does not expose object URLs publicly. Downloads are streamed through an authenticated Route Handler.
Uploads currently allow PDF, PNG, JPEG, WebP, DOCX, and XLSX files up to 4 MB. File names are sanitized for display; object keys are generated server-side. DOCX/XLSX archives are inspected without extracting to disk: encrypted, malformed, multi-disk, ZIP64, duplicate-path, traversal, and symlink entries are rejected; archives are limited to 1,000 entries, 16 MB per expanded entry, 32 MB total expanded data, and a 100:1 compression ratio. Malware scanning is not implemented in this release. Treat uploaded files as untrusted and keep downloads attachment-only; enable a dedicated malware-scanning pipeline before accepting sensitive or high-risk uploads.
npm run lint
npm run typecheck
npm test
npm run test:e2e
npm run buildGitHub Actions runs three independent jobs: quality/build, PostgreSQL integration tests, and Playwright E2E. The quality job also checks Prettier formatting with npm run format:check. E2E includes axe-core WCAG 2.1 A/AA checks and uploads a Lighthouse report covering performance, accessibility, best practices, and SEO. A separate daily workflow removes expired rate-limit buckets in bounded batches; configure the PRODUCTION_DATABASE_URL GitHub Actions secret to enable it.
Deliverable notification events are not enabled in this release. The former logging-only provider stub and its call sites were removed so the application does not imply that email or in-app notifications are being delivered. Invitation email delivery remains a separate optional Resend integration.
- Explicit state machine: deliverable review transitions are constrained to valid states, and reviewed versions remain immutable. This prevents clients and team members from applying conflicting or invalid decisions.
- PostgreSQL rate limiting: fixed-window counters are updated atomically in the shared database, so multiple Vercel instances use the same limits instead of independent in-memory counters.
- Optimistic revision checks: a review decision includes the expected revision in its conditional update. Only one concurrent decision can update that revision; a stale request is rejected rather than overwriting a newer state.
- Tenant-scoped relational constraints: workspace identifiers are included in relevant foreign keys and queries to reduce the risk of cross-workspace references.
npm run db:generate— generate Prisma Client.npm run db:seed— seed local demo users, workspaces, clients, and projects.docker compose down -v— remove the local database volume (destructive; deletes local data).npm run db:migrate— create/apply a development migration.npm run db:deploy— apply committed migrations in deployment.npm run db:studio— open Prisma Studio.
Commit migration files together with schema changes. Never commit .env, database credentials, or production secrets.
- Workspace-owned reads and writes are scoped by
workspaceId. - Workspace membership, role checks, and client project access are enforced server-side.
- Client portal queries exclude internal tasks and unrelated client projects.
- Server inputs are validated with Zod and persisted under database constraints.
- Deliverable state transitions are explicit; decided versions are not edited in place.
- Revision checks use conditional updates inside transactions.
- Supported mutations create Activity records in the same transaction.
- Services live in
src/server/services; shared schemas live insrc/lib/validations. - Private file downloads re-check workspace or client project access on every request.
- Provision Neon PostgreSQL and set
DATABASE_URL. - Set
AUTH_SECRET,AUTH_URL, and the S3-compatible storage variables. - Configure the Vercel project for this repository and branch.
- Run
npm run db:deployas a release/deployment step before serving the new application version. - Deploy with
npm run build.
Do not consider a deployment production-ready until a real Neon database, production S3 bucket, environment variables, and the complete migration set have been configured and verified.
See docs/DATABASE.md for the Mermaid ER diagram and database constraint rationale.
See Production service setup for PostgreSQL migration preflight, private S3-compatible storage, Resend invitation email, and post-deployment verification.
- Frontend: Next.js App Router, React, TypeScript, Tailwind CSS, server and client components.
- Backend: Server Actions, Route Handlers, REST-style API design, Zod validation.
- Data: PostgreSQL, Prisma ORM, schema migrations, relational data modeling.
- Security: Auth.js credentials authentication, Argon2id password hashing, role-based access control, workspace-level authorization, rate limiting, private object storage.
- Quality: Vitest, Playwright, integration testing, TypeScript strict mode, ESLint, Prettier.
- Delivery: Docker-based development workflows, GitHub Actions CI, Vercel, Neon PostgreSQL.
- Source code: https://github.com/ADAMDEV01/ClientFlow
- Live application: https://client-flow-isvm6brdg-addrryhby-5992.vercel.app
- GitHub repository: https://github.com/ADAMDEV01/ClientFlow