Projects & Sites¶

Status: Specified — ready to build Build order: 1 of 10 — foundational module, no upstream dependencies

Purpose¶

Projects and Sites are the root entities of the platform. Every other module attaches to a Site. A Project is the contract or programme of work; a Site is the physical location where work takes place within that project.

A project can have many sites. A highway scheme might have three sites running simultaneously — each with its own site diary, headcount, and plant allocation — all under one project.

Entities¶

Project¶

Represents a contract or body of work. Top-level organisational unit.

CREATE UNIQUE INDEX idx_projects_reference
    ON projects(reference) WHERE deleted_at IS NULL;
CREATE INDEX idx_projects_status
    ON projects(status) WHERE deleted_at IS NULL;
CREATE INDEX idx_projects_created_by ON projects(created_by);

Site¶

Physical location where work takes place. Belongs to a Project.

CREATE INDEX idx_sites_project_id
    ON sites(project_id) WHERE deleted_at IS NULL;
CREATE INDEX idx_sites_status
    ON sites(status) WHERE deleted_at IS NULL;
CREATE INDEX idx_sites_site_manager
    ON sites(site_manager_id) WHERE deleted_at IS NULL;

Project Assignments¶

Controls which users can access which projects. Rows here are mirrored into public.user_project_access (see ADR-003); that table is the runtime source of truth for access checks, not the JWT.

CREATE UNIQUE INDEX idx_project_assignments_unique
    ON project_assignments(project_id, user_id);
CREATE INDEX idx_project_assignments_user
    ON project_assignments(user_id);
CREATE INDEX idx_project_assignments_project
    ON project_assignments(project_id);

Tenant Admins have implicit access to all projects — no row required.

Status Lifecycles¶

Project¶

Site¶

Sites have no tender status — created when work is confirmed.

Business Rules¶

1. reference is unique within the tenant. Enforced at DB level (partial unique index) and validated in the service layer before the constraint fires.

2. Soft deleting a project soft-deletes all its sites in the same transaction. Service layer, not DB cascade.

3. A site cannot be set to active if its parent project is archived or completed.

4. A site can be on_hold while its project is active. One work front can pause without pausing the whole project.

5. If latitude is provided, longitude is required and vice versa. Pydantic validator.

6. Contract value stored in tenant home currency. No multi-currency in V1.

7. Status transition reason is written to the audit log, not stored on the record.

8. actual_end_date is set automatically when a project transitions to completed, if not already provided in the transition request.

9. All DATE fields in modules scoped to this site (e.g. entry_date in Site Diary, expiry comparisons in Plant & Equipment, Documents) are evaluated in the site's timezone. The API accepts and returns datetimes in UTC; application-layer code converts for date-boundary logic using the site's IANA timezone identifier. Sites in the UK default to Europe/London, which observes BST, ensuring that midnight-boundary comparisons produce the correct calendar date year-round.

API Endpoints¶

Projects¶

Sites¶

Request / Response Shapes¶

POST /projects¶

// Request
{
  "name": "A417 Missing Link — Phase 3",
  "reference": "PRJ-2025-001",
  "client_name": "National Highways",
  "contract_type": "NEC4",
  "contract_value": 4250000.00,
  "start_date": "2025-06-01",
  "end_date": "2027-03-31",
  "region": "South West",
  "custom_fields": {}
}

// Response 201
{
  "id": "a1b2c3d4-...",
  "name": "A417 Missing Link — Phase 3",
  "reference": "PRJ-2025-001",
  "status": "active",
  "client_name": "National Highways",
  "contract_type": "NEC4",
  "contract_value": 4250000.00,
  "start_date": "2025-06-01",
  "end_date": "2027-03-31",
  "actual_end_date": null,
  "region": "South West",
  "description": null,
  "site_count": 0,
  "custom_fields": {},
  "created_at": "2025-05-27T09:00:00Z",
  "updated_at": "2025-05-27T09:00:00Z",
  "created_by": "user-uuid"
}

GET /projects¶

Query params: status, q, sort (default -created_at), limit (default 20, max 100), cursor

// Response 200
{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "name": "A417 Missing Link — Phase 3",
      "reference": "PRJ-2025-001",
      "status": "active",
      "client_name": "National Highways",
      "start_date": "2025-06-01",
      "end_date": "2027-03-31",
      "site_count": 3,
      "created_at": "2025-05-27T09:00:00Z"
    }
  ],
  "pagination": {
    "total": 12,
    "cursor": "eyJpZCI6Ii4uLiJ9",
    "has_more": false
  }
}

List returns summary shape. contract_value and description on detail only.

POST /projects/{id}/transition¶

// Request
{ "status": "on_hold", "reason": "Client instructed pause" }

// Response 200 — full project object
// Response 409 — invalid transition
{ "error": "conflict", "message": "Cannot transition from completed to on_hold" }

POST /sites¶

// Request
{
  "project_id": "a1b2c3d4-...",
  "name": "Zone A — Earthworks",
  "reference": "SITE-A",
  "address_line_1": "A417, Cowley",
  "postcode": "GL53 9NX",
  "latitude": 51.8279,
  "longitude": -2.0123,
  "what3words": "filled.count.soap",
  "site_manager_id": "user-uuid",
  "start_date": "2025-06-01",
  "end_date": "2026-09-30",
  "custom_fields": {}
}
// Response 201 — full site object

POST /projects/{id}/assignments¶

// Request
{ "user_id": "user-uuid", "role": "project_manager" }

// Response 201
{
  "project_id": "a1b2c3d4-...",
  "user_id": "user-uuid",
  "role": "project_manager",
  "created_at": "2025-05-27T09:00:00Z"
}

Permission Matrix¶

"Own site" = sites where site_manager_id = current_user.id.

Offline Sync Scope¶

Site Manager syncs only sites where site_manager_id = their user ID or where they have an explicit project assignment row.

Cross-Module Dependencies¶

No upstream dependencies. This module must be built first.

project_id and site_id are foreign keys in every other module:

project_access in the JWT is populated from project_assignments. All downstream permission checks derive from project access.

Tests Required¶

Standard¶

• Create project — valid payload → 201
• Create project — duplicate reference → 409
• Create project — missing required field → 422
• List projects — pagination works correctly
• List projects — filter by status
• List projects — search by name and reference
• Get project — full detail fields present
• Get project — contract_value present for Project Manager, absent for Site Manager
• Update project — PATCH semantics (partial update, unspecified fields unchanged)
• Delete project — soft deletes project and all child sites in one transaction
• Status transitions — all valid transitions → 200
• Status transitions — all invalid transitions → 409
• actual_end_date auto-set on transition to completed
• Assignment create, list, delete

Cross-tenant isolation (mandatory)¶

• GET /projects/{id} where id belongs to another tenant → 404
• POST /sites with project_id from another tenant → 404
• POST /projects/{id}/assignments with user from another tenant → 422

Permission boundaries¶

• Site Manager cannot create a project → 403
• Site Manager cannot see contract_value — field absent from response
• Site Manager can edit their own site
• Site Manager cannot edit a site they are not assigned to → 403
• Viewer cannot edit anything → 403

Default Tenant Labels¶

Foundation Dependencies¶

This module cannot be built until the following foundation components exist and are verified: