# SiteRipoti (Working Title)
## Construction Site Reporting & Management App — Full Scope & Functional Specification

| | |
|---|---|
| **Document** | App Scope & Functional Specification |
| **Version** | 1.0 (Draft for review) |
| **Date** | 25 September 2026 |
| **Platform** | Makepad UI framework, Rust — single codebase targeting Android, iOS, Windows, macOS, Linux and Web (WASM) |
| **Status** | For stakeholder review |

---

## 1. Executive Summary

SiteRipoti is a multi-platform construction site management application that digitises **daily and monthly site reporting**, **workforce attendance**, **site communications**, **task scheduling and approvals**, **procurement** and **site meetings** — with AI assistance at every documentation step.

The app is designed around the reality of construction work in the field: unreliable connectivity, multiple concurrent sites under one supervisor, casual labour with paper IDs, and reporting chains that require verification before anything becomes official. It is **offline-first**, role-based, and audit-logged.

This document formalises the original six-phase scope (22 requirement items) and adds the omitted capabilities — user accounts and permissions, offline sync, safety reporting, snag lists, RFIs, purchase orders, dashboards, document/drawing control and integrations — required to make the app a complete, production-ready product rather than a collection of features.

**Notation:**
- **[BASE]** = requirement from the original scope, formalised
- **[ENHANCED]** = original requirement with meaningful additions
- **[NEW]** = omitted capability added in this document for a fully functional app

---

## 2. Background & Problem Statement

Site supervision today runs on a mix of WhatsApp groups, paper diaries, phone-camera photos and Excel sheets. The consequences:

- **Lost evidence** — photos scattered across personal phones; no timestamp/GPS proof.
- **Unverified reporting** — anyone can write anything; there is no approval chain or accountability.
- **Slow compilation** — an overall supervisor managing several sites must manually merge daily reports into monthly packs, often days later.
- **No audit trail** — disputes on what was done, when, and who approved it, are impossible to settle.
- **Casual labour opacity** — no reliable record of who worked, where, and under which department.
- **Paper meetings** — minutes taken by hand, typed up late, actions forgotten.

The app replaces this with one verifiable system of record from the foreman's pocket to the boardroom pack.

---

## 3. Product Objectives & Success Criteria

| # | Objective | Success Metric |
|---|---|---|
| O1 | Every site produces a complete, verified daily report | ≥ 90% of working days with an approved daily report per site |
| O2 | Cut report preparation time | Daily report compiled in ≤ 15 min; monthly pack in ≤ 30 min (vs. hours today) |
| O3 | Reliable multi-site oversight | Overall Supervisor compiles N-site consolidated report in one action |
| O4 | Trustworthy records | 100% of approvals carry user identity, timestamp and signature |
| O5 | Field usability | All core features fully usable offline on a low-end Android phone |
| O6 | Faster approvals | Task inspection → approval turnaround visible and measurable per site |

---

## 4. Users & Roles

### 4.1 Personas

| Persona | Description |
|---|---|
| **Overall Supervisor / Project Manager** | Manages several geographically distributed sites; needs consolidated reporting and cross-site visibility |
| **Report Master** | Prepares, verifies and approves the site's daily/monthly report; the authority on report content |
| **Site Supervisor / Site Agent** | Runs one site; contributes entries, photos and workforce data |
| **Site Engineer / Foreman / Site Manager** | Internal inspectors; verify task quality; contribute entries |
| **Procurement Officer** | Manages material schedules, suppliers and purchase orders |
| **HSE Officer** | Owns safety compliance, incidents and toolbox talks |
| **External Consultant** | Outside the company; performs external inspections and approvals on specific tasks |
| **Client / Project Owner** | Read-only stakeholder receiving progress digests |
| **Casual Worker** | Indirect user — present via scanned ID and attendance records |

### 4.2 Role × Capability Matrix

