Skip to content

Modules

Everything the ndakita_build app adds on top of the base ERP, module by module: what each one does, how they interact, the role permissions behind them, and where the roadmap stands. This page is the team's tracking reference; the per-repo docs/ folders hold the field-level detail.

Sources of truth: role matrix in ndakita_build/api/onboarding.py (ROLE_MATRIX), field detail in ndakita_build/docs/data-model.md, configuration detail in ndakita_build/docs/erp-config.md, and the build plan in ndakita_build/docs/module-roadmap.md.

Roadmap and progress

# Module Status Shipped Tests
P1 Material Requests from site ✅ Done 2026-07-18 test_material_request.py
P2 Finance approval levels (PO) ✅ Done 2026-07-18 test_po_approval.py
P3 Daily Site Reports + progress ✅ Done 2026-07-18 test_daily_site_report.py
P4 Customer (client records) ✅ Done 2026-07-18 test_customer.py
P5 Contracts ✅ Done (lightweight) 2026-07-18 test_contract.py
P6 Leads / CRM (Warm/Cold/Hot) ✅ Done 2026-07-18 test_leads.py
P7 Client Documents ✅ Done 2026-07-18 test_client_document.py
P8 Asset register + QR tags ✅ v1 done (scan UX → P9) 2026-07-18 test_assets.py
P9 Mobile / PWA for site managers ✅ v1 done — PWA (Option A); portal scanner + offline = v2 2026-07-19 test_workspace.py
— Procurement + Inventory ✅ Pre-existing Sprint 1–5 test_overrides.py
— Projects (types, phases, auto-setup) ✅ Pre-existing Sprint 1–5 test_overrides.py
— Labour (Daily Output Log) ✅ Pre-existing Sprint 1–5 test_daily_output_log.py
— M-Pesa reconciliation ✅ Pre-existing Sprint 1–5 test_mpesa_import.py

Open decisions for the founders (P9 resolved 2026-07-19 → PWA, Option A)

  1. P2 — confirm the PO approval threshold (KES 100,000 default in PO_APPROVAL_THRESHOLD) and whether a second approval level above Admin Finance is wanted.
  2. P5 — is the lightweight Contract enough, or is a bespoke Project Contract (payment terms, retention %) wanted on top?

How the modules interact

flowchart TD
    subgraph CRM [Sales pipeline]
        LEAD[Lead - temperature Cold/Warm/Hot] --> OPP[Opportunity]
        LEAD -->|convert| CUST[Customer + construction fields]
    end

    subgraph PROJ [Project core]
        CUST --> PROJECT[Project]
        PROJECT -->|auto-created| CC[Cost Centre]
        PROJECT -->|auto-created| WH[Site Warehouses - Main + Cement Store]
        PROJECT -->|auto-created| LOC[Location - asset site]
        CONTRACT[Contract - signed PDF, dates] --> PROJECT
        DOC[Client Document - deeds, approvals, IDs] --> CUST
        DOC -.optional.-> PROJECT
    end

    subgraph SITEOPS [Site operations]
        MR[Material Request - project-tagged rows] --> PO[Purchase Order]
        PO -->|approval workflow + threshold| PR[Purchase Receipt]
        PR --> PI[Purchase Invoice - project mandatory]
        WH --> MR
        TS[Timesheet + Daily Output Log] -->|on submit| JE[Journal Entries - quota pay]
        DSR[Daily Site Report - photos, blockers] -->|PM validates| PROJECT
    end

    subgraph ASSETS [Assets]
        ASSET[Asset + QR tag label] --> LOC
        MOVE[Asset Movement] -->|site transfer| LOC
    end

    subgraph FIN [Finance]
        MPESA[MPesa Import] -->|auto project match| JE2[Journal Entry]
        PI --> PL[Project P&L report]
        JE --> PL
        JE2 --> PL
    end

    DSR --> PP[Project Progress report]
    TS --> SLP[Site Labour Performance report]
    WH --> SID[Site Inventory Dashboard]

