FlowSpace

Work that flows.

An open-source project management platform that blends the structural power of ClickUp, the document flexibility of Notion, and the clean aesthetic of Linear.

Getting Started · Architecture · Contributing · Roadmap

---

Why FlowSpace?

Teams don't fail because of missing features. They fail because tools are either too rigid (Jira) or too free-form (Notion). FlowSpace gives you structure where you need it and freedom where you want it.

• Open Source Core — Self-host on your own infrastructure, no vendor lock-in
• ClickUp-style Views — Kanban, List, Timeline, Calendar, Table — all in one project
• Notion-like Docs — Rich documents with slash commands, nested pages, and publishing
• Linear Aesthetic — Clean, fast UI that feels like a native desktop app
• Developer-first — REST API, webhooks, TypeScript SDK (coming soon)

---

Getting Started

Prerequisites

• Node.js >= 22
• pnpm >= 10
• Docker (for PostgreSQL, Redis, Meilisearch, MinIO)

Quick Start

# Clone the repo
git clone https://github.com/your-username/flowspace.git
cd flowspace
# Install dependencies
pnpm install
# Copy environment variables
cp .env.example .env
# Start infrastructure (PostgreSQL, Redis, Meilisearch, MinIO)cd packages/flowspace-docker && docker compose up -d &&cd ../..
# Push database schema & seed with demo datacd packages/flowspace-server
DATABASE_URL="postgresql://flowspace:flowspace@localhost:5433/flowspace" npx prisma db push
DATABASE_URL="postgresql://flowspace:flowspace@localhost:5433/flowspace" npx tsx seeds/dev.seed.ts
cd ../..
# Start the API server (Terminal 1)cd packages/flowspace-server
npx tsc -p tsconfig.json
DATABASE_URL="postgresql://flowspace:flowspace@localhost:5433/flowspace" node dist/main.js
# Start the frontend (Terminal 2)cd packages/flowspace-front
npx next dev --port 3000

Open http://localhost:3000 — you're in.

---

Architecture

FlowSpace follows the Twenty CRM monorepo pattern — all packages live under packages/.

packages/
├── flowspace-server/ # NestJS API + Prisma ORM
│ ├── src/
│ │ ├── database/ # PrismaService (global DI provider)
│ │ └── modules/ # NestJS feature modules
│ │ ├── auth/ # Signup, login, JWT
│ │ ├── workspace/ # Workspace CRUD + members
│ │ ├── space/ # Spaces (project groups)
│ │ ├── project/ # Projects + default statuses
│ │ ├── task/ # Task CRUD + bulk updates
│ │ ├── comment/ # Threaded comments
│ │ ├── document/ # Notion-like pages
│ │ ├── notification/ # In-app notifications
│ │ └── search/ # Meilisearch integration
│ ├── prisma/
│ │ └── schema.prisma # 15 tables, all relations
│ └── seeds/ # Dev + test seed data
│
├── flowspace-front/ # Next.js 15 frontend
│ └── src/
│ ├── app/ # App Router pages
│ │ ├── (auth)/ # Login, Signup
│ │ ├── (app)/ # Authenticated layout (sidebar + canvas)
│ │ └── onboarding/
│ ├── components/
│ │ ├── layout/ # Sidebar, Topbar, CommandMenu
│ │ ├── tasks/ # KanbanBoard, TaskList, TaskCard, TaskDetailPanel
│ │ └── projects/ # ProjectHeader
│ ├── lib/ # API client, Zustand stores
│ └── styles/ # Tailwind v4 theme (globals.css)
│
├── flowspace-worker/ # BullMQ background jobs
├── flowspace-docker/ # Docker Compose (Postgres, Redis, Meilisearch, MinIO)
├── flowspace-ui/ # Shared shadcn/ui component library
├── flowspace-types/ # Shared TypeScript types
├── flowspace-utils/ # Shared utilities (slugify, fractionalIndex, etc.)
└── flowspace-emails/ # React Email templates (welcome, invite, notification)

Tech Stack

Layer	Technology
Frontend	Next.js 15, React 19, Tailwind CSS v4, shadcn/ui, dnd-kit, Zustand, TanStack Query
Backend	NestJS 11, Prisma 6, PostgreSQL 16, Redis 7, BullMQ
Search	Meilisearch v1
Storage	MinIO (S3-compatible)
Auth	Better Auth (email/password + OAuth)
Email	React Email + Resend
Monorepo	pnpm workspaces

Database Schema

15 tables covering the full PM domain:

