Yotor SACCOS — Web and Member Mobile Application Flows

Prepared: 10 November 2026
Business scope: Member, Savings, Loan, Shares and HR staff management only.
Member mobile scope: Read-only access to the authenticated member's own records, balances and transactions.

This document describes the proposed experience and target integration boundaries. It is not a claim that the mobile app, self-service APIs or all illustrated journeys are already implemented or accepted.

1. Audience and scope

User	Interface	Purpose
Membership officer	Staff web	Register and maintain authorized member records
Savings/Share officer	Staff web	Manage authorized accounts, pricing and recorded transactions
Loan officer	Staff web	Process authorized applications and repayment records
Independent approver	Staff web	Review only eligible routed requests; never self-approve
HR officer	Staff web	Maintain authorized staff records and account links
Application administrator	Staff web	Configure application roles, users and workflow routing
Auditor	Staff web	Read permitted audit evidence
Member	Member mobile app	View only their own profile, Savings, Loans, Shares and transaction history

Roles above are business personas, not evidence that those exact role names have already been provisioned. Actual access is determined by Identity's approved permission assignments and backend record checks.

Supporting services and infrastructure

• Keycloak: sign-in, credentials, authentication sessions and configured MFA.
• Identity Service: application accounts, effective roles/permissions, active status and branch scope.
• API Gateway: controlled public API entry and routing; backend checks remain required.
• Workflow Service: configured approvers, review steps, decisions and history.
• Audit Service: action and sensitive-view traceability through appropriate audit events.
• PostgreSQL: authoritative service-owned data/schema persistence.
• Kafka: asynchronous domain/audit transport and downstream processing.

Additional dependency boundaries: existing branch ownership comes from Organization. Current Loan activation depends on Accounting confirmation. These remain technical dependencies even though their administrative UIs are outside this document. Do not invent replacement branch records or financial posting confirmations to remove them from a diagram.

2. Diagram A — Whole-system architecture

Caption: “Staff operate through the web application; members receive a restricted, read-only mobile experience. Both use a controlled API boundary.”

Diagram notes: REST arrows describe logical calls, not permission to access another service's database. Mobile-facing reads must be separately authorized for ownership. Event producers use appropriate outbox/retry patterns; arrows do not mean every request emits every event. The shared database cylinder represents separate service schemas, not shared table ownership.

3. Diagram B — Staff web navigation

Caption: “One staff workspace, with screens and actions shown only when authorized.”

Web UI rules

• Searching an existing member should be the starting point for member-related account and transaction work.
• Carry the selected member/account context into related pages; do not repeatedly request raw UUID entry where a permitted picker can be used.
• Read-only users must not receive transaction, approval or editing controls.
• Display loading, empty, denied, failed and successful states explicitly.
• Keep actual business status visible; do not offer invalid transitions.
• Creating/revising approval definitions is an administrator action, separate from an approver's inbox.
• “My pending approvals” is not a list of all system requests; it is the current user's eligible queue.
• Show approved business configuration requirements instead of creating example prices or balances automatically.

4. Diagram C — Member mobile navigation

Caption: “The mobile app provides a personal view, not a second staff administration console.”

Proposed navigation: Home · Savings · Loans · Shares, with Profile/Security available from the account menu.

Mobile boundaries

• No other-member directory, member-ID picker or arbitrary branch selector.
• No member edits, deposits, withdrawals, transfers, share purchases, loan applications, approvals, HR screens or staff administration.
• An empty list means “no records for this member,” not permission to browse other members.
• Filters narrow the authenticated member's records; they cannot broaden ownership scope.
• Show real available backend values; do not fabricate transaction totals, balances, interest, loan charges or dates.
• A consolidated “recent activity” view is a proposed aggregation, not proof that a combined activity endpoint exists. Label Savings transactions, loan repayments and share purchases distinctly; do not treat their totals as a shared financial ledger.
• Default to no persistent storage of sensitive records offline. Secure session handling and cache clearing must be designed and tested for the chosen mobile framework.
• Statement downloads, push notifications and biometric login are outside this scope unless separately approved.

5. Diagram D — Login and own-record authorization

Caption: “A valid login is necessary but not sufficient: the backend verifies account access and member ownership.”

Required mobile backend work — proposed, not existing API contracts

1. Define a verified association from Keycloak subject → Identity application user → member record. Do not assume the three IDs are interchangeable.
2. Establish a controlled enrollment/linking process; matching a typed phone, email or member number alone must not grant ownership.
3. Provide dedicated self-service reads or an equally strict ownership policy in the owning services. A mobile UI filter over staff-wide APIs is insufficient.
4. Derive the member scope server-side. Check ownership for every account, loan, purchase, transaction and detail lookup.
5. Do not give mobile members staff-wide permissions merely to reuse staff endpoints. Branch membership alone is not proof of ownership.
6. Test attempts to substitute another member/account/transaction ID, including users in the same branch.
7. Use a separately configured public mobile OIDC client and restricted platform callback URIs; never embed a Keycloak client secret in an app.
8. Keep tokens and personal data out of URLs, analytics logs and audit payloads that do not require them.

