The Admin module is the operational heart of each tenant business. An admin or staff user logs in and operates entirely within their own business scope. No cross-tenant data access is possible — every query is filtered by the business_id resolved from the authenticated user's record.

The admin controller uses AuthorizesEngineeringAccess concern which provides rejectUnlessBusinessPortal() — this checks user_type IN (admin, staff) — and rejectUnlessPermission() for per-resource checks.

Admin and staff users authenticate via the same POST /api/login endpoint as all other roles. After login, the user_type field in the response determines which portal the mobile/web app should route to.

Before a business can run projects, reference data must be configured. The correct setup order avoids foreign key issues and ensures dropdowns are populated in the mobile app.

A project is the primary entity in the Admin module. It moves through a status lifecycle from draft through completion. All financial, scheduling, and people records are linked to a project_id.

Project relationships:

A Proposal is a price quotation attached to a project. The current_round field tracks how many revision rounds have occurred. Multiple proposals can exist per project, supporting re-quoting after scope changes.

Phases are the building blocks of a project timeline. Each phase has a phase_key that references the Phase Library, a progress_percent (0–100), and lifecycle status.

The project's current_phase_key field is updated manually or automatically when a phase reaches 100%.

Phase Library: Stores default_duration_days which apps use to pre-fill planned_start/planned_end when a phase is added from a template. The library is business-scoped — businesses build their own phase vocabulary.

The Admin module has four interlocking financial objects. Understanding their relationships prevents double-counting and ensures the ledger reflects reality.

Voucher → Ledger flow

The Admin module manages two types of people: Staff (employees on the admin's payroll) and Subcontractors (external companies). Both are business-scoped.

Staff

Staff records live in StaffProfile and link to a user_id in the users table. The user gets user_type=staff and can log in to the Admin portal with their assigned permissions.

Subcontractors

Subcontractors represent external companies. They can optionally have a linked user_id for Contractor portal access. Without a user_id they exist as data records only (for vouchers and ledger references).

Calendar events are the scheduling backbone. They link to a project and optionally to an assigned user. The upcoming_event_count on the dashboard reflects events with starts_at > now().

Project documents are categorised by document_type_id, linking to the Document Types reference table. Documents with requires_approval: true must be reviewed before being visible to clients.

Signature Settings

The SignatureSetting record stores the digital signature used on vouchers and certificates. One record per business (user_id = 0 for the business default). Apps render this signature image on generated PDF documents.

The Roles system allows the business admin to define custom permission sets and assign them to staff members. The admin role has all permissions by default and cannot be restricted.

Full list of all permission slugs in the Admin module. Admin users have all permissions implicitly. Staff users must be assigned a role that includes the required slug.

Validation error shape (422):