| Capability | Org Admin | Overall Supervisor | Report Master | Site Supervisor | Engineer/Foreman | Procurement | HSE | Consultant (ext.) | Client (viewer) |
|---|---|---|---|---|---|---|---|---|---|
| Manage organisation & users | ✔ | ✔ | – | – | – | – | – | – | – |
| Create/edit sites & working hours | ✔ | ✔ | – | – | – | – | – | – | – |
| Contribute entries to daily report | – | ✔ | ✔ | ✔ | ✔ | – | ✔ | – | – |
| Compile daily report | – | ✔ | ✔ | – | – | – | – | – | – |
| Approve & sign report | – | ✔ | ✔ | – | – | – | – | – | – |
| Compile multi-site report | – | ✔ | – | – | – | – | – | – | – |
| Scan workers / manage attendance | – | ✔ | ✔ | ✔ | ✔ | – | – | – | – |
| Chat in site channels | – | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | – |
| Manage task schedule & templates | – | ✔ | ✔ | ✔ | ✔ | – | – | – | – |
| Internal inspection sign-off | – | ✔ | ✔ | ✔ | ✔ | – | ✔ | – | – |
| External inspection sign-off | – | – | – | – | – | – | – | ✔ (assigned tasks only) | – |
| Create/approve purchase orders | – | ✔ | – | – | – | ✔ | – | – | – |
| Record meetings & generate minutes | – | ✔ | ✔ | – | – | – | – | – | – |
| Log incidents / HSE records | – | ✔ | ✔ | ✔ | ✔ | – | ✔ | – | – |
| View dashboards & analytics | ✔ | ✔ | ✔ | (own site) | (own site) | ✔ | ✔ | – | ✔ (digest) |
| View full document library | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | (shared only) | (shared only) |

*(Role capabilities are configurable per organisation; the matrix shows defaults.)*

---

## 5. Platform & Technology

| Layer | Choice | Rationale |
|---|---|---|
| UI | **Makepad (Rust)** | One codebase → native performance on mobile, desktop and web; smooth media-heavy UI |
| Business logic | Rust core crate | Shared across platforms; testable; safe |
| Local store | SQLite (per-device) | Offline-first storage, media queue, sync journal |
| Backend | Rust API service (e.g. Xicta - check implemented nimanyatta server existing in this path (/Users/aok/Projects/rustdev/CratesCode/nimanyatta/src) to be extended to meet our requirements here) + PostgreSQL + S3-compatible object storage | Type-safe end-to-end; simple deployment |
| Sync | Background delta sync with resumable media upload | Survives poor site connectivity |
| AI | LLM API (cloud) with on-device fallback for voice-to-text | Description refinement, photo captioning, transcription, minutes, summaries |
| Camera / GPS / Barcode–QR / OCR | Platform APIs via Makepad bindings | ID scanning, photo capture, geotagging |
| Push & local notifications | FCM / APNs + local scheduler | Reminders work offline |
| Auth | Email/phone + password, PIN + biometric app lock | Fast field access, secure at rest |

**Target devices:** priority is Android (low-end phones common on site), then iOS, then desktop for supervisors and web for client/viewer access.

---

## 6. High-Level Architecture & Offline-First Strategy

1. **Every core action is a local transaction.** Capturing photos, writing entries, scanning IDs and chatting all write to the on-device SQLite store first; the app is fully usable with zero connectivity.
2. **Sync journal.** All changes queue with the author, device and timestamp. When connectivity returns (Wi-Fi, hotspot), deltas upload; conflicts on shared documents (e.g. a report) are resolved by server arbitration and flagged for the Report Master.
3. **Media pipeline.** Photos/GIFs are compressed client-side, stamped with **timestamp + GPS + site name watermark** as evidence, then uploaded resumably. Originals retained per retention policy.
4. **Server-side authority.** Approvals, signatures, report locking and role permissions are enforced server-side — never client-only — so records are tamper-evident.
5. **Audit log.** Every create/edit/approve/lock/share event is recorded immutably (who, what, when, from where).

---

## 7. Functional Scope

---

### Phase 0 — Foundation & Platform **[NEW]**

*(Omitted in the original scope; without it, none of the other phases can ship.)*

