WarmDesk - Self-Hosted Project Management

Every project is a board. At creation time you choose between Kanban (columns you define, cards flow freely) and Scrum (same columns but with sprints, a backlog, and story points).

Columns support WIP limits — a visual warning appears when a column holds more cards than the configured maximum. The column ordering is adjusted by dragging; card ordering inside a column is likewise drag-and-drop, persisted immediately through the API.

For Scrum projects a sidebar sprint panel lets you create sprints, drag backlog cards into them, and start or complete a sprint with a click. Completed sprints are retained for historical reference; incomplete cards are returned to the backlog.

Every piece of work lives on a card. Cards support a rich set of metadata:

The card number (PRJ-42) is globally resolvable: typing it in any chat message or comment generates a clickable badge that pops open the card detail.

A per-project Gantt chart visualises cards that have a start date and a due date. The chart is rendered client-side with Frappe Gantt and lets you quickly spot scheduling conflicts and milestones without leaving the application.

Every project has a persistent project chat channel. Members send Markdown-formatted messages, attach files, react with emoji, and @mention colleagues — the mention generates a notification and is highlighted in the recipient’s view.

Cross-project direct messaging is fully supported: start a 1-on-1 conversation with any user, or create a named group chat by selecting multiple participants (or by picking an entire project team). Group chats support a custom avatar, member management (add / remove), and five chat layout options — bubble, comfortable, compact, cozy, and grouped (Discord-style).

Messages support link-preview cards (Open Graph metadata is fetched server-side), emoji picker, and desktop notifications. Messages are delivered over WebSocket; a 5-second polling fallback covers environments where WebSocket is unavailable.

Each project also has a topics board — threaded discussion threads that live alongside the task board. Topics can be pinned, edited, and replied to; they are a good fit for design decisions, meeting notes, or any asynchronous conversation that does not map to a single card.

WarmDesk adds a lightweight CRM layer. Every project belongs to a customer, and customers can have multiple contracts that track start and end dates.

Customer access control is independent of project membership: a user can be granted access to all projects under a customer without being explicitly added to each one. User groups provide the same shortcut at scale — assign a group to a customer or project once, and all group members inherit the role.

Customers can be starred for quick access, filtered in the project dashboard, and viewed with their full project and contract history.

Time entries are recorded against a project and optionally against a specific customer. Each week displays as a grid of date columns and project rows; clicking a cell opens a duration + description entry. Time can also be logged directly on a card comment with a time_spent_minutes value.

The Reports view aggregates entries across any combination of date range, user, customer, and project. Reports export to PDF (rendered via Go’s gofpdf library, or via window.print() with print-specific CSS in the browser) and to XLSX (SheetJS).

An admin panel covers:

Global roles control platform-level access beyond individual projects:

Three complementary mechanisms bridge WarmDesk and source control:

Incoming webhooks — each project can register webhook endpoints for GitHub, GitLab, or Gitea/Forgejo. Push events, pull request events, and issue events are parsed and linked to cards when the payload matches a card reference (PRJ-42). The link appears in the card’s Links tab with status, author, and URL.

Ticket API — a stable X-API-Key-authenticated endpoint allows CI pipelines to create cards, add comments, and move cards between columns without a user session. This is useful for automatically filing a card when a security scan finds a new vulnerability, or for transitioning a card to "Done" when a deployment succeeds.

Webhook receiver for chat — a generic JSON webhook posts a formatted message to the project’s chat channel, enabling simple status notifications from any tool that can make an HTTP POST.

Every user controls their own:

The frontend is a Vue 3 SPA bundled by Vite. In development, Vite’s dev server runs on port 5173 and proxies /api calls to the Go backend on port 8080. In production, the Go binary serves the compiled frontend from the path configured in web_dir.

The backend exposes a REST API under /api/v1/ and two WebSocket endpoints: /api/v1/ws/:projectSlug for project-level events (card updates, chat, presence) and /api/v1/ws/user for user-level events (DM notifications, mentions). All WebSocket state is kept in an in-process hub per project; swapping the hub’s pub/sub layer to Redis enables horizontal deployment across multiple backend instances with no code change.

The Tauri 2 desktop app wraps the same Vue 3 frontend in a native window. It uses the Tauri HTTP plugin to reach a locally running WarmDesk backend, or a remote one over HTTPS.

Handlers follow a strict pattern: parse and validate path parameters, check project membership with services.RequireProjectRole, bind the JSON body, perform the DB operation, broadcast a WebSocket event if needed, return JSON. Every error response uses the same shape: { "error": "human readable message" }.

Pinia stores own all shared state; components only read from stores and dispatch actions. The board.js store is the most complex: it owns columns and cards, applies WebSocket deltas, and handles drag-drop reordering. useWebSocket.js establishes one connection per project view and routes incoming messages to the correct store by type prefix (board., chat., topic., presence.).

AutoMigrate instead of migration files
Every model struct carries GORM tags. On startup the database is opened and AutoMigrate is called for every model. Adding a new column to a feature means adding a field with a gorm:"default:…​" tag — the column appears on the next restart with no manual intervention.

Fractional position ordering
Cards, columns, and projects store their display order as a float64 position rather than an integer index. Inserting a card between positions 1.0 and 2.0 gives it position 1.5 — no bulk re-numbering query is needed. Positions are normalised (renumbered as 1.0, 2.0, 3.0 …) after any reorder API call to prevent precision exhaustion.

Card numbering
Each project has an atomic card_counter column. Creating a card does UPDATE projects SET card_counter = card_counter + 1 and reads the new value — the card gets number KeyPrefix-N without a separate sequence object, keeping the schema compatible with SQLite.

System settings as key-value rows
SMTP credentials, branding, locale defaults, and other admin-controlled settings are stored as rows in the system_settings table. They are read at request time so changes take effect without a restart.

WebSocket fan-out
The in-process hub keeps one Go channel per connected client. When a handler calls ws.BroadcastToProject(projectID, msg), the hub iterates the channel set for that project and delivers the JSON message. When redis_url is configured, publish/subscribe uses Redis channels instead so that multiple backend instances can fan out to all connected clients regardless of which instance they are connected to.

Every project-scoped operation is nested under /api/v1/projects/:projectSlug/. The slug is URL-safe and derived from the project name on creation.

All protected routes require a Bearer <token> header. The access token (15 minutes) is obtained from POST /api/v1/auth/login. The frontend silently refreshes it using the 7-day refresh token; a 401 response triggers a transparent re-authentication cycle.

API keys use X-API-Key: <key> or ?api_key=<key> and are intended for CI/CD pipelines and automation scripts.

Incoming webhooks authenticate via a token embedded in the URL path:

The token is scoped to a single project; the receiver parses the payload, extracts card references, and creates CardLink records.

GET /api/v1/metrics exposes a standard Prometheus scrape endpoint, accessible to users with the metrics or admin global role.

GET /swagger/index.html provides an interactive API browser generated from Go annotations with swaggo/swag.

Open http://localhost:8080, register the first user, and promote them to admin with a direct DB update — or use another admin account once the first admin exists.

The deploy/ directory ships ready-to-use templates:

Add Redis and point multiple instances at the same database:

Each instance runs an independent WebSocket hub; Redis pub/sub bridges them so that a card update from a user connected to instance A is broadcast to users connected to instance B.

The Makefile provides build targets for redistribution:

These wrap the Tauri 2 desktop app, which bundles its own WebView and communicates with a locally running (or remote) WarmDesk backend.