Janosik

Janosik

A self-hosted Kanban board for teams and AI agents. Server mode provides accounts, shared boards and realtime sync. The UI and API share one pure reducer and a command log; the installable PWA can reopen cached pages offline.

Janosik runs in server mode in development and production. The UI applies edits optimistically, then sends them to the API as commands (POST /boards/:id/commands); the UI and API use the same boardReducer. Unit tests can exercise the reducer without an API. The PWA caches its app shell and assets, so previously loaded pages can reopen offline, but saving changes requires a server connection. Realtime updates use SSE and resume from ?since= after a dropped connection. See ROADMAP.md §7 for the architecture history.

Repository layout — the workspaces

This is an npm workspaces monorepo with one root lockfile. ui, shared and backend make up the application; brand, site, video and mcp support its design system, website, media and agent integrations; e2e holds browser-test infrastructure. Install dependencies once with npm install from the repository root.

Why shared matters: a board mutation is written once (in the reducer), executed in the browser for instant feedback and on the server when the command arrives — so a card can never move differently in the UI and in the database. The same applies to validation and to DTO types: change a field in shared/src/admin.ts and both sides fail to compile until they agree.

janosik/                        # npm workspaces root (one package-lock.json)

├─ ui/ # @janosik/ui — the React PWA (see tree below) ├─ shared/ # @janosik/shared — the domain library │ └─ src/ │ ├─ types/kanban.ts # Board / Column / Card / Label + LIMITS │ ├─ store/ │ │ ├─ board-reducer.ts # the pure reducer — every board action │ │ ├─ invert.ts # inverse actions for undo/redo │ │ ├─ validate.ts # strict command validator (both sides) │ │ ├─ migrate.ts # persisted-state migrations │ │ └─ seed-data.ts # demo "Product Launch" board │ ├─ utils/ # export/import envelope, limits, text, storage keys │ ├─ api.ts # user API DTOs (auth, boards, commands…) │ └─ admin.ts # admin API DTOs (users, boards, cards, masters…) ├─ backend/ # @janosik/backend — the NestJS API │ ├─ prisma/ # schema.prisma + versioned migrations │ ├─ src/ # auth/ boards/ commands/ comments/ activity/ │ │ # admin/ users/ health/ config/ (+ shared → ../../shared/src) │ ├─ test/ # Jest + Supertest e2e specs (real test DB) │ ├─ scripts/ # admin-cli.cjs, migrate-test-db.cjs │ ├─ docker-compose.yml # dev PostgreSQL 16 (janosik + janosik_test) │ └─ .env.example ├─ brand/ # @janosik/brand — shared brand assets and tokens ├─ site/ # @janosik/site — marketing site and documentation ├─ video/ # @janosik/video — product demo clips ├─ mcp/ # @janosik/mcp — the MCP server: the board as agent tools │ ├─ src/ # client + 13 tool groups (71 tools), toolset gating │ ├─ server.json # MCP Registry metadata (published as io.github.vitalytolstik/janosik) │ └─ scripts/smoke.mjs # live smoke test against a running instance ├─ skills/janosik/ # workflow guidance for AI agents using the MCP tools │ ├─ SKILL.md # the instructions a harness loads │ └─ references/ # card/comment templates + lifecycle recipes ├─ deploy/nginx.conf # optional SPA fallback + /api proxy (single-image serving is built in) ├─ Dockerfile # multi-stage: builds UI + API into one self-host image ├─ docker-compose.yml # self-host stack: app + postgres + redis ├─ docker-entrypoint.sh # runs prisma migrate deploy, then the API ├─ .env.example # annotated environment for docker compose ├─ SECURITY.md / CHANGELOG.md # disclosure policy, release history ├─ LICENSE / TRADEMARK.md # AGPL-3.0 terms + brand/trademark policy ├─ docs/SELF-HOSTING.md # full self-hosting guide (TLS, backups, ops) ├─ docs/INSTALL-BY-OS.md # running it on macOS / Windows 11 / Linux ├─ ROADMAP.md # project priorities, architecture decisions and task status ├─ ROADMAP-DONE.md # archive of closed tasks └─ AGENT.md # working agreement for AI agents/contributors