Illustrative self-service URL family: /api/member-self/.... This is a design suggestion only; no such endpoint family is claimed to be implemented by this document.

6. Diagram E — Member registration and independent approval

Caption: “Registration is recoverable and approval-controlled; PENDING is not manually activated.”

Rules: Retrying resumes the persisted request and must not duplicate initial shares or workflows. The requester cannot approve their own request. Show the linked instance, current step and next authorized action. Do not imply that rejection automatically reverses the initial share purchase: financial treatment must follow the implemented/approved policy and be explicitly tested.

7. Diagram F — Savings and Shares

Caption: “Staff perform authorized operations; members view only the resulting records.”

Physical-cash workflows depend on a valid Teller session and related controls in the current system. Teller UI is outside this brief. Do not illustrate unsupported cash posting as available without that dependency. External bank/payment processing and Accounting posting are separate from displaying a stored transaction.

8. Diagram G — Loan application, approval and member view

Caption: “Loan eligibility uses authoritative Savings and Share data; approval and disbursement are separate stages.”

Loan scope qualifications

• The mobile member does not apply, approve, disburse, pay or change the Loan through this proposed app.
• Current repository flow waits for Accounting confirmation before activation. Without that supporting capability deployed/verified, present disbursement as dependency-blocked—not operationally complete.
• Asynchronous failures must remain visible; do not display ACTIVE merely because the initial request returned successfully.
• Compensation details, monetary accuracy, duplicate-event handling and complete Loan browser flows require their own acceptance tests.

9. Diagram H — HR staff management only

Caption: “HR maintains staff information; this presentation deliberately excludes wider HR operations.”

Staff UI content

• Directory/list with supported search and filters.
• Staff profile with name, contact, branch, job title, hire date and employment status.
• Create/edit forms limited to backend-supported fields and allowed changes.
• Optional Identity account link with clear duplicate/missing-link guidance.
• If the existing staff-create API requires base salary, keep it in the HR-only form and restrict visibility. Do not omit a required backend field or expose it to member mobile users.
• Employment status is a displayed business fact, not permission to bypass existing termination or reactivation rules. Do not add direct status changes that evade those rules.

Excluded HR screens: payroll runs, payslips, attendance, leave, benefits, job-grade administration and termination-approval workflows. Existing backend capabilities in those areas are not deleted; they are simply outside this presentation/UI scope.

10. Web-versus-mobile capability matrix

Capability	Authorized staff web	Member mobile
Search members	Within approved role/record scope	No directory access
View member profile	Within approved role/record scope	Own approved fields only
Register/edit member	Permission-controlled	Not available
View Savings balances/history	Permission-controlled	Own accounts only
Deposit/withdraw/lock funds	Only supported authorized operations and dependencies	Not available
View share holdings/purchases	Permission-controlled	Own holdings/history only
Configure price / purchase Shares	Permission-controlled	Not available
View Loan status/schedule/repayments	Permission-controlled	Own Loans only
Apply/approve/disburse/record repayments	Separate authorized roles and supported dependencies	Not available
View/manage staff	HR-authorized staff only	Not available
Configure users/roles/workflows	Explicit administrative permissions	Not available
Act on approvals	Eligible independent approvers only	Not available
View audit records	Audit-authorized users only	Not available
Filter transactions	Within staff's authorized scope	Only narrows own records

11. Presentation Notes

Slide	Title	Diagram / message
1	Connected SACCO operations	Scope: five business areas plus restricted member mobile
2	One platform, two experiences	Diagram A; staff operate, members view their own data
3	Staff web experience	Diagram B; permission-aware navigation and contextual work
4	Member mobile experience	Diagram C; own profile, balances and transaction history
5	Trust and access controls	Diagram D; verified identity, application access and record ownership
6	Membership approval	Diagram E; persisted onboarding and independent approval
7	Savings and Shares	Diagram F; staff operations with member read-only visibility
8	Loan lifecycle	Diagram G; eligibility, approval and Accounting boundary
9	HR staff administration	Diagram H; staff records only, not the full HR suite
10	Access comparison	Section 11 matrix; emphasize no mobile business writes
11	Delivery boundaries	Implemented foundations versus proposed mobile/Loan UI acceptance
12	Next acceptance gates	Scope confirmation, ownership APIs, stable environment and controlled UAT

Short Narration

“Yotor SACCOS has one controlled backend foundation with two user experiences. Staff use the web application to perform authorized operational tasks. Members use a restricted mobile application to view their own information and transaction records. Keycloak establishes identity, Identity Service resolves application access, domain services enforce ownership, Workflow manages eligible decisions, and Audit supports traceability.”