Work Feature Guide

Guide to the Work module — professional work tracking across multiple jobs, each with a type-specific track hierarchy, time-logging sessions, and job-type-specific planning (tickets, milestones, and full store operations).

Overview

The Work module tracks professional work across multiple jobs. Every job has a jobType that determines its entire shape — track hierarchy, planning model, and session fields differ per type:

• SOFTWARE_ENGINEERING — flat projects as tracks, a per-job people roster, and tickets (status, priority, ETA, assignees, checklist tasks) on each project. Sessions require an activityCategory and may optionally link to a ticketId.
• CLIENT_BASED — clients → projects track hierarchy. Project tracks carry metadata (status, ETA, budget, hourly rate, contact, notes) plus milestones. Sessions may be flagged billable.
• STORE — flat areas (all PROJECT tracks), a launch profile, milestones (with a milestoneKind and renewalDate), suppliers, operational tasks (+ recurring templates), inventory (products + stock events), staff shifts, and P&L (finance transactions linked by work_job_id). Sessions require a store activityCategory.

Creating a STORE job with seedLaunchTemplate: true (the default for new store jobs) seeds three areas (Permits, Fit-out, Inventory), permit milestones, and an empty store profile.

Unlike the Android-style feature modules (e.g. Habits, with *_domain/*_data/*_presentation Gradle modules), Work has no separate feature module. It lives in three places: the Ktor server (entities, services, routing), shared KMP (serializable models + an HTTP WorkService + a session-timer repository), and a desktop ViewModel + Compose UI. There is no Android/iOS presentation for Work today.

Architecture

WorkViewModel holds a single WorkState exposed as a StateFlow; it talks to the shared WorkService for REST and to WorkSessionTimerRepository for live timer ticks over the timer WebSocket.

Job Types

Server-side validation enforces these shapes: tickets only on SOFTWARE_ENGINEERING jobs, project tracks must sit under a client track for CLIENT_BASED, milestones on PROJECT tracks for CLIENT_BASED/STORE, all store APIs require jobType == STORE, and store sessions require a store activity category. Violations throw WorkService.WorkValidationException → HTTP 400.

Data Models

Store P&L is not a table — WorkStorePnL is computed from transactions rows whose optional work_job_id FK points at the store job.

Enums

activity_category is persisted as a varchar on work_sessions (it spans both the SE and store enums), not a single DB enum.

API Endpoints

All routes are under /api/v1/work and require auth. The WORK feature flag must be enabled for the requesting client platform (via the X-Platform header). Calendar/date fields on the wire use dd/MM/yyyy (startDate, endDate, etaDate, dueDate, renewalDate, etc.).

Jobs, Tracks, People

Tickets (SOFTWARE_ENGINEERING)

Milestones (CLIENT_BASED / STORE)

Sessions & Stats

Store ops (STORE only — require jobType == STORE)

State Machine

WorkTicketStatus is a free enum on the wire — the server does not enforce transition order, so any status may be set via PATCH /work/tickets/{id}. The diagram shows the intended workflow; the columns of the SE ticket board map directly to these values.

Client Behavior

Each session gets a backing standalone timer created lazily by GET /work/sessions/{id}/timer. WorkSessionTimerRepository maps timer IDs to session IDs and forwards WebSocket TimerUpdate events as sessionTimerUpdates, so the desktop UI shows live elapsed time without polling.

Key Files

Migrations: V10__work_tracking.sql, V12__work_tickets_and_project_management.sql, V13__work_store_phase1.sql, V14__work_store_operations.sql, V15__work_store_inventory_and_finance.sql.

Testing

• Server (import): server/.../service/work/import/WorkTicketImportServiceTest.kt covers spreadsheet preview/commit parsing.
• Validation: assert WorkValidationException → 400 on cross-type misuse — tickets on a non-SE job, store APIs on a non-STORE job, store sessions without a store activityCategory, project tracks not under a client for CLIENT_BASED.
• Store seed: creating a STORE job with seedLaunchTemplate true should create the Permits/Fit-out/Inventory areas, permit milestones, and an empty profile; with it false, none.
• Inventory: verify onHandQuantity math across RECEIVE (+), SALE/WASTE (−), and ADJUST (±) stock events.
• Sessions/stats: complete with actualEnd populates durationMinutes; /work/stats aggregates by track and category and splits billable vs non-billable minutes.

Troubleshooting

Work sidebar entry / endpoints not appearing

• The WORK feature flag must be enabled for the client platform. Locally: UPDATE feature_flags SET enabled = true WHERE feature_key = 'WORK' AND platform = 'DESKTOP';
• Ensure OTER is also enabled for that platform, and that the request sends the correct X-Platform header.

“Tickets are only available for software engineering jobs” / store API 400s

• These are WorkValidationException responses. Tickets require jobType == SOFTWARE_ENGINEERING; all store-* routes require jobType == STORE. Confirm the job’s type before calling.

Milestone creation rejected

• Milestones can only be created on PROJECT tracks of CLIENT_BASED or STORE jobs. Check the target track’s trackKind and the job type.

Store P&L shows zero

• WorkStorePnL is computed from transactions whose work_job_id equals the store job. If no finance transactions are tagged to the job, totals are zero. Confirm Finance entries link via work_job_id and fall within the startDate/endDate range.

Session timer not ticking

• The timer is created lazily on GET /work/sessions/{id}/timer. If the timer WebSocket is disconnected, WorkSessionTimerRepository receives no TimerUpdate events and the UI elapsed time stays frozen — verify the WebSocket connection and that the user is authenticated (TokenStorage).

Dates parsing incorrectly

• All calendar fields use dd/MM/yyyy. Sending ISO (yyyy-MM-dd) will fail server-side parsing.

Related Docs

• Finance — transactions and the work_job_id link that powers store P&L
• Timers — standalone timer model and WebSocket updates reused by work sessions
• Habits — reference for the standard feature-module layout Work intentionally diverges from
• Domain & models — shared domain model reference
• UI & UX — desktop hub navigation patterns
• Testing & QA — testing strategy