- **FR-0.1 Organisation & user management** — Company (organisation) creation; invite-based onboarding by email, phone or share link; user profiles with role assignment per site.
- **FR-0.2 Roles & permissions** — Implement the §4.2 matrix; server-enforced. Consultants and clients are scoped strictly to what is shared with them.
- **FR-0.3 Site registry** — Create sites with name, geolocation, project type, working hours (per-site), team assignment and optional geofence.
- **FR-0.4 Offline-first core** — All Phase 1–6 features operate offline; background sync; visible sync status indicator (pending/synced/error).
- **FR-0.5 App security** — PIN/biometric lock, auto-lock, remote device revocation, encrypted local database.
- **FR-0.6 Notification centre** — In-app inbox of all alerts (approvals, mentions, reminders, escalations) + push notifications.
- **FR-0.7 Audit trail** — Immutable activity log per report, task, order and document; exportable.
- **FR-0.8 Settings** — User profile, drawn signature image, language (English/Swahili), dark mode, notification preferences, storage management.

---

### Phase 1 — Daily & Monthly Reports

#### Capture & documentation

- **FR-1.1 [BASE] Photo/GIF capture** — Take pictures or short looping clips (GIF/MP4) of the task being performed; multi-select from gallery; each item stamped with timestamp, GPS coordinates and site watermark. **[ENHANCED]:** annotation on photos (arrows, circles, text), and capture of a short **voice note** per entry.
- **FR-1.2 [BASE] Task description with rich text** — Description editor supporting **bold, underline, italic** and **bullet/numbered lists**. **AI refine** action: fix grammar, professionalise tone, expand terse notes into clear narrative — while preserving the user's facts. **[NEW]:** voice-to-text dictation; AI-assisted photo captioning; per-entry category (e.g. concrete works, plumbing) for later aggregation.
- **FR-1.3 [BASE] Document generation** — Generate the day's entries (photos + descriptions) into a formatted **PDF and Word (.docx)** document: branded cover page (company logo, project, site, date, author), table of contents for longer reports, photo grid with captions. **[NEW]:** customisable templates; automatic report numbering (e.g. `DR-SITE01-2026-09-25`).

#### Collaboration & verification

- **FR-1.4 [BASE] Multi-user contribution** — Multiple users on site add entries to the day's report. The **Report Master** compiles, verifies and **approves** the report before it is official; contributor list and their entries are visible in the document. **[ENHANCED]:** contributors see entry status (pending/accepted/returned with comment); approval captures a **drawn or typed digital signature**; approved reports are **locked and versioned** (resubmission creates a new version with a change log).
- **FR-1.5 [BASE] Multi-site compilation** — Site supervisors/personnel create reports for their individual sites; the **Overall Supervisor** generates a **compiled daily report** consolidating all submitted sites — per-site sections plus an executive summary page. **[NEW]:** compilation flags missing sites (not yet submitted) and can send a chase notification; consolidated export to PDF/Word.

#### Reminders

- **FR-1.6 [BASE] Daily capture reminder** — Configurable reminder (default **1 hour before end of working hours**, per-site working hours) to take pictures and create the report. **[NEW]:** escalation nudge to the supervisor if no report has been started 30 minutes after shift end.
- **FR-1.8 [BASE] Monthly report reminder** — Reminder to generate and review the monthly report **72 hours before the planned site meeting date** (configurable lead time).

#### Monthly reporting

- **FR-1.7 [BASE] Monthly accumulation** — Automatically accumulate the month's approved daily reports into a **monthly report**: all tasks executed, photo highlights, per-category totals. **[ENHANCED]:** AI-generated executive summary and progress narrative; auto-embedded statistics (manpower by day, materials received, delays, HSE stats); export to **PDF, Word and PowerPoint** for the meeting presentation.

#### Supporting site-diary data **[NEW]** *(standard content of a professional daily site report, omitted in the original scope)*

- **FR-1.9 Weather conditions** — Auto-fetched weather at site + manual override; feeds delay justification and the monthly report.
- **FR-1.10 Manpower & plant log** — Workers on site by trade/department (auto-filled from Phase 2 attendance), equipment/machinery on site with hours operated.
- **FR-1.11 Materials received today** — Deliveries captured against orders (auto-links Phase 5).
- **FR-1.12 Delays & hindrances** — Structured delay log with reasons (weather, labour, materials, design, access) and lost-time estimate; rolls into monthly summary.
- **FR-1.13 Visitor log** — Who visited, purpose, time in/out.
- **FR-1.14 Report lifecycle & archive** — Status workflow `Draft → In Review → Approved → Locked`; full-text search and filterable archive by site, date, author, status; batch export.

