Pindah Basa / Operations

Standard Operating Procedure

End-to-end system operation from organisation registration through logout — every activated module in Operations.API and operations.ui.

Document

Operations SOP

Version

1.0

Last updated

2026-08-05

Classification

Internal — operators & implementers

Audience

IT, finance, warehouse, clinical, school, sales, insurance

Owner

Pindah · pindah.org

Table of Contents

1. Purpose and Audience
2. System Overview
3. Prerequisites and Environment
4. Phase 0 — Registration and Organisation Bootstrap
5. Phase 1 — Authentication and Session Management
6. Phase 2 — Core Platform (Always Active)
7. Phase 3 — Module Activation and Dependencies
8. Module SOPs
   • 8.1 Inventory & Stock
   • 8.2 Accounting & Sales
   • 8.3 Procurement
   • 8.4 Pharmacy
   • 8.5 Hospital / Clinic (HMS)
   • 8.6 School (Frame)
   • 8.7 HR & Payroll
   • 8.8 CRM
   • 8.9 Insurance
   • 8.10 Logistics
   • 8.11 Agriculture & Feed
   • 8.12 Projects
   • 8.13 Documents (DMS)
   • 8.14 Forms & Surveys
   • 8.15 Asset Management
9. Cross-Module Business Workflows
10. Shared Tools (Chat, Mobile Scanner, Analyst, Guides)
11. Phase Final — Logout and Session End
12. Global Testing Matrix
13. Global Error Catalogue and Fixes
14. Appendices

1. Purpose and Audience

1.1 What this document is

This SOP is the single reference for operating Pindah Basa (branded UI: operations.ui) backed by Operations.API (.NET 8). It describes:

• What each feature is and why it exists
• Where it lives in the UI (route) and API
• Which other modules depend on it or consume its data
• Step-by-step workflows with prerequisites
• How to verify correct behaviour (test steps)
• Known errors, glitches, and remediation

1.2 Who should use this

1.3 Conventions used

2. System Overview

2.1 Architecture

Browser (operations.ui — Angular 20)
  → AuthInterceptor (JWT Bearer)
  → Operations.API (.NET 8 modular monolith)
  → FilteredDbContext (multi-tenant SQL Server)
  → Integrations (Paynow, WhatsApp, AI, R2, Traccar, SignalR)

2.2 Deployment modes

2.3 Module catalogue

2.4 Shared master data

3. Prerequisites and Environment

3.1 Before any user can work

3.2 Environment URLs

3.3 Browser and client requirements

• Modern Chromium, Firefox, or Safari (latest two versions)
• JavaScript enabled; cookies/localStorage for JWT
• For POS: stable network to API; optional desktop print bridge at http://127.0.0.1:17890
• For mobile scanner: phone on same network; SignalR hub /hubs/barcode-scan

4. Phase 0 — Registration and Organisation Bootstrap

4.1 What it is

Organisation registration creates a new tenant: database row for organisation, default roles (Administrator, Manager, Viewer), seed permissions, and an owning admin user. This is the entry point for every new customer.

4.2 Registration paths

4.3 Self-registration workflow

Prerequisites: Registration enabled; valid email; organisation name not duplicate (policy-dependent).

Steps:

1. Navigate to /register.
2. Enter organisation name, admin name, email, password.
3. Submit — API creates org, admin user, default roles.
4. Check email for confirmation link → /email-confirmation.
5. Click confirmation link; email verified.
6. Go to /login; sign in with credentials.
7. Land on /dashboard (or till-selection if POS configured).

Business rules:

• Organisation receives real identity immediately (not a temp org code).
• Administrator role gets all permissions auto-synced.
• Business document numbers use real prefixes from first create in each module.

Test — registration happy path:

Errors and fixes:

4.4 Accept invite workflow

Prerequisites: Valid invite token from admin (/organisation/users or HR invite).

Steps:

1. Open link /accept-invite/:token.
2. Complete profile and password.
3. Sign in.

Test: Invite email → accept → login → permissions match assigned role.

Errors:

4.5 Post-registration bootstrap checklist (administrator)

Execute in order after first login:

5. Phase 1 — Authentication and Session Management

5.1 What it is

Authentication establishes identity via JWT access token (60 min) + refresh token (7 days). Authorization uses role permissions and module activation middleware on the API.

5.2 Login methods

5.3 Login workflow

Prerequisites: Active user; confirmed email (if required); org not suspended.

Steps:

1. Open /login.
2. Enter email and password (or Google sign-in).
3. If 2FA required → /two-factor-verify → enter TOTP / email OTP / recovery code.
4. AuthService stores JWT + refresh in localStorage.
5. App calls GET /api/users/me and GET /api/organisations/current.
6. PermissionService loads permissions.
7. If POS user without till → /organisation/location-and-till (tillSelectionPageGuard).
8. Redirect to returnUrl or preferred dashboard.

Session lifecycle (automatic):

• AuthInterceptor attaches Authorization: Bearer {token}.
• Proactive refresh when < 5 minutes to expiry.
• 401 → refresh and retry once; failure → logout.
• session-timeout.service warns on idle; can force logout.

Test — login:

5.4 Two-factor authentication

Errors:

5.5 Password reset

Route: /password-reset
API: POST /api/auth/forgot-password → email link → reset form

Test: Request reset → email link → new password → login succeeds.

5.6 Permissions model

• Format: module:controller:operation (e.g. sales:invoices:create)
• Wildcards: *:*:* (super), stock:*:*, stock:inventory:*
• Default roles: Administrator (all), Manager (no deletes), Viewer (view only), Student (school self-service)
• Source of truth: wwwroot/default-permissions.md + database role assignments
• UI mapping: operations.ui/src/app/config/permission-config.ts

Refresh permissions after role change: Profile menu → Refresh permissions (or re-login).

6. Phase 2 — Core Platform (Always Active)

6.1 Dashboard

What it is: Role-based home screen with widget shortcuts to active modules.

Used by: All authenticated users.
Requires: core module (always on).

Test: Login as admin → widgets match activated modules. Login as viewer → no create buttons on widgets.

6.2 Organisation settings

What it is: Tenant administration — profile, modules, users, roles, billing, security, branch sync.

Cross-module impact: Module toggles immediately affect sidebar and API access. Periods drive School and financial reporting.

Test — module activation:

1. Deactivate Stock in /organisation/modules.
2. Refresh permissions.
3. Verify Stock menu hidden; GET /api/products returns 403.
4. Re-activate; menu returns.

Errors:

6.3 Account settings (personal)

Route: /account/settings
What it is: User profile, password, display preferences, theme.

Test: Change password → logout → login with new password.

6.4 Guides & Help

Route: /guides
What it is: In-app documentation browser.

6.5 Notifications

Route: /notifications
API: Notification endpoints
What it is: System alerts (stock, approvals, subscriptions).

6.6 Global search

Location: Header
What it is: Search routes and entities across modules.

7. Phase 3 — Module Activation and Dependencies

7.1 Activation order (recommended)

core (automatic)
  → inventory
    → accounting
      → procurement | pharmacy | clinic | insurance
  → hr | crm | school | projects | documents | forms | assets | logistics
  → agriculture (needs inventory)

7.2 Dependency enforcement

7.3 Till selection prerequisite

Route: /organisation/location-and-till
Guard: tillSelectionPageGuard
When: User has POS permissions but no till selected in session.
Test: Clear till session → navigate to POS → redirected to till selection → select → POS loads.

8. Module SOPs

8.1 Inventory & Stock

What it is

Product catalogue, warehouses, suppliers, receiving, stock takes, transfers, pricing, tills, and movement audit. Foundation for retail, pharmacy, clinic supplies, and agriculture.

Where it is used

Routes reference

Permissions: stock:inventory:*, stock:receipts:*, stock:stocktake:*, stock:transfers:*, pos:tills:*

Workflow A — New product setup

Prerequisites: Categories, locations, optionally suppliers.

1. /stock/add → enter name, SKU, category, cost, sell price, reorder level.
2. Set opening quantity per location.
3. Save → product appears in /stock/inventory/list.

Test: Search product in list; quantity matches opening stock; audit log shows opening entry.

Workflow B — Receive stock from supplier

Prerequisites: Supplier, location, products exist.

1. /stock/orders/create or receive against existing PO.
2. Select supplier, location, supplier invoice number.
3. Add lines with quantities and costs.
4. Post as Received → quantities increase.

Test: Product qty ↑; audit log type = Receipt; cost updated.

Workflow C — Stock take

Prerequisites: Location defined; products with stock.

1. /stock/stocktakes → New → scope location/category.
2. /stock/stocktakes/:id/count → enter counted qty (or scan barcodes).
3. Submit for approval → approver completes → system qty adjusts.

Test: Variance report matches manual calculation; status = Completed.

Workflow D — Stock transfer

Prerequisites: Two locations with tills; stock at source.

1. /stock/transfers/create → source/destination, receiver, lines.
2. Approver: Approve & Dispatch → status In Transit; source qty ↓.
3. Receiver: Confirm Receipt → destination qty ↑.

Test: Audit shows transfer out/in; balances correct at both locations.