The recurring pattern: everything is tagged to a Project, and the Project auto-creates its own cost centre, site warehouses, and asset location on insert — so every module's records roll up to per-project P&L and progress without manual setup.

Module reference

Procurement + Inventory (pre-existing)

Supplier → PO → Receipt → Invoice flow with per-project site warehouses (auto-created), a Transit Central Store for inter-site transfers (reason required), reorder levels, and the Site Inventory Dashboard. Purchase Invoices require a project before submit (client script) — this is what makes per-project P&L trustworthy.

P1 — Material Requests from site

  • Foremen and Site PMs raise Material Requests; Admin Finance reads.
  • Each item row is auto-tagged with the project of the chosen site warehouse (Warehouse.custom_project_site); submission is blocked until every row has a project (public/js/material_request.js).
  • Foreman site-scoping comes free from the existing User Permissions sync (User.custom_assigned_sites → Project + Warehouse permissions).
  • Interacts with: site warehouses (P source of project tag), Purchase Orders (procurement acts on requests), Projects (P&L trace).

P2 — Purchase Order approval ("levels of approval")

  • Purchase Order Approval workflow (fixture, generated by scripts/make_workflows.py): below the threshold a Site PM submits directly; at/above it the PO goes to Pending Approval and only Admin Finance can Approve/Reject.
  • Threshold: PO_APPROVAL_THRESHOLD = KES 100,000 (pending founder confirmation).
  • A seeded per-company Authorization Rule enforces the same threshold in on_submit, so API/scripted submits cannot bypass approval.
  • Interacts with: Material Requests (upstream), Purchase Receipts/Invoices (downstream), Admin Finance role.