---

### Phase 2 — Workers Report Table

- **FR-2.1 [BASE] ID scanning** — Scan casual workers' IDs (national ID, work permit, NCA card) via OCR; capture name, ID number and photo; assign **work department/station**. Duplicate detection prevents double registration. **[ENHANCED]:** consent capture and encrypted storage of ID data; consent flag required before storage.
- **FR-2.2 [BASE] Daily workers table** — Auto-generate the table of workers present on the day: names, departments, work stations, with headcount summary by department/trade. Exportable as PDF/Excel and attachable to the daily report.
- **FR-2.3 [NEW] Attendance & timesheets** — Clock-in/clock-out per worker (with optional geofence check); hours and overtime computed; export **payroll-ready CSV** (per department, per day/week/month).
- **FR-2.4 [NEW] QR quick check-in** — Generate printable QR badges for repeat workers so the next day's attendance is a scan, not a full ID capture.
- **FR-2.5 [NEW] Worker register & flags** — Site worker register with status (active/inactive), skills/trade tags, and an organisation-level blocklist.
- **FR-2.6 [NEW] Privacy controls** — ID images encrypted at rest, retention policy (auto-purge after configurable period), and full deletion on worker offboarding — aligned to data protection law (see §12).

---

### Phase 3 — Chat & Communications

- **FR-3.1 [BASE] Site chat** — One-to-one and group chat for site communications; dedicated **site channels** (e.g. Announcements, Site A – General) with membership tied to site teams.
- **FR-3.2 [BASE] File sharing** — Share **reports, approval documents and minutes** in chat with inline preview; shared documents open in the app viewer.
- **FR-3.3 [NEW] Chat essentials** — Read receipts, @mentions with push notification, pinned messages, message search, offline send-queue with delivery on reconnect.
- **FR-3.4 [NEW] Bot notices** — Automatic posts into channels for key events (report approved, meeting scheduled, purchase order issued, task inspection due) so the channel becomes the site's live feed.
- **FR-3.5 [NEW] Broadcast** — Overall Supervisor broadcasts a message to all sites' channels at once.
- **FR-3.6 [NEW] Moderation & retention** — Channel admin roles, mute, archive, and message retention policy.

---

### Phase 4 — Task Schedule, Approval Documentation & Status

- **FR-4.1 [BASE] Task templates by project type** — Auto-generate the construction activities template (main tasks and subtasks) from the user-defined **nature of the site** (residential building, warehouse, apartment estate, market, hospital, school, road, etc.). **[ENHANCED]:** AI generates a tailored breakdown from project type + a short scope description; templates are fully editable and reusable as the organisation's own library.
- **FR-4.2 [BASE] Full program of works** — Define all construction activities from project start, or adopt the template **mid-project** by marking actual progress so far, then itemise tasks and sub-tasks through to project end.
- **FR-4.3 [BASE] Timelines & quantities** — Set start/end dates and durations per task/subtask, and **material quantities** per task (feeds Phase 5 material schedule). **[ENHANCED]:** dependencies between tasks, milestones, and baseline vs actual tracking with slippage alerts.
- **FR-4.4 [BASE] Task IDs & inspection routing** — Each task carries a unique ID assigned for inspection/approval by **internal** roles (Site Engineer, Site Agent, Foreman, Site Manager) and **external consultants**, enabling domestic approval and tracking. **[ENHANCED]:** per-task inspection **checklists** (pass/fail/NA with notes and evidence photos); approval captures signature, timestamp and identity.
- **FR-4.5 [BASE] Status tracking** — Task status board: `Not Started / In Progress / Awaiting Inspection / Approved / Rework Required / On Hold`, with percentage complete and photo evidence per task. Daily report entries link to the tasks they relate to.
- **FR-4.6 [NEW] Views** — Gantt (timeline) view, calendar view and list/board views; filter by status, responsible person, department or consultant. check this code in this path (/Users/aok/Projects/rustdev/CratesCode/nigig-org/crates/apps/nigig-build/src/construction_frame/pages/workspace/project_management) to be in its own crate and functionality extended to meet our requirements where site can just add it as a crate and implement functionality needed.
- **FR-4.7 [NEW] Snag / defect list** — Log defects (punch list) with location, photo, assignee and due date; closure requires a closure photo and sign-off. Snag statistics feed the monthly report.
- **FR-4.8 [NEW] RFI log** — Requests For Information raised to consultants/designers with response tracking and due dates; unresolved RFIs highlighted as delay risks.
- **FR-4.9 [NEW] Variation register** — Record variation/change orders with justification, cost/time impact and approval trail, linked to affected tasks.

