# WorkTenant System Walkthrough and Demo Guide

This guide explains WorkTenant in a way you can use when training users, presenting the system, or testing it with realistic organizations.

WorkTenant is a multi-tenant execution and reporting platform. In plain terms: one platform hosts many organizations, each organization creates departments, users, programs, projects, outputs, indicators, work items, updates, evidence, risks, dashboards, and reports.

## 1. The Whole System in One Story

A super admin registers an organization. The organization admin sets up departments and users. Project managers create programs and projects. They break each project into outputs, indicators, and work items. Contributors receive assignments, submit progress updates, add comments, and upload evidence. The system then turns those rows into dashboards, risk signals, forecasts, notifications, and exportable reports.

Example:

Bindura State University wants to modernize its student registration process. In WorkTenant, the university is the organization. The ICT department is a department. "Digital Student Services" is a program. "Online Registration Portal" is a project. "Portal launched for semester intake" is an output. "Students registered online" is an indicator. "Configure payment gateway" is a work item. The assigned ICT officer submits an update saying the gateway is 60% configured, attaches evidence, and the project dashboard recalculates progress and risk.

## 2. Main Workspaces

The frontend lives under `appl`.

| Workspace | Typical URL | Users | Purpose |
| --- | --- | --- | --- |
| Login hub | `/appl` | All users | Signs in and routes users based on role. |
| Platform admin | `/appl/admin/dashboard` | `super_admin` | Manages all tenant organizations and platform analytics. |
| Organization admin | `/appl/organization/{slug}/dashboard` | `organization_admin`, `project_manager` | Manages one organization's users, departments, programs, projects, and analytics. |
| Structure / organogram | `/appl/organization/{slug}/structure` | `organization_admin` | Defines positions such as Director and Manager, then assigns users to them. |
| M&E dashboard | `/appl/organization/{slug}/me-dashboard` | `monitoring_evaluation`, `organization_admin`, `project_manager` | Tracks indicator quality, measurements, stale data, evidence, outputs, risks, and project health. |
| Member workspace | `/appl/{slug}/dashboard` | `contributor` | Shows assigned projects, work items, updates, and personal reports. |

Seeded default accounts from `DatabaseSeeder`:

| Role | Email | Password |
| --- | --- | --- |
| Super admin | `superadmin@worktenant.com` | `password` |
| Organization admin | `admin@buse.com` | `password` |
| Project manager | `pm@buse.com` | `password` |
| Contributor | `contributor@buse.com` | `password` |

Note: `monitoring_evaluation` users sign in through the admin/organization login flow and are routed to the organization M&E dashboard.

## 3. Roles and What They Do

| Role | Main responsibility | Typical actions |
| --- | --- | --- |
| `super_admin` | Platform owner | Create organizations, view all tenants, run platform reports and analytics. |
| `organization_admin` | Tenant administrator | Manage users, departments, programs, projects, outputs, indicators, work items, escalations, reports. |
| `project_manager` | Delivery manager | Create projects, outputs, indicators, work items, assign work, review dashboards. |
| `monitoring_evaluation` | Measurement and evidence oversight | View indicators, record/review measurements, check stale data, monitor evidence coverage, and review M&E dashboard risks. |
| `contributor` | Delivery team member | View assigned work, submit updates, add evidence, comment, and generate personal contribution reports. |

## 4. Walkthrough by Role

Use this section when someone asks, "What does each user do in the system?"

### Super admin walkthrough

The super admin works at platform level.

1. Signs in through `/appl` or `/appl/admin/login`.
2. Opens the admin dashboard to see platform analytics across all organizations.
3. Creates or edits organizations.
4. Opens an organization profile to view its departments, users, status, and setup health.
5. Generates platform reports.

Real-world explanation:

"The super admin is like the platform operator. They onboard tenants, check which organizations are active, and monitor whether each tenant has departments, users, managers, and projects configured."

### Organization admin walkthrough

The organization admin works inside one tenant.

1. Signs in and lands on `/appl/organization/{slug}/dashboard`.
2. Creates departments.
3. Creates users and assigns roles such as project manager or contributor.
4. Creates programs and may create projects.
5. Reviews organization analytics, risk radar, and reports.
6. Resets user passwords or updates user records when needed.

Real-world explanation:

"The organization admin is the tenant owner. For a university, this could be the registrar or ICT director who controls the university workspace and makes sure the right people can access the right projects."

### Project manager walkthrough

