Projects

The Projects module is the core domain model for Lacroo Pro. It manages the full lifecycle of construction projects within an organization — creation, configuration, stage tracking, member assignment, and archival. Projects serve as the parent entity for future modules (Diaries, Prestarts, Reports).

Data Model

Business Units

Org-level lookup table for grouping projects. Supports soft-delete (archive).

Projects

Timezone

A project’s timezone decides which calendar day its sign-ons, prestarts, photos and roll calls fall on, and every date and time on the project shows in it (see Dates & Times). It comes from where the project is, and only the server sets it:

1. The map pin decides.
2. Otherwise the address decides: an Australian state or territory (QLD Australia/Brisbane, NSW and ACT Australia/Sydney, VIC Australia/Melbourne, TAS Australia/Hobart, SA Australia/Adelaide, NT Australia/Darwin, WA Australia/Perth), or New Zealand (Pacific/Auckland).
3. A project with no location gets Australia/Sydney. Organisations have no zone setting of their own.

The create and save requests carry no zone. A zone a client still sends is ignored. The web and mobile apps do not work one out.

A save keeps the project’s zone, unless the project has none yet or the save moves it into a different zone. A move means the zone of the location changed. Rewording the address with the pin unchanged is not a move. A blank zone is never stored. The rule lives in one Go package, backend/pkg/projecttz (Resolve, ForSave, FromSite).

Project Stages

Append-only contract stage records. No edit or delete operations are exposed — stages form an immutable audit trail.

Project Members

Many-to-many relationship between projects and users. Access control is determined by the user’s org-level role.

Members and Field Users

Every project member is either office staff or a field user, never both. The rule is one SQL function, project_member_role(user_id, home_org_id, project_id): a person is a field user when their role on the project (the role set for them there, otherwise their company-wide role) carries the mobile_field or mobile_supplier avenue. The supplier master admin is never a field user, and a person with no role is office staff.

The project Members tab lists office staff only (GET .../members?exclude_field_users=true), and its Add Member offers only office people and office roles. Field users are added and managed on the Field Users tab. Without the parameter the endpoint still returns everyone, because muster, prestarts and the mobile pickers need the field users too. | updated_at | TIMESTAMPTZ | Auto-updated via trigger |

Unique constraint on (project_id, user_id) prevents duplicate assignments.

Custom Field Definitions

Configurable field templates for diaries, prestarts, and activities. Uses a copy-on-inherit model: org-level templates (project_id = NULL) are auto-copied to projects on creation. See Custom Fields for full documentation.

Enums

• project_status: live, archived
• custom_field_entity: prestart_diary, activity
• custom_field_type: text, textarea, number, checkbox, dropdown, radio, multiselect, date, time, file

API Endpoints

Projects

Stages

Members

Business Units

Custom Fields (Org Templates)

Custom Fields (Project-Level)

Users & Entra

WebSocket

Architecture

Role-Based Access Control

Admin roles (master_admin, organisational_manager) can create, update, delete projects, manage members, and manage business units. Non-admin users can only view projects they are assigned to as members.

Real-Time Updates

Project changes propagate in real-time via Postgres LISTEN/NOTIFY:

Database 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

Triggers fire on INSERT, UPDATE, and DELETE for projects, project_members, project_stages, and custom_field_definitions tables. Payload contains table, action, org_id, and project_id.

BFF Pattern

All data access flows through the BFF (Next.js Server Actions):

Browser (TanStack Query) → Server Action (Zod validation) → Go API (business logic + DB)

The browser never calls the Go API directly (except for the WebSocket connection). Server Actions validate inputs with Zod, authenticate via session validation, and call the Go API with a short-lived JWT.

Security

• Tenant isolation — Every query includes AND org_id = $N. Handlers verify JWT org_id matches the URL {orgId} parameter. Non-admins additionally require project membership.
• Role-based mutations — Create, update, delete, and member management restricted to master_admin and organisational_manager roles.
• Double input validation — Zod schemas in the BFF layer + Go struct validation with length limits and format checks.
• Soft deletes — Projects, business units, and custom fields use deleted_at timestamps. No hard deletes.
• Append-only stages — Project stages cannot be edited or deleted once created.
• Unique constraints — Business unit names unique per org (active only). Project member assignments unique per (project, user).
• COALESCE updates — Partial project updates use COALESCE(sqlc.narg(...), existing) to prevent overwriting fields not included in the request.
• Membership check — Non-admin project detail access requires IsUserProjectMember verification.
• Entra integration — Client secrets decrypted only during API calls, never logged or returned to the frontend.
• WebSocket auth — Connections require valid BearerAuth JWT. Clients are scoped to their org room.

Key Files