---

### Phase 5 — Procurement Schedule & Approval

- **FR-5.1 [BASE] Material schedule & sourcing** — Create the material quantity schedule per task; record sourcing options across **hardware stores, agents and factories**. **[ENHANCED]:** required-vs-delivered auto-computation — the app shows remaining quantities to procure from deliveries already captured in daily reports.
- **FR-5.2 [BASE] Directory** — Hardware, agent and factory directory: contacts, locations, categories, price lists. **[ENHANCED]:** supplier **rating** (price, delivery timeliness, quality) from history; price comparison across suppliers per material.
- **FR-5.3 [NEW] Requisition → LPO workflow** — Raise a material requisition from the schedule; generate a numbered **Local Purchase Order (PDF)**; approval chain (Supervisor → Procurement → Admin) with signatures; status tracking `Requested → Approved → Ordered → Delivered → Closed`.
- **FR-5.4 [NEW] Delivery capture & verification** — Capture delivery notes by photo/OCR, verify received quantities against the LPO, flag shortfalls/damages; receipts automatically update the material schedule.
- **FR-5.5 [NEW] Budget tracking** — Budget vs actual spend per material and per task; variance highlighted for the monthly report.
- **FR-5.6 [NEW] Payment record (optional module)** — Record payments/deposits to suppliers with receipt images; mobile-money payment capture (e.g. M-Pesa reference) for the Kenyan market. *(Full accounting is out of scope — see §17.)*

---

### Phase 6 — Site Meetings

- **FR-6.1 [BASE] Schedule & reschedule** — Schedule and reschedule site meetings with date, time, venue/link, agenda and invited attendees (from the project directory); invites with RSVP; automatic reminders to all attendees.
- **FR-6.2 [BASE] Project directory** — Maintain the project directory/list of all participants: name, company, role, contacts — used for invites, approvals routing and minute attribution.
- **FR-6.3 [BASE] Listen to the meeting** — The app records meeting audio and listens to members speaking, with **speaker identification** (who said what).
- **FR-6.4 [BASE] Auto minutes** — At the end of the meeting the app **prepares and generates minutes**: agenda items, key discussion points per speaker, decisions, and **action items with owners and deadlines**. Editor allows correction before finalising.
- **FR-6.5 [BASE] Share minutes** — Distribute the approved minutes to attendees and interested parties via in-app chat, email and PDF/Word export.
- **FR-6.6 [NEW] Agenda templates & pre-reads** — Standard meeting agenda templates (progress, safety, procurement, AOB); attach pre-read documents (monthly report, programme update) to invites.
- **FR-6.7 [NEW] Action item tracker** — Action items from minutes become tracked items: due-date reminders, status, carry-forward of unresolved items into the next meeting automatically.
- **FR-6.8 [NEW] Cross-linking** — Minutes reference (and link to) the reports, tasks, RFIs, snags and variations discussed.
- **FR-6.9 [NEW] Transcription options** — English and Swahili speech recognition; export of the full transcript alongside the minutes.

---

### Phase 7 — Safety, Health & Environment (HSE) **[NEW]**

*(Omitted in the original scope; expected by any professional client and mandatory for credible site records.)*