The project manager manages delivery.

1. Signs in through the admin login flow and enters the organization workspace.
2. Creates projects/work containers under a program.
3. Adds outputs and indicators to define success.
4. Creates work items and assigns them to contributors.
5. Adds dependencies where one task blocks another.
6. Reviews project intelligence, Gantt data, linkage maps, stalled work, and risk radar.
7. Raises escalations for risks needing leadership attention.

Real-world explanation:

"The project manager turns strategy into a practical delivery plan: deliverables, metrics, tasks, owners, dates, progress, and risk decisions."

### Contributor walkthrough

The contributor works on assigned tasks.

1. Signs in through `/appl` or the member workspace.
2. Opens assigned projects and work items.
3. Submits progress updates.
4. Adds comments and uploads evidence.
5. Checks notifications for new assignments, blocked work, overdue work, and report-ready messages.
6. Generates a personal contribution report.

Real-world explanation:

"The contributor does not manage the whole project. They update their assigned work so management can see what is moving, what evidence exists, and what is blocked."

### Monitoring and evaluation walkthrough

The `monitoring_evaluation` user signs in through `/appl` or `/appl/organization/{slug}/login` and lands on `/appl/organization/{slug}/me-dashboard`.

Measurement workflow:

1. Open the M&E dashboard.
2. Review stale indicators, missing targets, evidence gaps, and project health.
3. Open the relevant project and record a dated measurement for an indicator.
4. Confirm the indicator current value changes to the latest measurement.
5. Review the changed achievement percentage on the project, program, or M&E dashboard.

Real-world explanation:

"M&E users connect project activity to measured results. They help answer: did the work produce the planned output or outcome?"

## 5. The Data Hierarchy

Read the system from top to bottom like this:

```text
Platform
  Organization
    Departments
    Organization Positions / Organogram
    Users
    Programs
      Work Containers / Projects
        Outputs
          Indicators
            Indicator Measurements
        Work Items
          Assignments
          Updates
          Dependencies
          Output Contributions
          Indicator Contributions
          Attachments
          Comments
        Escalations
    Dashboards, Activity Logs, Notifications, Reports
```

## 6. What Each Row Means

This section is useful when explaining a table row on screen or a row in exported reports.

| Row type | What the row represents | Important fields | Real-world example |
| --- | --- | --- | --- |
| Organization | A tenant using the system | `name`, `slug`, `code`, `type`, `status` | `Bindura State University`, slug `buse-demo`, type `university`. |
| Department | A unit/team inside an organization | `organization_id`, `name`, `code`, `head_user_id` | `ICT Services`, `Finance`, `Student Affairs`. |
| Organization position | A box in the organogram, separate from permission roles | `organization_id`, `department_id`, `parent_position_id`, `title`, `position_type`, `user_id` | `Director of ICT` reports to `Executive Director`; assigned to an existing user. |
| User | A person with a role | `organization_id`, `department_id`, `email`, `role`, `status` | ICT Director as project manager, registrar clerk as contributor. |
| Program | A strategic portfolio of related projects | `organization_id`, `manager_user_id`, `portfolio_weight`, `start_date`, `end_date` | `Digital Student Services`. |
| Work container / project | A managed body of work | `program_id`, `title`, `code`, `priority`, automatic `progress_percent`, `program_weight` | `Online Registration Portal`. |
| Output | A concrete deliverable from a project | `work_container_id`, `title`, `due_date`, `weight`, `status` | `Student portal deployed for registration week`. |
| Indicator | A measurement that proves progress or impact | `output_id`, `baseline_value`, `target_value`, automatic `current_value`, `frequency` | `Online registrations completed`, target `6500`. |
| Indicator measurement | A dated measurement entry | `indicator_id`, `measurement_date`, `actual_value`, `notes` | On `2026-06-05`, `2800` students registered online. |
| Work item | A task or milestone required to deliver the project | `output_id`, `title`, `status`, progress from updates, `item_weight` | `Configure payment gateway`, progress `60%`. |
| Work item assignee | Who is responsible for a work item | `work_item_id`, `user_id`, `assignment_role` | ICT officer assigned as `lead`. |
| Work item update | A progress entry submitted by a user | `progress_percent`, `status_after_update`, `contribution_percent`, `submitted_at` | "Payment gateway sandbox tested; 60% complete." |
| Dependency | A task relationship | `predecessor_work_item_id`, `successor_work_item_id`, `dependency_type`, `lag_days` | "Portal testing cannot finish until payment gateway is ready." |
| Output contribution | How much a task contributes to an output | `work_item_id`, `output_id`, `contribution_percent` | Gateway setup contributes `30%` to portal launch output. |
| Indicator contribution | How much a task contributes to a measured indicator | `work_item_id`, `indicator_id`, `contribution_percent` or `contribution_value` | Data migration contributes to number of students registered online. |
| Attachment | Evidence attached to a project, task, output, indicator, or update | `attachable_type`, `original_name`, `mime_type`, `uploaded_by` | Signed site handover form, screenshot, training register. |
| Comment | Discussion on a project, task, output, indicator, or update | `commentable_type`, `user_id`, `comment` | "Please verify figures before Friday report." |
| Escalation | A management risk requiring action | `severity`, `status`, `assigned_to`, `due_at` | "Supplier delayed server delivery; assigned to project manager." |
| Activity log | Audit-style record of system activity | `user_id`, `subject_type`, `action`, `metadata` | `qa_project_loaded`, `created`, `updated`. |
| Notification | Message delivered to a user | `title`, `body`, `severity`, `read_at` | "New work item assignment" or "Report generated". |
| Report row | Export row from JSON, CSV, XLSX, or PDF report | `section`, metric fields, values | Summary metrics, project rows, risk rows. |