Workflow E — Price change approval

Prerequisites: Markup rules or manual price change on receipt.

1. Change triggers request → /stock/inventory/price-approvals.
2. Manager approves or rejects.

Test: Approved price visible on product; rejected price unchanged.

Errors and fixes

8.2 Accounting & Sales

What it is

General ledger, POS, invoices, quotations, purchase orders (financial), customers, payments, expenses, bank import, financial statements.

Where it is used

Routes reference

Permissions: accounting:*, sales:*, pos:sales:*

Workflow A — Initial accounting setup

Prerequisites: Admin access.

1. Create/import chart of accounts.
2. Map System Cash account.
3. Add currencies, payment methods, fees/taxes, banks.
4. Add customers.
5. Test: Record Payment → check journal entry → trial balance balances.

Workflow B — POS sale

Prerequisites: Till selected; products with stock at till location; payment methods.

1. /accounting/sales/create.
2. Select customer (or walk-in).
3. Add products (search/scan).
4. Apply taxes/discounts.
5. Select payment method; complete sale.
6. Receipt prints; stock deducts.

Test: Sale in /accounting/sales/list; stock qty ↓; run Consolidate on dashboard → journal entry created.

Workflow C — Invoice (credit sale)

Prerequisites: Customer; products/services.

1. /accounting/invoices/create → customer, dates, lines.
2. Save as Pending → real INV- number assigned at create.
3. Email PDF to customer.
4. When paid: Make Payment → status Paid/Partial.

Test: Balance column correct; receivables aging on dashboard updates.

Workflow D — Month-end consolidate

Prerequisites: POS sales in period.

1. /accounting/dashboard → Consolidate for date range.
2. Review new journal entries.
3. Run trial balance, income statement, balance sheet.

Test: Debits = credits; revenue matches sales register.

Errors and fixes

8.3 Procurement

What it is

Source-to-pay: requisitions, approvals, RFQs, supplier invoices with 3-way match, supplier payments.

Dependencies

inventory, accounting — uses Stock suppliers/GRN and Accounting POs.

Routes reference

Cross-routes: PO → /accounting/purchase-orders; GRN → /stock/orders/receive; suppliers → /stock/suppliers.

Workflow — Full procure-to-pay

Prerequisites: Suppliers, products, approval rules, chart of accounts.

PR (draft) → submit → approve
  → convert to PO (/accounting/purchase-orders) OR RFQ (/procurement/rfqs)
  → award supplier
  → goods arrive → receive (/stock/orders/receive)
  → supplier invoice (/procurement/supplier-invoices) — 3-way match
  → approve → payment (/procurement/payments)

Test each gate:

Errors:

8.4 Pharmacy

What it is

Dispensary operations: quick dispense, verification queue, refills, medical aid claims, labels, optional POS payment.

Dependencies

inventory, accounting, pharmacy module; patients from Clinic or Accounting customers.

Routes reference

Workflow — Dispense to payment

Prerequisites: Location/till; products with batch stock; dosage cyphers; payment methods.

1. /pharmacy/dispense → select location, patient.
2. Review allergy alerts.
3. Add medicine lines (FEFO batch auto-selected).
4. Attach prescription script image (per policy).
5. Save & Print → real RX- number; stock deducts; status Dispensed.
6. Payment modal → collect or skip.
7. Queue: Verify → Collected → Paid.

Test:

Errors:

8.5 Hospital / Clinic (HMS)

What it is

Hospital Management System: patients, appointments, EMR encounters, lab, inpatient, billing claims, admin master data. Menu label: Hospital; route prefix /clinic.

Dependencies

inventory, accounting; facility type in Organisation.custom_args.healthcare_facility_type controls feature set (clinic, hospital, surgery_center, dental, multi_specialty).

Menu structure (6 areas)

Workflow — Outpatient visit (happy path)

Prerequisites: Medical aid societies (if applicable); staff users; products for dispensing.

1. Register patient /clinic/patients → New → demographics, allergies, medical aid.
2. Book appointment /clinic/appointments.
3. Encounter /clinic/emr/encounters → vitals, notes, diagnosis.
4. Prescription /clinic/patients/:id/prescriptions/new.
5. Pharmacy /pharmacy/dispense → same patient.
6. Bill /accounting/invoices or collect at dispense.
7. Medical aid claim /pharmacy/medical-aid-claims or /clinic/billing/insurance-claims.

Test: Patient chart shows linked encounter, prescription, invoice; balances correct.

Known gaps and workarounds (documented in hms_frontend_workflows.md)