users · workspaces · workspace_members · spaces · projects · statuses · tasks · comments · documents · time_entries · notifications · activities · custom_field_definitions · integrations · api_keys

---

Features

Implemented (Phase 1 MVP)

• Auth — Email/password signup & login
• Workspaces — Multi-tenant with slug-based URLs
• Spaces — Group projects (Engineering, Marketing, etc.)
• Projects — CRUD with auto-created statuses
• Kanban Board — Drag-and-drop tasks between columns
• List View — Grouped by status with inline details
• Task Detail Panel — Slide-over with properties, comments
• Documents — Nested page tree with expandable folders
• My Tasks — Personal task inbox with filters
• Global Search — Cmd+K command menu
• Settings — General, Members, Billing pages
• Onboarding — 3-step workspace creation wizard
• Dark Mode — System/manual toggle
• Canvas Layout — ClickUp-style with sidebar frame + rounded content panel

Planned (Phase 2)

• Timeline / Gantt view
• Calendar view
• Table view with custom columns
• Custom fields (all types)
• Time tracking
• Automations builder
• Slack + GitHub integrations
• Stripe billing
• Email notifications
• REST API + webhooks

Planned (Phase 3)

• SSO / SAML
• Electron desktop app
• AI features (Claude API)
• Portfolio view
• TypeScript SDK

---

API Endpoints

All endpoints are prefixed with /v1.

Method	Endpoint	Description
GET	/v1/health	Health check
POST	/v1/auth/signup	Create account
POST	/v1/auth/login	Sign in
GET	/v1/workspaces	List workspaces
GET	/v1/workspaces/:slug	Get workspace by slug
POST	/v1/workspaces	Create workspace
GET	/v1/spaces?workspaceId=	List spaces
POST	/v1/spaces	Create space
GET	/v1/projects?spaceId=	List projects
POST	/v1/projects	Create project (auto-creates statuses)
GET	/v1/projects/:id/statuses	Get project statuses
GET	/v1/tasks?projectId=	List tasks
POST	/v1/tasks	Create task
PATCH	/v1/tasks/:id	Update task
DELETE	/v1/tasks/:id	Delete task
POST	/v1/tasks/bulk-update	Bulk update tasks
GET	/v1/comments?taskId=	List comments
POST	/v1/comments	Create comment
GET	/v1/documents?workspaceId=	List documents
POST	/v1/documents	Create document
GET	/v1/notifications?userId=	List notifications
GET	/v1/search?q=	Search across entities

---

Contributing

We welcome contributions! Here's how to get started:

Development Setup

1. Fork and clone the repo
2. Follow the Getting Started steps
3. Create a branch: git checkout -b feature/your-feature
4. Make your changes
5. Run type checks: cd packages/flowspace-server && npx tsc --noEmit
6. Commit and push
7. Open a Pull Request

Project Structure Guide

• Adding a new API module — Create a folder in packages/flowspace-server/src/modules/ with *.module.ts, *.controller.ts, *.service.ts, *.dto.ts. Register it in app.module.ts.
• Adding a new page — Create a folder in packages/flowspace-front/src/app/(app)/[workspace]/. Use the flat, edge-to-edge layout pattern (no rounded cards — the canvas handles the rounded container).
• Adding a UI component — Add it to packages/flowspace-ui/src/components/. Export from index.ts.
• Modifying the database — Edit packages/flowspace-server/prisma/schema.prisma, then run npx prisma db push.

Design Guidelines

• The app uses a ClickUp-style canvas layout — sidebar and topbar are the outer frame (dark), main content sits in a rounded panel
• Hover states on the frame use hover:bg-white/[0.07] (not hover:bg-accent)
• Content inside the canvas uses standard Tailwind semantic colors (bg-background, text-foreground, etc.)
• Keep the UI flat and dense — no floating cards with shadows, use borders and separators
• Every interactive element needs a visible hover/focus state

Good First Issues

Look for issues tagged with good first issue — these are scoped and well-documented tasks ideal for new contributors.

---

Self-Hosting

git clone https://github.com/your-username/flowspace.git
cd flowspace
cp .env.example .env
cd packages/flowspace-docker
docker compose up -d

Configure .env with your own secrets, then build and run the server + frontend.

---

License

MIT — see LICENSE for details.

The open source core is MIT licensed. Cloud-specific features (SSO, audit logs, advanced billing) will be under a proprietary license.

---

Built with NestJS · Next.js · Prisma · PostgreSQL · Tailwind CSS