P3 — Daily Site Reports + progress reporting

  • Daily Site Report (naming DSR-.YYYY.-.MM.-.####): work done, blockers, labour count, weather, photos (child Site Report Photo).
  • Workflow Daily Site Report Review: Foreman submits → Site PM Validates. Validation rolls the reported phase and progress % onto the Project (custom_current_phase, custom_progress_pct).
  • A report's site warehouse must belong to its project (guard).
  • Project Progress report: phase, % complete, last report date, reports filed, latest blockers — the "which sites are quiet or stuck" view.
  • Interacts with: Projects (progress rollup), Client View (read), P9 mobile (primary phone workflow later).

P4 — Customer (client records)

  • Construction fields on Customer: ID/registration no., KRA PIN, client since, primary site. Projects link via the standard Project.customer.
  • Client View users are scoped with User Permissions (own Customer + Projects) at invite time.
  • Interacts with: Leads (conversion target), Contracts (party), Client Documents (files against the customer), Projects.

P5 — Contracts (lightweight)

  • Base Contract doctype + custom_project link; party is the Customer; signed PDF via the attachments sidebar; start/end dates and signed status tracked.
  • Project keeps custom_contract_value / custom_retention_amount for the financials.
  • Interacts with: Customer, Project. (Bespoke Project Contract remains a founders' option.)

P6 — Leads / CRM (tenant sales pipeline)

  • custom_lead_temperature (Cold / Warm / Hot) on Lead and Opportunity — filterable in list views.
  • Seeded Sales role: full Lead / Opportunity / Customer, deliberately no project or finance access. Site PM also has full CRM access.
  • Construction Lead Sources seeded: Referral, Site Signboard, Walk-in, Website.
  • Interacts with: Customer (standard conversion), then the whole project chain.

P7 — Client Documents ("keeps client data")

  • Client Document (naming DOC-.YYYY.-.####): typed paperwork — Title Deed, Council Approval, Contract, Drawing, ID/Registration, KRA, Other — filed against a Customer, optionally a Project (customer/project mismatch is blocked).
  • 30-day expiry reminder: Client Document Expiry Reminder Notification (fixture) emails Admin Finance + Site PM.
  • Sensitive: Client View reads only its own customer's documents.
  • Interacts with: Customer, Project, Architect (drawings read).

P8 — Asset register + QR tags (v1)

  • Seeded non-depreciable Asset Categories: Plant & Machinery, Formwork & Scaffolding, Power Tools, Vehicles, Site Equipment (depreciation stays a tenant finance decision).
  • Site tracking is native: every Project is mirrored as a Location (auto-created), Head Office seeded; Asset.location + Asset Movement move assets between sites with an audit trail.
  • custom_asset_tag + Asset Tag Label print format: framework- rendered QR (no CDN) encoding the asset's URL — scanning a printed tag with any phone camera opens the asset.
  • Interacts with: Projects (Locations), Foremen (movements), P9 (in-app scanner later).

P9 — Mobile / PWA for site managers (v1)

  • Decision (2026-07-19): Option A (PWA). Flutter shelved.
  • v1: the On Site Workspace (fixture, generated by scripts/make_workspaces.py) — a Foreman/Site-PM-only mobile landing with big shortcut tiles for New Material Request, New Daily Report, My Timesheets, and Assets, plus a browse card. Frappe v15's desk is already an installable PWA, so Add to Home Screen gives a branded Ndakita Build phone app with no separate repo.
  • v2 (later): dedicated mobile-first portal pages with an in-app QR scanner (finishes the P8 scan UX) and offline report queueing.
  • Interacts with: surfaces P1 (Material Request), P3 (Daily Site Report), Labour, and P8 (Asset lookup) on a phone.

Labour — Daily Output Log (pre-existing)

Quota-based casual labour on Timesheet: per-worker daily target, achieved quantity, pro-rated pay with a 70% floor, journal entries on submit, M-Pesa bulk-payment export via the Site Labour Performance report.

M-Pesa reconciliation (pre-existing)

MPesa Import parses statements (PDF/CSV/Excel), auto-suggests the project per transaction, and posts Journal Entries on confirmation.

Role permissions

Levels: full = read/write/create/delete (+ submit/cancel/amend on submittable doctypes) · read = view only. Foreman access is additionally scoped to their assigned sites via User Permissions; Client View is scoped to their own customer/projects at invite time.

DocType Site PM Admin Finance Foreman Architect Client View Sales
Project full read read (own) write (BOQ/drawings) read (own) —
Warehouse full read read (own) — — —
Item / Supplier full read read (Item) read (Item) — —
Material Request full read full (own site) — — —
Purchase Order full full (approver) — — — —
Purchase Receipt full read — — — —
Purchase Invoice / Payment Entry / Journal Entry read full — — — —
Sales Invoice — full — — — —
Stock Entry full read full (own site) — — —
Timesheet (Daily Output Log) full read full (own site) — — —
Daily Site Report full (validates) read full (own site, submits) — read (own) —
Customer full full — — read (own) full
Contract full full — — — —
Client Document full full — read read (own) —
Lead / Opportunity full — — — — full
Asset full read read — — —
Asset Category full read — — — —
Asset Movement full read full — — —

Workflow actions (on top of doc permissions):

Workflow Action Who
Purchase Order Approval Submit (below threshold) Site PM, Admin Finance
Purchase Order Approval Submit for Approval (at/above threshold) Site PM, Admin Finance
Purchase Order Approval Approve / Reject Admin Finance only
Daily Site Report Review Submit Foreman, Site PM
Daily Site Report Review Validate Site PM only

Report access: finance reports → Admin Finance + Site PM; stock reports → + Foreman; Project Progress + Site Labour Performance → Site PM, Admin Finance, Foreman. 2FA is pre-flagged for Site PM and Admin Finance (enabled per tenant when users are ready to enrol).

Seeded per tenant (zero manual steps)

Every new site gets, idempotently on install and every migrate: item groups, UOMs, the six roles, Transit warehouse type + Central Store, payment terms (incl. 50/50), standard contract T&Cs, activity type, lead sources, Head Office location, asset categories, the two workflows, the document-expiry notification, the PO authorization rule, the On Site Foreman workspace, role/report permissions, and Ndakita Build branding. Verified 2026-07-19: a fresh new-site + install-app erpnext ndakita_build produces all modules (incl. the P9 workspace) with no manual steps.