- **FR-7.1 Incident & near-miss reporting** — Log incidents and near misses with photos, severity, persons involved, immediate action taken; escalation notification to supervisor and HSE officer.
- **FR-7.2 Toolbox talks** — Record safety talks delivered: topic, date, attendees pulled from the worker register.
- **FR-7.3 Safety inspections** — Scheduled inspection checklists (PPE compliance, scaffolding, housekeeping, electrical) with corrective actions, assignees and closure evidence.
- **FR-7.4 Emergency information** — Per-site emergency contacts, assembly points and procedures; available offline.
- **FR-7.5 HSE statistics** — Days since last incident, toolbox talk counts, open corrective actions — auto-embedded into the monthly report and dashboards.

---

### Phase 8 — Dashboards, Analytics & Client Access **[NEW]**

- **FR-8.1 Site dashboard** — Live per-site view: programme progress %, workers on site today, daily report status (submitted/missing), open snags/RFIs, delays this month, spend vs budget.
- **FR-8.2 Multi-site portfolio view** — Overall Supervisor sees all sites side by side with drill-down; traffic-light health per site.
- **FR-8.3 Trends** — Manpower over time, task burn-down, materials consumed, report timeliness.
- **FR-8.4 Client digest** — Automated weekly/monthly progress digest (summary + photo highlights) shared read-only with the client/owner; optional lightweight web portal access.
- **FR-8.5 Export** — Any dashboard or chart exportable as PDF/image for presentations.

---

### Phase 9 — Document & Drawing Management **[NEW]**

*(Required so "approval documents" and inspections have a controlled home.)*

- **FR-9.1 Document library** — Central, permissioned library for drawings, contracts, approvals, permits, insurance certificates, survey reports.
- **FR-9.2 Drawing revision control** — Revision register per drawing (Rev A/B/C…), supersede/withdraw with automatic notification to site teams; offline access to current revisions on device.
- **FR-9.3 Transmittals** — Record of who received which document revision and when.
- **FR-9.4 Upload & view** — Upload from camera or files; in-app viewer for PDF and images; search by name, type, discipline.

---

### Phase 10 — Integrations, API & Data Portability **[NEW]**

- **FR-10.1 Calendar sync** — Two-way sync of meetings and reminders with Google Calendar and Outlook.
- **FR-10.2 Share-out** — Email and WhatsApp share targets for reports, minutes and purchase orders.
- **FR-10.3 Maps & weather** — Map view of site locations (site registry); weather service integration (FR-1.9).
- **FR-10.4 REST API & webhooks** — Read APIs and webhooks for event push, enabling integration with accounting/ERP (e.g. pushing timesheet and PO data) and future extensions.
- **FR-10.5 Backup & export** — Organisation-level data export (reports, registers, documents) as a complete archive; configurable backup schedule.

---

## 8. AI Capability Summary

| Capability | Where used |
|---|---|
| Description refinement (grammar, tone, expansion) | Daily report entries (FR-1.2) |
| Voice-to-text dictation | Report entries, chat, minutes editing |
| Photo captioning suggestion | Report entries (FR-1.2) |
| Task template generation | Programme of works (FR-4.1) |
| Executive summary & progress narrative | Monthly report (FR-1.7) |
| Meeting transcription + speaker identification | Meetings (FR-6.3) |
| Minutes drafting (discussions → decisions → actions) | Meetings (FR-6.4) |
| Anomaly nudges (e.g. report mentions rain but weather was clear; entry has no photo) | Report QA before approval |

AI output is always **advisory** — the Report Master reviews, edits and approves before anything is final. All AI processing clearly labelled; sensitive ID data is **never** sent to external AI services.

---

## 9. Notifications & Reminders Summary

| Trigger | Recipient | Default timing (configurable) |
|---|---|---|
| Capture photos / start daily report | Site team | 1 hour before shift end |
| No report started (escalation) | Site + Overall Supervisor | 30 min after shift end |
| Generate & review monthly report | Report Master + Supervisor | 72 hours before planned meeting |
| Task inspection due | Assigned inspector | Morning of due date |
| Approval requested / granted | Requester / approver | Immediate |
| Snag / RFI / action item due | Assignee | 24 hours before due |
| Meeting reminder | Invitees | 1 day + 1 hour before |
| Incident logged | Supervisor + HSE | Immediate |
| Delivery / LPO status change | Procurement requester | Immediate |

---

## 10. Non-Functional Requirements