Highlights

• Four board views — Kanban, Calendar (drag deadlines, "unscheduled" panel, week/month, day panel), Table (sorting, inline editing, configurable columns) and Watch (a read-only status view with a live activity feed and 20/50/100-item pages).
• Card density — a Simplify design toggle switches every card to a compact one-line tile (title, label dots, blocked marker, checklist progress, priority and assignee) with far fewer elements; the full face stays one click away in the card dialog.
• Drag & drop — move cards within/between columns and reorder columns (@dnd-kit), inline Trello-style "+" zones, keyboard sensor and drag overlay.
• Rich card content — WYSIWYG description (MDXEditor) that is the card's document (up to 64k characters), checklists with progress badges (items up to 500 characters), due dates with overdue/soon badges, color/gradient covers, 14-color labels, and a read-only machine-readable acceptance-criteria / definition-of-done contract.
• Attachments — paste files into descriptions or add them directly; description uploads follow edits and undo/redo. Video uploads can be processed in the background for browser playback; see the card guide for limits and retention.
• Card & board archive — Trello-style archiving with restore (WIP-aware) and permanent delete; board archive with restore.
• Multi-boards — switcher, create/rename/archive/delete, deep links /board/:id, global search across boards with snippets.
• Search & filters — by title/description/labels, label ANY/ALL matching, due status, creation date; hotkeys / and Ctrl/Cmd+K, match counter.
• WIP limits — per-column caps with counters, blocked composers/drags and toasts.
• Activity feed — per-card event history covering every board action, with relative timestamps and an "Agent" badge on entries an agent's API token caused.
• Keyboard-first — shortcut palette (?), j/k cursor navigation, n/c composers, e/Enter edit.
• Undo / redo — 50-step history with coalescing, Ctrl/Cmd+Z, Ctrl/Cmd+Shift+Z, Ctrl+Y, header buttons.
• PWA — installable (manifest + icons). The service worker caches the app shell and hashed assets, so previously loaded pages can reopen offline. Writes still need the API: if it is unreachable, an optimistic edit rolls back with a message. There is no persistent outbox yet, so reloading discards unsynced changes; previously loaded data remains available offline.
• Server mode — sign in to work with boards stored in PostgreSQL. The UI applies edits optimistically and sends each one through the command log (POST /boards/:id/commands); rejected edits roll back with a message. Per-entity version checks protect typed text from a stale undo. A request already in flight can finish during a reload. The no-API local-only mode is used by unit tests; development and production builds require the API.
• Realtime — a GET /boards/:id/events SSE stream carries every committed command ({type, seq, action, actorId}) and the client replays foreign actions through the very same reducer. Edits appear in other browsers with no reload; a dropped stream resumes exactly where it stopped (?since=) and window focus remains the fallback. Your own commands are never applied twice, and a stale undo still refuses to clobber someone else's text.
• Shared boards — a Members (N) dialog in the header: admins invite by email, switch roles (ADMIN/MEMBER/VIEWER), bound a viewer's access with an expiry date ("access expired" badge) and remove members — the last admin can never be demoted or removed. Invitations are opt-in: the invitee gets a badge on the header bell and accepts or declines there; nothing is shared until they accept. Everyone else sees the same member list read-only, and a VIEWER gets a genuinely read-only board: no drag, no composers, no menus, no inline editors, a read-only card dialog — while the server independently answers 403 to every mutation.
• Master panel — a separate /admin area for the platform operator: metrics, all users and boards, command log, audit trail and moderation (block a user and their sessions die instantly, revoke API tokens, archive/soft-delete a board, create accounts with a one-time password). Master accounts live outside the user table,