How to read this map
Each chapter walks one process in numbered steps. Every step names the actor, describes what the system does, and states what triggers the next step. Branches list every possible outcome at that point. Red-numbered steps are process endpoints.
1 · Approved data only. Dashboards, reports and the AI analyst read approved results exclusively. A figure that is not approved does not exist for reporting purposes.
2 · Transitions by procedure only. Submission and verification state changes go through guarded database procedures. Direct writes are rejected by the database itself, even for administrators.
3 · Approved results are locked. Once approved, a value and its RAG snapshot are frozen. Changing RAG thresholds recomputes non-approved results only. The only way back is a logged administrative reopen.
4 · AI assists, people decide. AI verification and analysis are first-level assistance. Every final decision — approve, reject, request clarification — is a person's, recorded with name, time and note.
5 · Everything is audited. Creations, updates, deletions, workflow events, overrides and decisions land in an immutable audit log with actor and timestamp.
Accounts, roles & access
Access is invitation-only and organization-bound. Eight roles carry 46 granular permissions; every screen and action checks them on the server.
1.1 · Requesting an account — public visitor
The visitor submits name, email and reason. No system account is created at this point.
The request is emailed to the platform owner’s configured address.
With an invitation sent, or with silence.
1.2 · Inviting a user — System Administrator
Enters full name, email, department and role(s). The invitation binds the future account to the organization at the authentication layer — a user can never sign up into the wrong organization.
The system emails a one-time invitation link from the platform’s verified domain.
With an active, organization-bound account.
The user appears in the user register; their role determines every subsequent capability in this map.
1.3 · Deactivation — exception path
The account keeps its history (submissions, decisions, audit entries remain attributed) but loses all access: row-level security resolves a deactivated user to no organization, so every query returns nothing. Notifications stop — the engine only notifies active users.
Immediately. Reactivation restores access without data loss.
1.4 · The eight roles
| Role | Core responsibility in the workflows below |
|---|---|
| System Administrator | Everything, plus the only role that manages the strategic plan, users, workflows and settings |
| M&E Administrator | Periods, indicators, targets, RAG configuration, notification settings, engine controls |
| M&E Officer | Reviews and approvals, verification decisions, corrective actions, evaluations |
| Department Manager | First-line review of the department’s submissions; department performance |
| Data Entry Officer | Enters results, uploads evidence, submits the department’s return |
| Project Manager | Projects, milestones, activities, project evidence |
| Executive | Read access to dashboards, reports and the AI analyst |
| Auditor | Read access everywhere, including the audit trail; changes nothing |
Strategic plan & results framework
One strategic plan per organization, revised over its life — never multiplied. Only the System Administrator can create or change it; everyone else reads. The plan carries the hierarchy everything else aligns to.
Sets name, period (multi-year), vision and mission. Because an organization keeps one plan, revisions edit the existing plan rather than creating parallel ones.
Plan set to active — it becomes the root of the results framework.
The PDF is stored privately and rendered as a page-turning flipbook on the plan page, with table-of-contents navigation, page jump and full-text keyword search, so every staff member reads the same authoritative document inside the system.
Strategic Pillars → Strategic Objectives → Outcomes → Outputs. Each level links upward, so every record traces to the plan. Pillar rows open detail pages listing their objectives.
The Results Framework screen renders the full indented chain; indicators may now attach at any level (chapter 04).
All other roles see the plan, the flipbook and the framework read-only. Attempts to modify are refused by both the interface and row-level security.
The plan lifecycle ends at completed (period over) or archived.
Historical alignment is preserved: programs, indicators and results keep their linkage to the archived structure.
Programs, projects & activities
The delivery structure under the plan. Programs group projects; projects carry budgets, milestones and three progress dimensions; activities sit under projects.
A project records its program, department, manager, dates, budget and health. Milestones get planned dates and owners — these dates feed the reminder engine (chapter 11).
Physical, financial and schedule progress are tracked separately; the dashboard shows the physical-minus-schedule gap as the project’s honesty check. Milestone completion records the actual date.
Project set to completed (or cancelled, which stops its reminders).
Project indicators and evidence remain queryable; evaluations (chapter 09) may reference the project.
Indicators, targets & RAG
Indicators are the measurement contract. Their definition, data source and verification method are not paperwork — the AI verifier reads them when judging evidence.
Code, name, definition, unit, value type (numeric, percentage, currency, count, ratio, date, yes/no, text), direction of success (higher-better, lower-better, exact, range), baseline, data source, collection method, calculation method, verification method, frequency, aggregation, and its attachment point in the results framework plus the responsible department and officer.
Each target belongs to one indicator and one period. Once any result against a target is approved, the target is locked — the database refuses changes that would rewrite history.
An organization-wide default (e.g. green ≥ 90 % achievement, amber 70–90 %, red < 70 %) with per-indicator overrides where a measure needs its own bands.
The indicator is ready for the reporting cycle.
The calculation engine applies achievement % (inverted for lower-better measures), variance and RAG automatically on every value entered.
The reporting cycle
The core process: a period opens, departments enter and evidence their results, submissions travel a configurable approval chain, and approved figures — and only approved figures — flow to dashboards, reports and the AI analyst.
5.1 · Opening a reporting period — M&E Administrator
Monthly, quarterly, semiannual or annual, with start/end dates and a submission due date. Status begins at upcoming. The due date drives every deadline reminder and escalation in chapter 11.
One submission is generated per department that has targeted indicators in this period, each containing one result row per indicator, all at draft.
System notifies every submitter in an affected department: “Reporting period open — submissions due <date>” (in-app + email, subject to preferences).
5.2 · Entering results — Data Entry Officer
Editable only while the submission is draft or returned, and only for the officer’s own department. The value field matches the indicator’s type; explanation, challenges and a “corrective action required” flag accompany it.
System instantly computes achievement %, variance and RAG from the target and shows them beside the value.
Excel, Word, PDF, scanned PDF, images, CSV — stored in the private evidence vault, linked to the exact result row.
AI Evidence verification starts automatically in the background the moment the upload completes (chapter 06). The officer does not wait for it.
The guarded procedure moves the submission to submitted and stamps who and when. From here the department can no longer edit values.
System notifies the first-stage reviewer — the department head for first-line review — “Submission awaiting your review” (in-app + immediate email).
5.3 · Review & approval chain — Department Manager, then each configured stage
Moves it to under review. The reviewer sees every value with its computed RAG, the narrative, the evidence — and each file’s AI verification result (score, discrepancies, relevance), so attention goes to the flagged rows first.
On any decision, the affected people are notified immediately (in-app + email): submitter on return/approval, next-stage holders on advance.
The submission’s life ends at approved.
Approved figures immediately count in dashboards, department performance, reports and the AI analyst. If an approved result lands red, the responsible officer and department head are alerted “Indicator off track”; amber alerts the officer “Indicator at risk”. Red results and “corrective action required” flags feed chapter 07. Evidence verification decisions (chapter 06) remain open until an M&E officer closes them.
5.4 · Exceptions
The only path back from approved: a guarded administrative procedure requiring a written reason, returning the submission to returned for correction and re-approval. The reopen, its reason and its actor are recorded in the event history and audit trail.
A manual RAG override (e.g. amber → red for context the numbers miss) requires a reason; the computed status is preserved alongside the override, both visible, both audited.
Departments still in draft or returned when the due date approaches or passes enter the submission escalation ladder (chapter 11): reminders at 7 and 3 days before, on the day, then escalation to the department head at +3 days and to head + administrators at +7 days.
Period set to closed; closing user and time recorded. Late entry is no longer possible without an administrative reopen.
Evidence & AI verification
Evidence is treated as structured data, not an attachment. Every uploaded file is read, cross-referenced against the submitted value, scored deterministically, and queued for a human decision. The AI never decides.
6.1 · Automatic verification — runs on every upload
Excel is read cell-by-cell with sheet and row references; CSV and text line-numbered; Word paragraph-numbered; PDF text page-labeled. Scanned PDFs and photographs go to the vision model as whole files (up to 8 MB).
The model receives the indicator’s definition, unit, data source, collection method, calculation method and verification method, the reporting period dates, and the submitted value — then reports, strictly from the document: candidate values with exact quotes and source references, relevance (supported / partial / unrelated / unknown), period fit, terminology presence, and — where a calculation method exists — whether the underlying figures reproduce the submitted number.
Five weighted checks: value confirmed (40), relevance (25), period (15), source identifiable (10), terminology (10). A value within 0.1 % passes; within 5 % warns as a minor discrepancy with the exact difference; beyond that, fails. The score and status are arithmetic over the checks:
The result appears on the verification dashboard, the evidence register and inside the submission review screen — reviewers work the flagged and red rows first.
6.2 · The human decision — M&E Officer (review permission)
Sees the score, every check with its detail, each found value with its quote and source reference, the AI summary labeled “first-level check only”, and the variance.
The database physically blocks any other path to these fields — the decision can only be recorded through the guarded procedure, with the officer’s name, time and note.
With the recorded decision.
The uploader is notified of the decision (in-app + email). The full matrix — indicator → submitted → evidence value → source → variance → AI finding → reviewer decision — persists permanently as the verification audit trail.
Corrective actions & escalation
Where under-performance turns into managed work. Actions link back to the indicator, result, project or evaluation recommendation that caused them — the traceability chain never breaks.
Title, reason, the linked source (red indicator result, project, or an evaluation recommendation), owner, department, priority (low → critical) and due date. Red approved results and “corrective action required” flags from the reporting cycle are the usual entry points.
System The daily sweep walks the escalation ladder below for every open action with a due date.
completed with completion time (or cancelled). Either state stops all reminders.
The action remains linked to its source for evaluations and audits: “red result → action → resolution” is a queryable chain.
7.1 · The default escalation ladder — editable per organization in Administration → Notifications
| When | Offset | Corrective actions | Submissions |
|---|---|---|---|
| Reminder | −7 days | Responsible officer | Responsible officer |
| Reminder | −3 days | Officer + department head | Officer + department head |
| Overdue warning | 0 | Responsible officer | Officer + department head |
| Escalation | +3 days | Department head | Department head |
| Escalation | +7 days | Head + administrators | Head + administrators |
Milestones remind at −7, −3 and 0 (owner, then owner + head); evaluations remind their lead at −7 and −1 before the start date. Each reminder fires at most once per person per record per day, however many times the engine runs.
Risks & issues
Forward-looking exposure (risks) and materialized problems (issues), both department-owned and visible on the dashboard when they demand attention.
Title, category, owner, department, probability (1–5) and impact (1–5). The system computes the risk score as probability × impact.
At closed or realized; issues end at closed after resolution.
Evaluations & recommendations
Formal learning: baseline, process, mid-term, end-line, outcome, impact or thematic evaluations, each closing the loop from findings back into corrective work.
Type, scope (program or project), lead, dates, methodology, budget.
System reminds the lead 7 days and 1 day before the start date.
Findings are recorded against the evaluation; each finding can carry recommendations.
Evaluation at completed; each recommendation at implemented or rejected.
Evaluation follow-up is queryable — every recommendation shows whether the organization actually acted on what it learned.
Reports & the AI analyst
Two ways to consume approved results: fixed snapshots for the record, and conversational analysis for questions.
10.1 · Generating a report
Status generating while the system assembles a frozen snapshot of the approved data — the report never silently changes after the fact.
At generated — a permanent, dated snapshot.
10.2 · Asking the AI analyst
AI answers from a context built exclusively of approved, RLS-scoped data — it sees only what the asking user could see, cites indicator and project codes, shows its arithmetic, and says plainly when the data cannot answer. It has no tools and no write access; it can inform decisions, never make them.
Notifications & reminders
The engine that makes the system actively manage the M&E cycle. Every notification is delivered in-app and by email, governed by an organization-level matrix and personal preferences.
11.1 · What fires, and to whom
| Event | Recipients | Timing |
|---|---|---|
| Reporting period opened | Submitters in affected departments | Immediate |
| Submission awaiting review / approval | Department head, then each stage’s permission holders | Immediate |
| Submission returned / approved | Submitter | Immediate |
| Submission due / overdue | Escalation ladder (ch. 07 table) | Daily sweep |
| Indicator at risk / off track | Responsible officer (+ head when red) | On approval |
| High risk identified (score ≥ 15) | Risk owner + department head | Immediate |
| Corrective action due / overdue | Escalation ladder | Daily sweep |
| Milestone approaching / overdue | Owner, then owner + head | Daily sweep |
| Evaluation starting soon | Evaluation lead | Daily sweep (−7, −1) |
| Evidence verification decided | Evidence uploader | Immediate |
| System announcement | As addressed | Immediate |
11.2 · How a notification travels
Workflow events fire instantly from database triggers. The sweep runs every morning (06:00 in-database, with a 06:30 cloud follow-up that also sends the emails) and walks every due date against the escalation ladders. Deduplication guarantees at most one reminder per person per record per day.
Order of precedence: the organization’s settings matrix (per type: email on/off, in-app on/off) → the person’s own preferences (Notifications page) → delivery. No preference recorded means both channels on.
Every email’s journey ends in a terminal state visible in the delivery history.
Administrators see the full history with stat tiles under Administration → Notifications, can edit templates with live preview, adjust the matrix and ladders, and run the engine on demand (“Run engine now”). Failed sends can be diagnosed from the recorded error.
Administration & audit trail
The configuration that shapes every workflow above, and the record that outlives all of them.
| Screen | Who | What it governs |
|---|---|---|
| Users & Roles | System Administrator | Invitations, activation, role grants — chapter 01 |
| Departments / Organization structure | System Administrator | Department tree, unit-to-department roll-up, department heads (who receive escalations and first-line reviews) |
| Workflows | System Administrator | The approval pipeline per entity type: ordered stages, each requiring a permission — this defines who approves at each stage of chapter 05. With no stages configured, first approval is final. A rejection at any stage returns to the submitter. |
| Reporting Periods | M&E Administrator | Create, open, close — the clock of chapter 05 |
| RAG Configuration | M&E Administrator | Threshold bands and per-indicator overrides; recomputes non-approved results only |
| Notifications | M&E / System Administrator | Settings matrix, escalation ladders, email templates, delivery history, run-now — chapter 11 |
| System Settings | System Administrator | Organization profile and platform options |
| Audit Trail | Auditor / System Administrator (read-only) | The immutable log below |
12.1 · The audit trail — where every process ends up
Every create, update and soft delete on governed records; every workflow event with its actor, stage and comment; every RAG override with its reason; every verification decision with its note; every administrative reopen. Audit rows cannot be edited or deleted — the database refuses. Evidence files are soft-deleted only: the record of what was uploaded, by whom, and what the AI and the reviewer concluded about it, is permanent.
It doesn’t. That is the point.