| Area | Requirement |
|---|---|
| **Offline** | All capture/report/attendance/chat-compose features fully offline; zero data loss on connectivity loss; sync resumes automatically |
| **Performance** | App cold start < 3 s on a mid-range Android; photo capture → entry saved < 1 s; monthly report generation < 60 s |
| **Media handling** | Client-side compression (target ≤ 1 MB per photo for sync); originals retained on device until synced; storage usage display and cleanup tools |
| **Battery** | GPS and camera use optimised; background sync batched |
| **Usability** | One-handed phone operation; large touch targets for field use; icon-driven navigation; English and Swahili UI |
| **Reliability** | Local database integrity checks; crash-safe write queue |
| **Scalability** | Support 100+ sites and 1,000+ workers per organisation without redesign |
| **Compatibility** | Android 9+, iOS 15+, Windows 10+, macOS 12+, modern browsers (web) |
| **Accessibility** | Dynamic text sizing; contrast modes |

---

## 11. Security

- TLS 1.3 for all transport; AES-256 encryption at rest (server) and encrypted local database (device).
- Biometric/PIN app lock; session timeout; remote device logout.
- Server-side authorisation on every API call (roles per §4.2).
- Tamper-evident approvals: every signature bound to user identity, device, timestamp and document hash.
- Immutable audit log (FR-0.7) retained per policy.
- Photo/GIF evidence watermarks cannot be edited within the app; edits create new versions.

---

## 12. Privacy & Compliance

- Compliance with the **Kenya Data Protection Act, 2019** (and GDPR-aligned principles for international use): lawful basis, consent capture for worker ID data, purpose limitation, data minimisation.
- Worker ID images/numbers: encrypted, access-controlled, retention-limited, deletable on request/offboarding.
- Data residency option (hosting region selectable per organisation).
- Role-based visibility ensures consultants/clients see only their scope.

---

## 13. Data Model Overview

Core entities (simplified):

```
Organization 1─* Site 1─* DailyReport 1─* ReportEntry 1─* MediaItem
                      │            └─* ApprovalEvent (signature, status)
                      │
                      ├─1─* Worker 1─* AttendanceRecord
                      ├─1─* Task (tree: main/sub) 1─* Inspection 1─* ChecklistItem
                      │        ├─1─* SnagItem / RFI / Variation
                      │        └─1─* MaterialRequirement
                      ├─1─* Supplier 1─* PurchaseOrder 1─* Delivery
                      ├─1─* Meeting 1─* Transcript 1─* Minutes 1─* ActionItem
                      ├─1─* ChatChannel 1─* Message
                      ├─1─* Incident / ToolboxTalk / SafetyInspection
                      └─1─* Document (revision-controlled)

User (role per org per site) — AuditEvent (global)
```

---

## 14. Key Workflows

**Daily report lifecycle**
`Capture (photo/GIF + rich-text entry, offline OK) → contributors add entries → Report Master compiles → (AI refine/QA) → approve + sign → lock & version → auto-share (chat/email) → sync to cloud`

**Multi-site compilation**
`Each site submits → Overall Supervisor opens "Consolidated Daily" → selects sites/date → app generates per-site sections + executive summary → missing sites flagged/chased → export PDF/Word`

**Monthly report**
`Auto-accumulate approved dailies + HSE/procurement/progress stats → AI drafts executive summary → Report Master reviews/edits → export PDF/Word/PowerPoint → present at meeting`

**Task approval**
`Task in progress (evidence photos) → internal inspection (checklist + sign-off) → external consultant inspection where assigned → Approved / Rework → status board updated → links to daily report entry`

**Procurement**
`Material schedule shows shortfall → requisition → LPO raised → approval chain → order → delivery captured & verified → schedule and budget updated`

**Meeting**
`Schedule (agenda + pre-reads) → record + transcribe (speaker ID) → AI minutes draft → edit & approve → share → action items tracked → unresolved items carry forward`

---

## 15. Traceability — Original 22 Items → This Specification

