Use Cases & Interaction Flows

Understanding how users interacting with the system is vital for implementation. We categorize use cases by Actor and Domain.

1) Primary Actors

🕵️ Super Admin

RonnieERP Staff. Manages tenants, high-level support, and platform configuration.

👨‍💼 Tenant Admin

IT Manager / CEO of the Client Company. Full access to their tenant.

👷 Employee

Standard user. Logs in, checks leave, tasks, tickets.

🤖 System/Billing

Automated processes (Cron jobs, Recurring invoices).

2) Core Use Cases

Tenant Management

Onboard Tenant: Wizard to set name, subdomain, currency.
Configure Domains: Setup custom domain (CNAME).
View Dashboard: See active users, storage usage, license warnings.

User & RBAC

Invite User: Send email invitation to employees.
Assign Role: Grant specific permissions (e.g., "HR Manager" or "Accountant").
Reset 2FA/Password: Security recovery flows.

Marketplace

Browse Modules: View available plugins (HRM, Accounts).
Enable/Disable: Activate a module (starts billing trial).
Billing Settings: Update credit card, view invoices.

3) Key Sequence Flows

Detailed technical flows for critical platform actions.

A. Tenant Onboarding Flow

            sequenceDiagram
                actor User
                participant FE as Frontend
                participant API as Central API
                participant DB as Central DB
                participant Email as Email Service

                User->>FE: Fills Signup Form (Name, Email, Industry)
                FE->>API: POST /tenants/signup
                API->>DB: Create Tenant Record (status=Active)
                API->>DB: Create User (Role=TenantAdmin)
                API->>Email: Send Welcome/Verify Email
                Email-->>User: Verification Link
                User->>FE: Clicks Link
                FE->>API: POST /auth/verify
                API-->>FE: Returns Auth Token

B. Enabling a Paid Module

            sequenceDiagram
                actor Admin as TenantAdmin
                participant Hub as Central Hub
                participant Bill as Billing Gateway
                participant Bus as Event Bus
                participant Mod as Target Module (HRM)

                Admin->>Hub: Click "Enable HRM"
                Hub->>Bill: Check Payment Method
                Bill-->>Hub: Payment Valid / Trial Started
                Hub->>Hub: Insert into `tenant_modules`
                Hub->>Bus: Publish `module.enabled` {tenant_id, module: 'hrm'}
                Bus->>Mod: Consumption Trigger
                Mod->>Mod: Run Seeders (Def. Permissions, Settings)
                Mod-->>Hub: Ack (Ready)
                Hub-->>Admin: Show "Launch" Button

C. Validating a Request (Middleware)

            sequenceDiagram
                participant Client
                participant GW as API Gateway
                participant Auth as Auth Middleware
                participant App as Module Handler

                Client->>GW: GET /hrm/employees (Bearer Token)
                GW->>Auth: Validate Token Signature
                Auth-->>GW: Token Valid (User: 123, Tenant: 456)
                GW->>Auth: Check Permissions (hrm.employees.view)
                
                alt Permission Denied
                    Auth-->>Client: 403 Forbidden
                else Permission Granted
                    Auth->>App: Forward Request + Context Headers
                    App-->>Client: 200 OK (Data)
                end

4) Scenario Narratives

Scenario 1: The "New Hire" Flow

Tenant Admin logs into Central.
Navigates to People Directory.
Clicks "Add Person", enters details (John Doe, Email, Dept: Sales).
System creates a Person Record in Central.
Admin clicks "Invite User" linked to this Person.
Events `person.created` and `user.invited` are published.
HRM Module consumes `person.created` to start a purely HR profile (Tax ID, Bank Details).
Attendance Module consumes `person.created` to create a shift roster entry.

Scenario 2: Cross-Module Dependency

User wants to apply for Leave in HRM.
HRM needs to know who the "Line Manager" is.
HRM queries its local read-model of the Organization Chart (synced from Central).
HRM determines "Manager" is "Jane Smith".
HRM creates a Notification request targeting "Jane Smith".
Central Notification Service picks up the request and delivers the email/push to Jane.

5) Permission Mapping

Action	Required Permission Key	Default Role
View Dashboard	`core.dashboard.view`	All Authenticated
Manage Users	`core.users.manage`	TenantAdmin
View Audit Logs	`core.audit.view`	TenantAdmin
Enable Modules	`core.marketplace.manage`	TenantAdmin

Key Takeaways:

Actors drive the requirements; always identify WHO is doing the action.
Sequence diagrams clarify the "Handshake" between Central and Modules.
Middleware is the rigorous gatekeeper for every single request.
Scenarios prove that "Events" are superior to "Direct DB Queries".