When testing Clinic: Prefer Patient Directory, Appointments, Encounters, Quick Dispense, Invoices, Medical Aid Claims. Avoid OR/Surgery unless verified on your API version.

Errors:

8.6 School (Frame)

What it is

School management for Zimbabwe primary/secondary: students, stages/classrooms, assessments, marks, report cards, attendance, e-learning. Menu label: Frame.

Dependencies

Organisation periods; HR for staff; optional Accounting for fees.

Routes reference

Workflow — Term assessment to report card

Prerequisites: Periods (/organisation/periods); stages/classrooms; subjects; grading scales.

1. Create period (e.g. 2026 – Term 1).
2. /school/grading/stages → define forms/grades and classrooms.
3. /school/subjects → subject catalogue.
4. /school/students/create → enrol; assign classroom.
5. /school/assessments/create → link subject, stage, period.
6. /school/assessments/marks → enter scores.
7. /school/reports → generate report cards → Sync Marks → Refresh Grades → PDF.

Student login workflow:

1. Admin creates student → activation email.
2. Student opens /activate-student/:token → set password.
3. Student logs in → /school/student-profile/dashboard.

Test:

Errors:

8.7 HR & Payroll

What it is

Employee records, invites, user groups, payroll, pay periods, performance scorecards, timetables, onboarding/offboarding, announcements.

Routes reference

Workflow — Hire to payroll

1. /hr/users/invite-users → email invite.
2. User accepts → appears in /hr/users.
3. Assign role at /organisation/roles.
4. /hr/payroll/pay-periods → create period.
5. /hr/payroll/add → run payroll for period.

Test: Invite → accept → user in list → payroll line generated.

Cross-module: School /school/staff reuses UsersListComponent. Clinic clinical staff are users with clinic permissions.

8.8 CRM

What it is

Leads, opportunities, pipeline, accounts, contacts, cases, campaigns, quotes, forecasts, knowledge base, portals.

Routes reference (selected)

Workflow — Lead to sale

1. /crm/leads/create → capture lead.
2. Qualify → convert to opportunity.
3. /crm/opportunities → move through pipeline stages.
4. /crm/quotes/create → send quote.
5. On win → create Accounting quotation/invoice with same customer.

Test: Lead count on dashboard ↑; opportunity stage changes persist; quote PDF generates.

8.9 Insurance

What it is

Full insurance lifecycle: submissions, quotes, placements, policies, endorsements, renewals, claims, reinsurance, regulatory, client money, commissions.

Dependencies

core, accounting; documents module recommended for policy files.

Entity creation order (mandatory)

Submission → Quote → Placement → Policy
  → Endorsement (on active policy)
  → FNOL → Claim → Reserves → Claim Payment

Policy versions are immutable; endorsements create new versions.

Routes reference (selected)

Workflow — New business to policy

1. Create submission with risk items.
2. Generate/compare quotes.
3. Record placement when market binds.
4. Issue policy from placement.
5. Premium posts to accounting (per integration setup).

Workflow — Claim

1. FNOL → claim record.
2. Set reserves.
3. Adjudicate → claim payment.
4. Update loss ratio on dashboard.

Test: Cannot create policy without placement; endorsement blocked on cancelled policy; commission statement totals match payments.

Errors:

8.10 Logistics

What it is

Fleet management: drivers, vehicles, trips, live monitoring (Traccar GPS integration).

Routes reference

Workflow — Delivery trip

1. Create vehicle and driver.
2. /logistics/trips → plan stops, assign driver/vehicle.
3. Start trip → monitor on /logistics/trips/monitor.
4. Complete trip → review summary.

Test: Trip appears on map; status transitions; links to CRM customers if used.

Cross-module: Pharmacy Home Delivery uses Logistics trips (when delivery module enabled).

8.11 Agriculture & Feed

What it is

Feed formulation: nutrients, raw materials (from stock), nutrient matrix, formulas, generation reports.

Dependencies

inventory for raw materials (/agriculture/raw-materials → stock products).

Routes reference

Workflow — Create feed formula

1. Define nutrients.
2. Map raw materials (inventory products) in nutrient matrix.
3. /agriculture/formulas/create → ingredients + targets.
4. Generate report → review nutritional analysis.

Test: Formula saves; report calculates nutrient totals; raw material costs pull from stock.

8.12 Projects

What it is

Project tracking, issues (list + kanban), job cards, field job cards.

Routes reference

Workflow — Job card

1. Create project.
2. /projects/job-cards/create → work order details.
3. Complete → issue closed.

Test: Job card PDF; linked issues update status.

8.13 Documents (DMS)

What it is

Document management: cabinets, folders, uploads, approvals, workflows, share links, OnlyOffice viewing.

