Prestarts

The Prestarts module handles daily safety checklists created by supervisors before each work shift. Prestarts capture shift details, weather forecasts, dynamic custom fields, activities with assigned resources, file attachments, sign-ons, and comments. This is the first “operational data entry” module — building on the custom fields configuration layer.

Lifecycle

Prestarts follow a two-stage lifecycle:

1. Draft — Core fields (supervisor, datetime, duration, shift type, location) are editable. Activities, sign-ons, and comments can be added.
2. Published — Core fields are locked. The briefed activities keep their plan, but their cost code and actual quantity can still change. Activities added after publish can be changed and deleted. Photos and files can still be added (they show as “Added after publish”), but not removed. Comments remain open for ongoing discussion.

Publishing is a one-way transition. Published prestarts will later create linked diary entries automatically.

Draft prestarts can be changed many at once from the list (supervisor, shift, duration, location) — see Bulk Edit & Undo.

Duplicated and new prestarts start at the project’s configured prestart time for the shift (Shift Configuration), falling back to a fixed time when none is set.

Data Model

Enums

Prestarts

Indexes:

• (org_id, project_id, status) WHERE deleted_at IS NULL — list queries with status filter
• (org_id, project_id, supervisor_id) — filter by supervisor
• (project_id, prestart_datetime DESC) WHERE deleted_at IS NULL — chronological listing

Activities

Activities are reusable work items linked to either a prestart or a diary (future). They describe the work to be performed during a shift.

Activity Resources

Many-to-many link between activities and users (workers assigned to the activity).

Unique constraint on (activity_id, user_id).

Prestart Files

Attachments linked to either a prestart or an activity.

CHECK constraint: at least one of prestart_id or activity_id must be set.

Prestart Sign-Ons

Records which workers attended the prestart meeting.

Anyone with company-wide access (for example a Master Admin) can sign themselves on to any project in their organisation, including the office QR sign-on, without being added to the project first.

Unique constraint on (prestart_id, user_id).

Prestart Comments

Discussion threads on prestarts, available to any project member.

Design note: project_id is denormalized on prestart_sign_ons and prestart_comments to enable zero-cost LISTEN/NOTIFY triggers. Without it, the trigger function would need to JOIN through the prestarts table to find the project_id, which is not possible in a simple trigger function.

API Endpoints

All endpoints are under /v1/orgs/{orgId}/projects/{projectId}/.

Prestarts

Activities

Activity Resources

Files

Sign-Ons

Comments

Weather

Architecture

Real-Time Updates

All prestart tables fire LISTEN/NOTIFY triggers on the project_changes channel:

Postgres trigger fires → pg_notify('project_changes', payload)
Go WebSocket hub receives notification → broadcasts to org room
Browser WebSocket client receives message → TanStack Query cache invalidation

The INVALIDATION_MAP in ws-provider.tsx maps table names to query keys:

• prestarts → ["prestarts", orgId, projectId] + ["prestart", orgId, projectId, prestartId]
• activities → ["prestart", orgId, projectId]
• prestart_sign_ons → ["prestart", orgId, projectId]
• prestart_comments → ["prestart-comments", orgId, projectId] + ["prestart", orgId, projectId]

Weather Integration

The weather endpoint proxies the Open Meteo API. Projects must have latitude, longitude, and timezone configured (via the project detail Overview tab) for weather to work. The forecast is stored as JSONB in weather_data on the prestart.

Custom Field Values

Dynamic custom fields (configured at the org/project level) are stored as { "field-def-uuid": value } in the custom_field_values JSONB column on both prestarts and activities. Field definitions come from the custom_field_definitions table with entity_type = 'prestart_diary' or 'activity'.

Security

Tenant Isolation

Every query includes AND org_id = $org_id. The org_id is extracted from the verified session, never from request parameters.

Role-Based Access

Input Validation

• BFF (Next.js): Zod schemas validate all inputs before proxying to Go
• Go API: Struct validation + UUID parsing on all path parameters
• Database: Foreign key constraints, CHECK constraints, NOT NULL constraints

Key Files