A full-stack project management and collaboration platform: organizations, projects, a Kanban board, tasks with subtasks/labels/comments/attachments, notifications, and real-time updates over WebSockets.
For the full architecture and data model, read the
Architecture Essentials doc
in AGENT-DOCS/ before making non-trivial changes.
- Frontend (
/): Astro + React + TypeScript, styled with a hand-built CSS design system (src/global.css) instead of Tailwind. - Backend (
server/): Express REST API, layered routes → controllers → services → repositories. - Database: SQLite (via
better-sqlite3), foreign keys enabled. - Real-time: a WebSocket server for push updates only; regular CRUD always goes through the REST API.
In local development this is a two-process app: the Astro frontend and the Express API run and are developed independently, communicating only over HTTP/WebSocket. The frontend never touches SQLite directly. In production the two are merged into one process on one port — see Production build.
- Node 24
- pnpm (installing with anything else is blocked by a
preinstallhook)
This repo is a pnpm workspace containing the root Astro app and server/.
A single install at the root pulls in both:
pnpm installCopy the env templates and adjust values if needed (the defaults work for local development):
cp .env.example .env
cp server/.env.example server/.envCreate the SQLite database and run migrations:
pnpm --filter server migrateOptionally seed it with demo organizations, projects, tasks, and user accounts (the seed script prints the demo login credentials when it finishes):
pnpm --filter server seedBoth processes need to be running. In two separate terminals:
pnpm --filter server dev # API on http://localhost:4000
pnpm dev # frontend on http://localhost:4321Then visit http://localhost:4321.
pnpm test # frontend tests (vitest)
pnpm --filter server test # backend tests (vitest)
pnpm lint # eslint
pnpm format # prettier --write
pnpm typecheck # astro checkThe deploy target expects one process on one port, not the two dev uses.
server/src/prod.ts mounts the built Astro app into the same Express app
the API already runs, using @astrojs/node's "middleware" adapter mode
(astro.config.mjs) rather than Astro's own standalone server:
pnpm build # astro build -> dist/
pnpm --filter server build # tsc -> server/dist/
pnpm --filter server migrate # or: node server/dist/db/migrate.js
PORT=3000 node server/dist/prod.jsThen visit http://localhost:3000 — both the API (/api/v1/...) and every
page are served from that one port. See the Dockerfile for the full
multi-stage build used to produce the deployed image.
src/: Astro pages/layouts and React feature components (src/features/<feature>/{api,types,components}).server/src/: Express app:routes/→controllers/→services/→repositories/, plusmodels/,middleware/,websocket/.server/db/migrations/: versioned SQL migrations, run viapnpm --filter server migrate.AGENT-DOCS/: architecture, PRD, and planning docs.