## 7. How the Main Workflow Works

### Step 1: Register or select an organization

The super admin creates an organization with a unique `slug`. The slug drives organization URLs and API lookups.

Example:

```json
{
  "name": "Bindura State University",
  "slug": "bindura-state-university",
  "code": "BSU",
  "type": "university",
  "country": "Zimbabwe",
  "city": "Bindura",
  "status": "active"
}
```

### Step 2: Create departments and users

Departments create structure. Users are attached to an organization and optionally a department. Roles define what they can do.

Example departments:

| Department | Code | Head |
| --- | --- | --- |
| ICT Services | ICT | Project manager |
| Academic Registry | REG | Organization admin |
| Student Finance | FIN | Contributor |

### Step 3: Create a program

A program groups related projects and carries a `portfolio_weight` from `0` to `100`.

Example:

```json
{
  "name": "Digital Student Services",
  "description": "Modernize student registration, payments, and student records.",
  "portfolio_weight": 60,
  "start_date": "2026-05-01",
  "end_date": "2026-12-18",
  "status": "active"
}
```

### Step 4: Create a project / work container

The system calls projects `work_containers` because the same structure can hold projects, initiatives, workstreams, or strategic assignments.

Example:

```json
{
  "container_type": "strategic_project",
  "title": "Online Registration Portal",
  "code": "BSU-REG-2026",
  "priority": "high",
  "status": "active",
  "start_date": "2026-05-04",
  "end_date": "2026-08-28",
  "program_weight": 45,
  "contribution_weight": 45
}
```

Project progress is automatic. It is recalculated from work item progress and item weights, so users do not type project progress during project creation.

### Step 5: Define outputs and indicators

Outputs describe what must be delivered. Indicators prove whether it worked.

Example output:

```json
{
  "title": "Registration portal launched",
  "due_date": "2026-08-14",
  "weight": 50,
  "status": "active"
}
```

Example indicator:

```json
{
  "name": "Students registered online",
  "unit_of_measure": "students",
  "baseline_value": 0,
  "target_value": 6500,
  "frequency": "weekly",
  "data_source": "Student information system"
}
```

Indicator current value is automatic. It comes from the latest recorded measurement.

### Step 6: Create and assign work items

Work items are the actual tasks. Managers assign them to contributors.

Example work item:

```json
{
  "title": "Configure online payment gateway",
  "item_type": "task",
  "category": "payments",
  "priority": "high",
  "status": "todo",
  "planned_start_date": "2026-05-06",
  "planned_end_date": "2026-05-29",
  "estimated_effort": 80,
  "item_weight": 30,
  "milestone_weight": 20
}
```

Work item progress starts at 0 and changes through submitted updates.

Assignment example:

```json
{
  "user_id": 12,
  "assignment_role": "lead"
}
```

When a user is assigned, the notification service creates a notification for that user.

### Step 7: Submit updates and evidence

Contributors submit progress updates. If the update includes `progress_percent`, the work item progress is updated. If it includes `status_after_update`, the work item status is updated.

Example update:

```json
{
  "update_type": "progress",
  "title": "Payment gateway sandbox complete",
  "description": "Bank sandbox credentials configured and first test payment succeeded.",
  "progress_percent": 60,
  "status_after_update": "in_progress",
  "contribution_percent": 20,
  "contribution_weight": 20,
  "contribution_note": "Unlocks integration testing."
}
```

Attachments can be added to work containers, work items, work item updates, outputs, and indicators.

### Step 8: Record indicator measurements

A measurement updates the indicator's `current_value` to the latest actual value.

Example:

```json
{
  "measurement_date": "2026-08-01",
  "actual_value": 2800,
  "notes": "First week of pilot registration."
}
```

### Step 9: Link work to outputs and indicators

Contribution links explain why a task matters.

Example:

```json
{
  "output_id": 4,
  "contribution_percent": 30
}
```

This means the task contributes 30% of the selected output. The system prevents total contribution percentages for the same work item from exceeding 100%.

### Step 10: Add dependencies and escalations

Dependencies protect sequencing. The system rejects self-dependencies and cycles.

Example:

```json
{
  "predecessor_work_item_id": 18,
  "dependency_type": "FS",
  "lag_days": 2
}
```

`FS` means finish-to-start: the predecessor should finish before the successor starts.

Escalations raise risks for leadership attention.

Example:

```json
{
  "escalation_type": "supplier_delay",
  "title": "Payment gateway production approval delayed",
  "description": "Bank production credentials are not yet approved.",
  "severity": "high",
  "status": "open",
  "due_at": "2026-05-20 12:00:00"
}
```

### Step 11: Review dashboards and reports

Dashboards show live intelligence. Reports can export as:

```text
format=json
format=csv
format=xlsx
format=pdf
```

Important report endpoints:

| Report | Endpoint |
| --- | --- |
| Platform | `GET /api/v1/reports/platform` |
| Organization | `GET /api/v1/reports/organizations/{slug}` |
| Program | `GET /api/v1/reports/programs/{program}` |
| Project | `GET /api/v1/reports/projects/{workContainer}` |
| Member | `GET /api/v1/reports/me` |

## 8. How the Intelligence Rows Are Calculated

### Work item rows

Each work item row includes status, progress, assignees, update counts, attachment counts, dependency status, and whether it is stalled.

A work item is considered stalled when it is not complete and it has no recent update in the last 7 days.

### Project rows

A project row is built from all work items, outputs, indicators, dependencies, and updates inside one work container.

Key project row fields:

| Field | Meaning |
| --- | --- |
| `weighted_progress` | Weighted average of work item progress using `item_weight`. |
| `expected_progress` | Time-based expected progress between project start and end date. |
| `schedule_variance` | `weighted_progress - expected_progress`. Positive means ahead of schedule. Negative means behind. |
| `velocity_points_per_day` | Average progress movement from recent updates over a 21-day window. |
| `projected_completion_date` | Forecast date based on current progress and velocity. |
| `direction_signal` | `bullish`, `neutral`, or `bearish` based on schedule variance, recent updates, blocked dependencies, and forecast slip. |
| `dependency_pressure` | Number of unresolved blocking dependency links. |
| `health_score` | 0 to 100 score based on progress, completed items, blocked items, stalled items, and recent update activity. |
| `health_band` | `Strong`, `Stable`, `Watch`, or `At Risk`. |

### Simple calculation example

Assume a construction project has three tasks:

| Task | Weight | Progress |
| --- | ---: | ---: |
| Foundation work | 60 | 40% |
| Dependent rollout | 30 | 25% |
| Reporting close-out | 10 | 90% |

Weighted progress:

```text
(40 x 60%) + (25 x 30%) + (90 x 10%) = 40.5%
```

If the project should be 50% complete by today's date, schedule variance is:

```text
40.5 - 50 = -9.5
```

That negative variance can push the direction signal toward `bearish`, especially if updates are stale or a dependency is blocked.

### Program rows

A program row rolls up the project rows inside that program. It uses `program_weight` on each project to calculate program progress and forecast.

Example: if a program has two projects:

| Project | Program weight | Weighted progress |
| --- | ---: | ---: |
| Online Registration Portal | 45 | 60% |
| Student Finance Integration | 55 | 30% |

Program progress:

```text
(60 x 45%) + (30 x 55%) = 43.5%
```

### Organization rows

An organization row rolls up all project rows inside that organization. It counts departments, users, programs, projects, outputs, indicators, and work items. It also averages progress, health, and contribution signals.