Routes reference

Public route (no auth): /share/:token → view shared document.

Workflow — Document approval

1. Upload to folder.
2. Workflow triggers → appears in /documents/approvals.
3. Approver signs off → status approved.

Test: Share link works in incognito; expiry alerts on dashboard.

8.14 Forms & Surveys

What it is

Form builder, published public forms, response collection.

Routes reference

Public route (no auth): /f/:publicId

Workflow

1. /forms/create → design fields → publish → copy public link.
2. Respondent opens /f/:publicId → submits.
3. Review /forms/:id/responses.

Test: Public form submits without login; response count increments.

8.15 Asset Management

What it is

Fixed asset register: equipment, assignment, depreciation tracking.

Routes reference

Workflow

1. /assets/list → Add asset (equipment, cost, location).
2. Assign to user/department.
3. Appears on balance sheet (when integrated with accounting).

Test: Asset visible in list; edit persists.

9. Cross-Module Business Workflows

9.1 Retail shop (complete)

Procurement PR → PO → Stock GRN → POS sale → Consolidate → Financial statements

9.2 Pharmacy clinic (Caring Hands pattern)

Patient → Appointment → Encounter → Dispense → Invoice → Medical aid claim → Financial dashboard

9.3 School term

Periods → Enrol → Assess → Marks → Report cards → (optional) Fees invoice

9.4 Insurance broker

Submission → Quote → Placement → Policy → Premium in GL → Claim → Commission statement

10. Shared Tools

10.1 Chat / Analyst

API: Main API + chatApiUrl for chat service.

Test: Send message → streamed response; no 401 with valid JWT.

10.2 Mobile Scanner

Requires: SignalR connection to /hubs/barcode-scan; desktop session initiates scan.

Test: Open scanner on phone → scan barcode → appears on desktop stock take or POS.

10.3 Guides

Route: /guides — in-app help.

10.4 Nudge engine

Contextual tips via NudgeHub (/hubs/nudge). Background intelligence per module (finance, inventory, school, etc.).

10.5 Desktop print bridge

URL: http://127.0.0.1:17890
Purpose: Silent printing for receipts and labels from desktop deployment.

Test: POS sale → receipt prints without browser dialog.

10.6 Branch sync (desktop / multi-branch)

Route: /organisation/branch-sync
Purpose: Offline branch captures outbox events; sync push/pull when online.

Test: Create sale offline → sync → appears at head office.

11. Phase Final — Logout and Session End

11.1 What it is

Logout terminates the session: clears JWT, refresh token, and cached user/permission data from localStorage; disconnects SignalR hubs.

11.2 Manual logout workflow

1. Click profile menu (top-right).
2. Select Logout.
3. AuthService.logout() calls API if configured; clears local storage.
4. Redirect to /login.

Test:

11.3 Automatic logout triggers

11.4 End-of-day checklist (organisation)

11.5 Security notes

• Never share JWT or refresh tokens.
• Use 2FA for admin and finance roles.
• Use Preview as Role (profile menu) to verify access before granting production roles.
• Log out on shared workstations.

12. Global Testing Matrix

12.1 Smoke test (any deployment)

Run after deployment or major upgrade (~30 minutes):

12.2 Module-specific regression

12.3 API verification (optional technical test)

Use Swagger at API root or tools like curl:

POST /api/auth/login
GET  /api/users/me          Authorization: Bearer {token}
GET  /api/organisations/current
GET  /api/products?take=5

Expect 200 for authorised endpoints; 401 without token; 403 without permission.

13. Global Error Catalogue and Fixes

13.1 HTTP status codes

13.2 UI errors

13.3 Data integrity rules

13.4 When to escalate

• Repeated 500 errors on core endpoints (/api/auth/login, /api/products)
• Data visible across organisations (security incident)
• Branch sync ledger out of balance after sync
• Payment gateway (Paynow) failures affecting live billing

14. Appendices

Appendix A — Full authenticated route index

See operations.ui/src/app/app-routing.module.ts and each *-routing.module.ts under src/app/components/. Module exploration agent documented 200+ routes — key prefixes:

Public routes (no auth): /login, /register, /f/:publicId, /share/:token, /mobile-scanner, password reset, invite acceptance, student activation.

Appendix B — Permission format examples

stock:inventory:view
stock:inventory:create
sales:invoices:create
pharmacy:dispense:create
school:students:view
crm:leads:create
organisation:roles:assign
*:*:*

Appendix C — Related documentation files

Appendix D — Default role summary

Appendix E — Integration endpoints (admin reference)

End of SOP — Pindah Basa / Operations Platform