This is an experimenal preview. If anything broke - ask your cli agent to fix or contact me. Any feedback is alos welcomed
OpenWork is a workspace platform with boards, cards, folders, unified inbox, Telegram integration, AI agents, and webhook automation.
Tech stack: Fastify 5, PostgreSQL (Drizzle ORM), React 19, Vite, TypeScript, Zod v4, pnpm workspaces.
- Node.js 20+
- pnpm 9+
git clone <repo-url> && cd openwork
pnpm installcp .env.example .env
cp packages/backend/.env.example packages/backend/.envRequires a running Postgres instance and DATABASE_URL in packages/backend/.env.
pnpm db:bootstrapApplies migrations and seeds default workspace records for a fresh environment: admin and starter users, project settings, the general collection, the auto-dev-cards board, and the default workspace. See Bootstrap Data for details.
pnpm certs:generatepnpm dev- Frontend: https://localhost:5173
- Landing: http://localhost:5319
- Backend API: http://localhost:3847
- Swagger docs: http://localhost:3847/docs
packages/
backend/ Fastify API server, PostgreSQL data store
frontend/ React 19 SPA, Vite, React Router
landing/ Public OpenWork landing page
shared/ Shared TypeScript types
widget/ Embeddable web form & chat widgets
scripts/ Dev utility scripts (certs, stale process check — see docs/RUNBOOK.md)
docs/ Design system and developer guides
REST API server handling all workspace logic. Built with Fastify 5 and fastify-type-provider-zod, uses PostgreSQL with Drizzle ORM for relational data.
Key areas:
- 21 route files — auth, cards, boards, folders, tags, conversations, messages, agents, agent chat, connectors, Telegram, webhooks, media, storage, API keys, permissions, audit logs, backups, message drafts, health, and widget
- 23 services — agents & agent chat, Telegram bot/webhook/outbound, webhook delivery, event bus, backup, storage, connectors, audit logging, TOTP 2FA, and core CRUD for cards, boards, folders, conversations, messages, tags
- 20 data collections — users, cards, boards, folders, tags, conversations, messages, connectors, Telegram bots, webhooks, API keys, audit logs, message drafts, and more
- Security — JWT auth with refresh tokens, API key scoped permissions, 2FA (TOTP), rate limiting, audit logging
React 19 single-page application. All pages are lazy-loaded via React Router for code splitting.
Key areas:
- Pages — Dashboard, Boards (list/detail), Cards (detail), Folders (list/detail), Inbox, Agents, Connectors, Storage, Settings (API keys, backups), Auth (login/register/2FA)
- State — React Context for auth, custom hooks for data fetching
- API client (
src/lib/api.ts) — centralized fetch wrapper with JWT auto-refresh on 401
TypeScript type definitions shared between backend and frontend: permission types and auth interfaces.
Standalone JavaScript widgets embedded on external websites via a <script> tag. Built as IIFE bundles with no dependencies, rendered inside Shadow DOM for style isolation.
Two widgets:
ws-form.js— embeddable web form. Fetches form config from the backend by ID, renders fields dynamically, submits data back. Auto-initializes fromdata-ws-form/data-ws-api-urlHTML attributes, or viaWsForm.init().ws-chat.js— embedded chat widget for real-time conversations with visitors.
Usage example:
<div data-ws-form="FORM_ID" data-ws-api-url="https://your-api.example.com"></div>
<script src="https://your-cdn.example.com/ws-form.js"></script>generate-certs.sh— generates local HTTPS certificates via mkcert intocerts/. Run withpnpm certs:generate.
| Command | Description |
|---|---|
pnpm dev |
Start all dev servers in parallel |
pnpm dev:backend |
Start backend only |
pnpm dev:frontend |
Start frontend only |
pnpm dev:landing |
Start landing page only |
pnpm build |
Build all packages |
pnpm lint |
Lint all packages |
pnpm typecheck |
Type-check all packages |
pnpm docker:full |
Start everything in Docker |
pnpm docker:full:stop |
Stop Docker containers |
pnpm docker:down |
Stop and remove Docker containers |
pnpm db:bootstrap |
Bootstrap backend SQL data for a fresh environment |
pnpm certs:generate |
Generate local HTTPS certs via mkcert |
- Cards & Folders — organize work items with tags and links
- Boards — Kanban-style boards with customizable columns
- Unified Inbox — all conversations in one place
- Telegram — workspace-managed bot setup, media support, webhook handling
- AI Agents — configurable agents with preset system, file workspaces, and chat interface
- Connectors — external service integrations
- Embeddable Widgets — web forms and chat widgets for external sites
- Webhooks — webhook subscriptions with delivery tracking
- Storage — file upload and media management
- Security — JWT auth, API key scoped permissions, 2FA (TOTP), rate limiting, audit logging, backups
Run pnpm db:bootstrap from the repo root, or cd packages/backend && pnpm db:bootstrap, to initialize a fresh backend database.
Test accounts:
| Password | |
|---|---|
admin@openwork.local |
admin123 |
manager@openwork.local |
manager123 |
agent1@openwork.local |
agent123 |
cp .env.example .env
pnpm docker:fullSee packages/backend/.env.example for all backend config.
OpenWork can provide the Telegram bot for the workspace so end users do not need to create one in BotFather.
- Set
TELEGRAM_MANAGED_BOT_TOKENinpackages/backend/.env. - Set
TELEGRAM_WEBHOOK_BASE_URLor use ngrok from the Connectors admin UI. - In the app, open
Connectorsand add Telegram using the recommended managed-bot option.
If you prefer, admins can still connect a custom Telegram bot manually.
All project guidelines live in docs/:
docs/backend-development.md— backend code authoring (routes, services, error handling)docs/design-system.md— colors, typography, components, layout, animations
Private.