### Report rows

Exported reports are flattened into rows. Summary metrics appear under the `Summary` section. Then the report includes section rows such as `Programs`, `Projects`, `Work Items`, `Outputs`, `Indicators`, and `Risk Radar`.

## 9. Five Organization Example Sets

Use these examples as realistic test cases. Dates are after April 28, 2026 so they satisfy the current validation rules for new records.

### Example Set 1: University

Organization:

| Field | Value |
| --- | --- |
| Name | Bindura State University |
| Slug | `bindura-state-university` |
| Code | `BSU` |
| Type | `university` |
| City | Bindura |

Departments and users:

| Department | User | Role |
| --- | --- | --- |
| Academic Registry | Registrar Admin | `organization_admin` |
| ICT Services | Digital Services Manager | `project_manager` |
| Student Finance | Fees Officer | `contributor` |
| Student Affairs | Student Support Officer | `contributor` |

Program and project:

| Level | Name |
| --- | --- |
| Program | Digital Student Services |
| Project | Online Registration Portal |
| Output | Registration portal launched |
| Indicator | Students registered online, target `6500`, weekly |

Work items:

| Work item | Weight | Assignee | Test update |
| --- | ---: | --- | --- |
| Configure online payment gateway | 30 | Fees Officer | 60%, `in_progress` |
| Import continuing student records | 40 | Digital Services Manager | 45%, `in_progress` |
| Run student pilot support desk | 30 | Student Support Officer | 20%, `in_progress` |

Expected demo result:

The project dashboard should show partial progress, several in-progress items, indicator achievement below target, and a useful risk conversation if payment gateway approval is delayed.

Test cases:

1. Create the organization and departments.
2. Create the program and project.
3. Add the output and indicator.
4. Assign the three work items.
5. Submit one progress update and one measurement: `2800` students registered.
6. Export the project report as PDF and the organization report as CSV.

### Example Set 2: Construction Company

Organization:

| Field | Value |
| --- | --- |
| Name | Atlas Civil Contractors |
| Slug | `atlas-civil-contractors` |
| Code | `ACC` |
| Type | `construction_company` |
| City | Harare |

Departments and users:

| Department | User | Role |
| --- | --- | --- |
| Projects Office | Contracts Director | `organization_admin` |
| Site Engineering | Site Project Manager | `project_manager` |
| Procurement | Procurement Officer | `contributor` |
| Health and Safety | Safety Officer | `contributor` |

Program and project:

| Level | Name |
| --- | --- |
| Program | Urban Infrastructure Delivery |
| Project | Mbare Clinic Renovation Phase 1 |
| Output | Renovated outpatient wing handed over |
| Indicator | Rooms renovated, target `12`, weekly |

Work items:

| Work item | Weight | Assignee | Test update |
| --- | ---: | --- | --- |
| Complete site survey and setting out | 20 | Site Project Manager | 100%, `completed` |
| Procure roofing sheets and ceiling boards | 30 | Procurement Officer | 35%, `in_progress` |
| Complete foundation and slab repairs | 35 | Site Project Manager | 40%, `in_progress` |
| Conduct safety induction and PPE checks | 15 | Safety Officer | 80%, `in_progress` |

Dependency test:

Make "Complete foundation and slab repairs" depend on "Complete site survey and setting out" using dependency type `FS`.

Expected demo result:

Because the survey is complete, the dependency should not block the slab repair task. If you change the survey to `in_progress`, the project risk radar should show blocked dependency pressure.

### Example Set 3: NGO

Organization:

| Field | Value |
| --- | --- |
| Name | Community Health Reach Trust |
| Slug | `community-health-reach-trust` |
| Code | `CHRT` |
| Type | `ngo` |
| City | Masvingo |

Departments and users:

| Department | User | Role |
| --- | --- | --- |
| Programs | Country Program Lead | `organization_admin` |
| Field Operations | Outreach Manager | `project_manager` |
| Monitoring and Evaluation | M&E Officer | `monitoring_evaluation` |
| Community Mobilization | Field Officer | `contributor` |

Program and project:

| Level | Name |
| --- | --- |
| Program | Maternal Health Outreach |
| Project | Rural Antenatal Care Campaign |
| Output | Mobile clinic outreach completed in target wards |
| Indicator | Pregnant women reached, target `2500`, monthly |

Work items:

| Work item | Weight | Assignee | Test update |
| --- | ---: | --- | --- |
| Train village health workers | 25 | Outreach Manager | 70%, `in_progress` |
| Schedule mobile clinic visits | 25 | Field Officer | 50%, `in_progress` |
| Capture beneficiary records | 30 | M&E Officer | 40%, `in_progress` |
| Submit district coordination report | 20 | Country Program Lead | 10%, `todo` |

Measurement test:

Record indicator measurement `850` women reached on `2026-06-30`.

Expected demo result:

The indicator achievement should show `34%` because `850 / 2500 x 100 = 34%`. The organization analytics should highlight progress but also show remaining delivery pressure.

### Example Set 4: Government Ministry

Organization:

| Field | Value |
| --- | --- |
| Name | Ministry of Local Government and Public Works |
| Slug | `ministry-local-government-public-works` |
| Code | `MLGPW` |
| Type | `government_ministry` |
| City | Harare |

Departments and users:

| Department | User | Role |
| --- | --- | --- |
| Permanent Secretary Office | Ministry Admin | `organization_admin` |
| Infrastructure Planning | Infrastructure Program Manager | `project_manager` |
| Provincial Coordination | Provincial Officer | `contributor` |
| Finance and Procurement | Procurement Analyst | `contributor` |

Program and project:

| Level | Name |
| --- | --- |
| Program | District Service Centre Upgrade |
| Project | Gweru District Office Solar Backup |
| Output | Solar backup system commissioned |
| Indicator | Backup power hours available per day, target `8`, weekly |

Work items:

| Work item | Weight | Assignee | Test update |
| --- | ---: | --- | --- |
| Approve technical specifications | 20 | Infrastructure Program Manager | 100%, `completed` |
| Complete procurement evaluation | 30 | Procurement Analyst | 45%, `in_progress` |
| Prepare district site for installation | 25 | Provincial Officer | 35%, `in_progress` |
| Commission solar backup system | 25 | Infrastructure Program Manager | 0%, `todo` |

Escalation test:

Create a high-severity escalation called `Tender evaluation delay` assigned to the Infrastructure Program Manager.

Expected demo result:

The assignee receives a notification and email. Organization analytics should place this project in the risk radar if progress is low or blocked.

### Example Set 5: Bank

Organization:

| Field | Value |
| --- | --- |
| Name | ZimTrust Bank |
| Slug | `zimtrust-bank` |
| Code | `ZTB` |
| Type | `bank` |
| City | Harare |

Departments and users:

| Department | User | Role |
| --- | --- | --- |
| Digital Banking | Digital Banking Admin | `organization_admin` |
| Core Banking IT | Core Systems Manager | `project_manager` |
| Risk and Compliance | Compliance Officer | `contributor` |
| Branch Operations | Branch Rollout Officer | `contributor` |

Program and project:

| Level | Name |
| --- | --- |
| Program | Digital Channels Modernization |
| Project | Mobile Banking KYC Upgrade |
| Output | KYC upgrade released to mobile banking users |
| Indicator | KYC completion rate, target `95`, daily |

Work items:

| Work item | Weight | Assignee | Test update |
| --- | ---: | --- | --- |
| Update customer verification workflow | 35 | Core Systems Manager | 55%, `in_progress` |
| Validate compliance rules | 25 | Compliance Officer | 30%, `in_progress` |
| Pilot mobile app release with 3 branches | 25 | Branch Rollout Officer | 10%, `todo` |
| Prepare go-live risk signoff | 15 | Compliance Officer | 0%, `todo` |

Contribution test:

Link "Validate compliance rules" to the output at `25%` and to the indicator at `30%`.

Expected demo result:

The linkage map should show the compliance task connected to both the output and the KYC completion indicator. Any work item without output or indicator contribution should appear as an orphan work item in the linkage map.

## 10. Universal Test Walkthrough for Any Organization

Use this repeatable flow for any of the five organizations above.

1. Log in as super admin.
2. Create the organization.
3. Create at least three departments.
4. Create one organization admin, one project manager, and two contributors.
5. Log in as the organization admin or project manager.
6. Create one program with `portfolio_weight` between `0` and `100`.
7. Create one project with `program_weight` between `0` and `100`.
8. Create one output and one indicator.
9. Create three or four work items with weights totaling any positive number.
10. Assign the work items to contributors.
11. Log in as a contributor.
12. Submit a progress update with `progress_percent` and `status_after_update`.
13. Add a comment and upload an evidence attachment.
14. Log back in as manager.
15. Add output and indicator contribution links.
16. Add a dependency between two work items.
17. Record one indicator measurement.
18. Create one escalation if there is a risk.
19. Open project intelligence and organization analytics.
20. Export reports in JSON, CSV, XLSX, and PDF.

