System Architecture & Role-Based Access Documentation

Sheet 01 / Purpose & scope

Organisational hierarchy

The system is built around a fixed three-level hierarchy. It is not a one-project-at-a-time system: at any point Sarjan may have Project A (with Site 1 and Site 2 active) and Project B (with Site 3 active) running side by side, each with its own team, fund and HR data — all visible to Head Office at once.

Concrete example

Every project and every site in this tree can be active simultaneously — nothing here is a "current project" you switch into.

Example structure (as agreed with client)

Sheet 02 / Section 3

Core structural principles

Four rules, confirmed with the client, are enforced at the data-model level rather than left to process discipline alone.

Sheet 03 / Section 4.1

Head Office roles — fixed

Roles fall into three tiers: HO roles (centrally controlled, company-wide), Site roles (dynamic, created per site) and the External role. HO roles are centrally defined; multiple users may be assigned to the same HO role.

Sheet 04 / Section 4.2

Site roles — dynamic, created per site

This is the role list already agreed with the client. The Project Manager / Site In-charge creates and names Site roles according to the approved site structure and scale — but every role, however named, is linked to one of the fixed permission templates in Sheet 06. The 13 roles below are the confirmed baseline set.

Sheet 05 / Section 4.3

External role

Subcontractor-side access, deliberately limited to submission — nothing is approved on the external side of the boundary.

Sheet 06 / Section 4.4

Permission template model — how "dynamic" stays safe

Free-text role creation without an underlying permission structure would mean every new role needs custom code, which defeats the purpose of "dynamic." Instead, every role — fixed or PM-created — must be linked to one of a small, fixed set of permission templates. The Project Manager picks a template when naming a new role for their site; the template — not the role name — is what the system enforces.

Sheet 07 / Section 5 + HR working sheet

HR & payroll architecture

HR and payroll are built around three worker categories, each with a different employer-of-record, pay cycle and attendance owner — this is what makes multi-site labour management workable at scale.

5.1 Pay cycle

5.2 Site working hours & compliance rules

• Standard site day: 9 hours on site including 1 hour rest — 8 working hours. Default 08:00–17:00, adjustable per site by the Project Manager with Head–Projects approval.
• Weekly off: Sundays are half day, approval needed by Project Manager.
• Ordinary working week capped at 48 hours; time beyond that is overtime, compensated as paid leave with Project Manager approval.
• Night shift runs only with written Project Manager approval, an HSE clearance and certified lighting levels.
• No person below 18 years of age is permitted on site under any category, for any reason — including as a helper or a family member of a worker.
• Geo-fencing is applied at site level for attendance validation.

5.3 Leave entitlements

From the HR working sheet — not yet carried into the Client Review v2 architecture doc, included here for completeness.

Also from the working sheet: Site staff receive a quarterly evaluation by the Project Manager, with the report submitted to HR.

Sheet 08 / Section 6

Module architecture

Twelve functional modules, each scoped to Head Office, Site, or both. This is the "which module, who owns it" map — cross-referenced against the role directory in Sheets 03–05.

Sheet 09 / Section 7

Core data model

Key entities and how they're scoped in the hierarchy. This is the backbone that makes fund isolation, employee locking and per-site HR possible — every transactional entity carries a site_id (and, through it, a project_id and company_id), and access is filtered by that chain.

Sheet 10 / Section 8

Multi-project & multi-site concurrency model

Because several projects and several sites are active at once, the system is designed around scoped access and roll-up reporting rather than a single "current project" context.

• ①

  Every transactional record carries its site_id at creation. There is no global/shared transaction table — isolation is structural, not a filter applied after the fact.

• ②

  A user's Home/HR context is their assigned Site (or, for HO roles, the whole company). Site-level users operate within explicitly authorized Site assignments — there is no unrestricted Site switching.

• ③

  A shared functional Site role (e.g. QA/QC Engineer or Site Accountant may cover 2 Sites, or Plant & Machinery In-charge may be shared) retains one Home/HR Site and receives separate, explicit Site role assignments for each additional Site. Each assignment is independently approved, scoped and revocable.

• ④

  Head Office dashboards query across all active projects and sites in real time — consolidated cash flow, consolidated HR headcount, consolidated PO/expense status — without any project needing to be "closed" or "selected" first.

• ⑤

  Document numbering (PO, MRR, expense voucher, muster) is scoped per site with its own sequence, so two sites can issue "PO-001" on the same day without collision; the full reference includes the site code.

Sheet 11 / Section 9

Access control matrix (indicative)

Illustrative matrix. Final limits (approval bands, override rights) are confirmed in the open decisions list — this is a snapshot of who touches what, not the finished RBAC configuration.

Matrix is indicative. Final permissions, approval bands and role templates are governed by the approved RBAC configuration and client approval matrix.

Sheet 12 / Synthesis

Company → Site, step by step

Pulling every sheet above into one sequence — how a company-level decision turns into work happening on the ground at a site, and how it rolls back up again.

1. Company is the root

   Sarjan exists as a single legal entity. All policy, fund release authority and master data control sit at Head Office. HO roles (MD, the Heads, the Managers, the ERP Administrator) are fixed and company-wide — Sheet 03.

2. HO opens a Project

   A Project represents a contract or client engagement. Many projects run concurrently; each gets a Project Manager. This is Module M-02, jointly owned by HO and Site.

3. The Project spins up one or more Sites

   Each Site is a physical work location with its own site_id, chained to its project_id and company_id. A project can run many sites in parallel — none of them need the others to be "closed."

4. The PM / Site In-charge defines Site roles

   Roles are created and named for that site's scale — not hardcoded. Every role, whatever it's called, is linked to one of the seven fixed permission templates from Sheet 06, which is what the system actually enforces.

5. People are onboarded and locked to that Site

   Employees get exactly one active site assignment — Category A staff, Category B direct labour, or Category C subcontractor labour, each with its own attendance owner and pay cycle (Sheet 07). There's no "reassign"; a real move is relieve-and-onboard.

6. HO allocates funds to the Site

   A site-scoped fund ledger opens. Money only ever moves HO → Site or Site → HO — never site to site. If two sites need funds, HO makes two separate allocations (Sheet 02, 3.1).

7. The Site team executes and records

   Indents, daily progress, stock movements, muster, quality checks and safety inspections all flow through the modules scoped to that site — M-05 through M-11 — each tagged with the site's own document sequence, so "PO-001" at Site 1 never collides with "PO-001" at Site 3.

8. Approvals move through the RBAC matrix

   Site approvers (PM, Senior Site Engineer) clear items within their band. Anything above the band, or anything company-wide, escalates to an HO approver (MD, Head–Purchase, Head–Accounts, Manager–HR) — see the full matrix on Sheet 11.

9. Head Office rolls it all up in real time

   Consolidated cash flow, consolidated HR headcount, consolidated PO/expense status — queried live across every active project and site, without selecting a "current" one. This is what makes the whole model safe to run at scale.