| Original item | Covered by |
|---|---|
| 1. Picture/GIF of task | FR-1.1 |
| 2. Description + AI refine + rich text | FR-1.2 |
| 3. PDF/Word generation | FR-1.3 |
| 4. Collaboration + Report Master verification | FR-1.4 |
| 5. Multi-site compiled reports | FR-1.5 |
| 6. Reminder 1 h before end of work | FR-1.6 |
| 7. Monthly accumulation | FR-1.7 |
| 8. Monthly reminder 72 h before meeting | FR-1.8 |
| 9. Scan casual worker IDs + department | FR-2.1 |
| 10. Workers table by day/station | FR-2.2 |
| 11. Chat, share reports/approvals/minutes | FR-3.1, FR-3.2 |
| 12. Task templates by site nature | FR-4.1 |
| 13. Full project task itemisation (incl. mid-project) | FR-4.2 |
| 14. Timelines + material quantities | FR-4.3 |
| 15. Task IDs + internal/external inspection | FR-4.4, FR-4.5 |
| 16. Material quantities + sourcing | FR-5.1 |
| 17. Hardware/agent/factory directory | FR-5.2 |
| 18. Schedule/reschedule meetings | FR-6.1 |
| 19. Project directory | FR-6.2 |
| 20. App listens to meeting | FR-6.3 |
| 21. Generate minutes | FR-6.4 |
| 22. Share minutes | FR-6.5 |

All additions introduced by this document: **Phase 0 (foundation), FR-1.9–1.14, FR-2.3–2.6, FR-3.3–3.6, FR-4.6–4.9, FR-5.3–5.6, FR-6.6–6.9, and Phases 7–10 in full.**

---

## 16. Release Roadmap

| Release | Content | Rationale |
|---|---|---|
| **R1 — MVP** | Phase 0 + Phase 1 (FR-1.1–1.8, 1.14) | Core value: verified daily reports, multi-site compilation, monthly packs |
| **R2** | FR-1.9–1.13 (site-diary data) + Phase 2 (attendance) + Phase 3 (chat) | Completes daily field operations |
| **R3** | Phase 4 (programme & approvals) + Phase 5 (procurement) | Planning and materials control |
| **R4** | Phase 6 (meetings) + Phase 7 (HSE) | Governance and safety |
| **R5** | Phase 8 (dashboards/client portal) + Phase 9 (documents) + Phase 10 (integrations) | Oversight, control and ecosystem |

Indicative effort: R1 is the critical path; subsequent releases can proceed in parallel streams once the Phase 0 platform exists.

---

## 17. Out of Scope (v1)

- Full payroll processing and statutory deductions (app **exports** payroll-ready data only)
- Accounting/bookkeeping (via API integration instead)
- BIM/CAD authoring or editing (documents are viewed, not edited)
- Equipment telematics / IoT sensor integration
- Client-side internet-free AI (cloud AI with graceful offline degradation only)

---

## 18. Open Questions

1. Hosting model — regional cloud vs. on-premise for larger contractors?
2. Commercial model — per-user subscription, per-site, or freemium?
3. Preferred AI provider and budget for LLM/transcription usage?
4. Priority document format — is Word parity with PDF required on day one, or PDF-first?
5. Does the client/viewer web portal need to be in R1 or can it wait for R5?
6. Retention period for worker ID data (legal/HR guidance)?
7. Should worker attendance include biometric verification (with its additional legal requirements), or photo/QR sufficiency confirmed?

---

## 19. Glossary

| Term | Meaning |
|---|---|
| **Report Master** | Person responsible for preparing, verifying and approving site reports |
| **Overall Supervisor** | Manager consolidating reports from multiple sites |
| **LPO** | Local Purchase Order |
| **RFI** | Request For Information (formal query to a consultant/designer) |
| **Snag list / Punch list** | List of defects to be corrected before acceptance |
| **Variation** | Contracted change to scope, cost or time |
| **HSE** | Health, Safety & Environment |
| **NCA** | National Construction Authority (Kenya) |
| **Programme of works** | The scheduled breakdown of all project activities |
| **Geofence** | Virtual GPS boundary used to verify presence on site |
| **DPA 2019** | Kenya Data Protection Act, 2019 |

---

*End of document — SiteRipoti Scope v1.0. Feedback from stakeholders to be incorporated in v1.1.*