## 11. Expected Results to Check

| Test | Expected result |
| --- | --- |
| Contributor assigned to task | Contributor receives a notification. |
| Contributor submits update | Work item progress changes to submitted `progress_percent`. |
| Update includes `status_after_update` | Work item status changes to that value. |
| Indicator measurement is recorded | Indicator `current_value` changes to latest measurement value. |
| Work item linked to outputs | Linkage map shows the task under the selected output. |
| Work item linked to indicators | Linkage map shows the task under the selected indicator. |
| Dependency creates a cycle | API rejects with `This dependency would create a cycle.` |
| Report generated | Requester receives `Report generated` notification. |
| Project has stale or blocked tasks | Risk radar ranks those tasks higher. |
| No output/indicator links | Work item appears under `orphan_work_items` in the linkage map. |

## 12. Common API Paths for Testing

All authenticated paths are under:

```text
/api/v1
```

Login:

```text
POST /auth/admin/login
POST /auth/client/login
POST /auth/forgot-password
POST /auth/verify-reset-code
POST /auth/reset-password
GET /me
POST /logout
```

Setup:

```text
GET/POST /organizations
GET/POST /departments
GET/POST /users
POST /users/reset-password
GET/POST /organization-positions
GET/POST /programs
GET/POST /work-containers
```

Delivery:

```text
GET/POST /outputs
GET/POST /indicators
GET/POST /indicators/{indicator}/measurements
GET/POST /work-items
POST /work-items/{workItem}/assign
GET/POST /work-items/{workItem}/updates
GET/POST /work-items/{workItem}/dependencies
POST /work-items/{workItem}/output-contributions
POST /work-items/{workItem}/indicator-contributions
```

Collaboration:

```text
GET/POST /attachments/{type}/{id}
GET/POST /comments/{type}/{id}
GET/POST /escalations
GET /notifications
GET /activity-logs
```

Intelligence and reports:

```text
GET /dashboard/summary
GET /dashboard/member-summary
GET /dashboard/admin-analytics
GET /dashboard/organization/{slug}
GET /dashboard/monitoring-evaluation/{slug}
GET /dashboard/programs/{program}
GET /dashboard/programs/token/{token}
GET /dashboard/work-containers/{workContainer}
GET /dashboard/work-containers/token/{token}
GET /reports/platform
GET /reports/organizations/{slug}
GET /reports/programs/{program}
GET /reports/programs/token/{token}
GET /reports/projects/{workContainer}
GET /reports/projects/token/{token}
GET /reports/me
```

## 13. How to Explain WorkTenant to Stakeholders

Use this simple explanation:

"WorkTenant helps an organization connect strategy to execution. At the top, we register the organization and its teams. Then we define programs and projects. Each project has outputs, indicators, and tasks. Staff update tasks with evidence. The system calculates progress, forecasts completion, identifies blocked or stale work, and produces reports for management."

For executives:

"It gives leadership a portfolio dashboard: which organizations, programs, and projects are healthy, which are behind schedule, and where action is needed."

For project managers:

"It gives managers a delivery cockpit: tasks, assignees, dependencies, outputs, indicators, evidence, and escalations in one place."

For contributors:

"It gives team members a clear list of assigned work and a simple way to report progress with evidence."

For M&E teams:

"It connects activities to indicators, so outputs and outcomes can be measured rather than only described."

## 14. Current Implementation Notes

These notes help you explain current behavior accurately:

1. Status values are mostly free text, but the UI expects common values such as `active`, `draft`, `todo`, `in_progress`, `completed`, `blocked`, and `on_hold`.
2. Percent and weight fields are generally validated from `0` to `100`.
3. New program, project, and planned task start dates are validated against the current date, so use future dates when manually creating records.
4. Reports support JSON, CSV, XLSX, and PDF.
5. Attachments are limited to 20 MB per upload.
6. Work item dependency types accepted by the API are `FS`, `SS`, `FF`, and `SF`.
7. The current user creation flow emails onboarding credentials.
8. The current system uses hard deletes rather than soft deletes.
9. Some older test/report documents in the repo may describe previous issues; this guide reflects the current code read in this workspace.