Commercial Model (Permissions & Packages)

Auth + Platform Admin + Basic Package + Add-on Modules

This is the proposed system map / blueprint for how the platform should work.

It follows these rules:

Auth Backend is the source of truth for:
- login
- JWT / session
- company memberships
- tenant roles
- user module access
- user permissions
- delegation rules
Platform/Core logic is the source of truth for:
- package catalog
- add-on catalog
- module catalog
- company subscriptions
- company purchased add-ons
Each module backend is the source of truth for its own business data.
Frontend visibility must depend on:
- what the company bought
- what the user membership is allowed to access

1. High-level blueprint

flowchart TD

    %% =========================
    %% LOGIN / AUTH LAYER
    %% =========================
    A1[Platform Admin Login\nadmin.kisum.io/login]
    A2[User Login\napp.kisum.io/login]

    A3[Auth Backend\nauth.kisum.io]
    A4[(PostgreSQL Auth)]

    A1 --> A3
    A2 --> A3
    A3 <--> A4

    %% =========================
    %% FRONTENDS
    %% =========================
    B1[Platform Admin Frontend\napp.kisum.io]
    B2[User Frontend\napp.kisum.io]

    B1 <--> A3
    B2 <--> A3

    %% =========================
    %% PLATFORM / BASIC CORE
    %% =========================
    C1[Basic Package / Core App\napp.kisum.io]
    C2[Basic Backend\napi-v2.kisum.dev]
    C3[(Main Database)]

    B2 <--> C1
    C1 <--> C2
    C2 <--> C3

    %% =========================
    %% ADMIN BACKEND
    %% =========================
    D1[Admin Backend\napi-v2-admin.kisum.dev]
    D2[(Platform / Core Config DB)]

    B1 <--> D1
    D1 <--> D2
    D1 -. token validation .-> A3

    %% =========================
    %% MODULE FRONTENDS
    %% =========================
    E1[Finance Module\napp.kisum.io/finance]
    E2[Touring Module\napp.kisum.io/touring]
    E3[Market Module\napp.kisum.io/market]
    E4[Venue Module\napp.kisum.io/venue]
    E5[AI Module\napp.kisum.io/chat]

    C1 --> E1
    C1 --> E2
    C1 --> E3
    C1 --> E4
    C1 --> E5

    %% =========================
    %% MODULE BACKENDS
    %% =========================
    F1[Finance Backend\napi-v2-finance.kisum.dev]
    F2[Touring Backend\napi-v2-touring.kisum.dev]
    F3[Market Backend\napi-v2-market.kisum.dev]
    F4[Venue Backend\napi.kisum.dev/venue]
    F5[AI Backend\napi-v2-ai.kisum.dev]

    E1 <--> F1
    E2 <--> F2
    E3 <--> F3
    E4 <--> F4
    E5 <--> F5

    %% =========================
    %% MODULE DATABASES
    %% =========================
    G1[(PostgreSQL Finance)]
    G2[(MongoDB Touring / Market)]
    G3[(Venue DB)]
    G4[(AI DB)]

    F1 <--> G1
    F2 <--> G2
    F3 <--> G2
    F4 <--> G3
    F5 <--> G4

    %% =========================
    %% AUTH VALIDATION TO SERVICES
    %% =========================
    C2 -. token validation .-> A3
    F1 -. token validation .-> A3
    F2 -. token validation .-> A3
    F3 -. token validation .-> A3
    F4 -. token validation .-> A3
    F5 -. token validation .-> A3

2. Logical blueprint

2.1 Main responsibility split

flowchart LR

    A[Auth Layer] --> A1[Users]
    A --> A2[Sessions]
    A --> A3[Company Memberships]
    A --> A4[Tenant Roles]
    A --> A5[User Module Grants]
    A --> A6[User Permissions]
    A --> A7[Delegation Rules]

    B[Platform / Core Layer] --> B1[Package Catalog]
    B --> B2[Add-on Catalog]
    B --> B3[Module Catalog]
    B --> B4[Company Subscriptions]
    B --> B5[Company Add-ons]

    C[Business Module Layer] --> C1[Finance Data]
    C --> C2[Touring Data]
    C --> C3[Market Data]
    C --> C4[Venue Data]
    C --> C5[AI Data]

3. Access model blueprint

3.1 Access is calculated in 3 layers

flowchart TD

    A[Company bought modules] --> D[Effective Access Engine]
    B[Membership granted modules] --> D
    C[Membership fine permissions] --> D

    D --> E[Frontend visible apps]
    D --> F[Backend route authorization]
    D --> G[Delegation / grant rules]

3.2 Access formula

effective_module_access
=
company_enabled_modules
AND
membership_granted_modules

effective_permission_access
=
permission belongs to enabled module
AND
membership has that permission

4. Company vs user access blueprint

4.1 Company level

The company owns:

Basic Package
zero or more add-ons:
- Finance
- Touring
- Market
- Venue
- AI

This means:

Company A
= Basic + Finance + Market

So company-level enabled modules are:

basic
finance
market

4.2 User level inside the company

Users inside that company may have different access:

User A = Basic + Finance + Market
User B = Finance only
User C = Basic + Finance
User D = Basic + Market
User E = Finance + Market

So even if the company owns the module, the user still needs access granted.

4.3 Blueprint

flowchart TD

    A[Company A bought:\nBasic + Finance + Market]

    A --> B1[User A grants:\nBasic + Finance + Market]
    A --> B2[User B grants:\nFinance only]
    A --> B3[User C grants:\nBasic + Finance]
    A --> B4[User D grants:\nBasic + Market]
    A --> B5[User E grants:\nFinance + Market]

    B1 --> C1[Effective: Basic + Finance + Market]
    B2 --> C2[Effective: Finance]
    B3 --> C3[Effective: Basic + Finance]
    B4 --> C4[Effective: Basic + Market]
    B5 --> C5[Effective: Finance + Market]

5. Role hierarchy blueprint

Roles are not the same as modules.

Roles define administrative authority.

Modules define what app/service the user can enter.

Permissions define what the user can do inside the module.

5.1 Role hierarchy

flowchart TD

    A[TENANT_SUPERADMIN]
    B[ADMIN]
    C[MANAGER / APPROVAL]
    D[USER / SUBMITTER]

    A --> B
    B --> C
    C --> D

5.2 Role meaning

TENANT_SUPERADMIN

access to all modules company bought
can buy add-ons
can grant module access
can grant permissions
can restrict what Admin can grant

ADMIN

access to all modules company bought
cannot buy add-ons
can manage users
can grant only what Superadmin allows

MANAGER / APPROVAL

below Admin
can only manage within delegated scope
can only grant what Admin or Superadmin allow

USER / SUBMITTER

normal operational user
no grant power by default
only uses what was assigned

6. Delegation blueprint

6.1 Delegation rule flow

flowchart TD

    A[Superadmin defines Admin grant scope]
    B[Admin defines Manager grant scope]
    C[Manager can assign to Users]
    D[User consumes assigned access]

    A --> B
    B --> C
    C --> D

6.2 Example

Company bought:
Basic + Finance + Market

Superadmin decides:
- Admin can manage only Basic + Finance
- Admin cannot grant Market

Admin decides:
- Manager can grant only Finance.view and Finance.create

Manager decides:
- User X gets Finance.view only

This means:

even though company has Market, Admin cannot assign it
even though Admin has Finance, Manager may receive only part of Finance grant authority
final user gets only what is delegated down

7. Runtime request blueprint

7.1 Any request to a backend

sequenceDiagram
    participant FE as Frontend
    participant BE as Module Backend
    participant AUTH as Auth Backend
    participant CORE as Platform/Core
    participant DB as Module DB

    FE->>BE: Request with JWT + x-org
    BE->>AUTH: Validate token + session
    AUTH-->>BE: User + membership + role
    BE->>CORE: Get company package/add-ons
    CORE-->>BE: Company enabled modules
    BE->>AUTH: Get membership grants / permissions / delegation
    AUTH-->>BE: Membership access data
    BE->>BE: Compute effective access
    BE->>DB: If allowed, execute business action
    DB-->>BE: Return data
    BE-->>FE: Response

8. Frontend app-loading blueprint

The frontend should not guess access.

It should request access summary from backend.

8.1 Flow

sequenceDiagram
    participant FE as Frontend
    participant AUTH as Auth Backend
    participant CORE as Platform/Core

    FE->>AUTH: Login
    AUTH-->>FE: JWT + session

    FE->>AUTH: GET /auth/me/access?companyId=...
    AUTH->>CORE: Resolve company subscriptions/add-ons
    CORE-->>AUTH: Company enabled modules
    AUTH->>AUTH: Resolve membership grants + permissions + delegation
    AUTH-->>FE: Access summary JSON

8.2 Example frontend result

{
  "companyId": "uuid",
  "tenantRole": "MANAGER",
  "companyEnabledModules": ["basic", "finance", "market"],
  "membershipGrantedModules": ["finance", "market"],
  "effectiveModules": ["finance", "market"],
  "permissions": [
    "finance.expense.view",
    "finance.expense.create",
    "market.artist.view"
  ],
  "delegation": {
    "canBuyAddons": false,
    "canManageUsers": true,
    "grantableModules": ["finance"],
    "grantablePermissions": [
      "finance.expense.view",
      "finance.expense.create"
    ]
  }
}

9. Module opening blueprint

9.1 Example: user opens Finance

flowchart TD

    A[User clicks Finance module]
    B[Frontend checks effectiveModules]
    C{Finance allowed?}
    D[Open Finance frontend]
    E[Hide / deny module]

    A --> B
    B --> C
    C -->|Yes| D
    C -->|No| E

9.2 Example: Finance API request

flowchart TD

    A[Request to Finance Backend]
    B[Validate token]
    C[Resolve company]
    D[Load company enabled modules]
    E[Load membership module grants]
    F[Compute effective modules]
    G{Finance enabled?}
    H[Load fine permissions]
    I{Has finance.expense.view?}
    J[Allow request]
    K[Deny request]

    A --> B --> C --> D --> E --> F --> G
    G -->|No| K
    G -->|Yes| H --> I
    I -->|Yes| J
    I -->|No| K

10. Admin management blueprint

10.1 Platform Admin area

The Platform Admin frontend/backend should manage:

package catalog
add-on catalog
module catalog
company subscriptions
company add-ons
maybe global configuration

10.2 Company access management area

Inside tenant/company management, we need:

list company users
show company enabled modules
show user granted modules
show user permissions
show delegation boundaries
grant/revoke module access
grant/revoke permissions
configure who can grant what

10.3 Flow

sequenceDiagram
    participant ADMIN as Superadmin/Admin UI
    participant ABE as Admin Backend
    participant AUTH as Auth Backend
    participant CORE as Platform/Core

    ADMIN->>ABE: Open company access management
    ABE->>CORE: Get company package + add-ons
    CORE-->>ABE: Company enabled modules
    ABE->>AUTH: Get memberships + grants + permissions
    AUTH-->>ABE: Access matrix
    ABE-->>ADMIN: Render user/module/permission screen

    ADMIN->>ABE: Grant Finance to User B
    ABE->>AUTH: Validate actor delegation rights
    AUTH-->>ABE: Allowed
    ABE->>AUTH: Save membership module grant
    AUTH-->>ABE: Success
    ABE-->>ADMIN: Updated access

11. Blueprint for service ownership

11.1 Ownership map

flowchart LR

    A[Auth Backend] --> A1[Identity]
    A --> A2[Sessions]
    A --> A3[Memberships]
    A --> A4[Roles]
    A --> A5[User Module Grants]
    A --> A6[Permissions]
    A --> A7[Delegation]

    B[Platform/Core] --> B1[Package Catalog]
    B --> B2[Add-on Catalog]
    B --> B3[Company Subscriptions]
    B --> B4[Company Add-ons]

    C[Basic Backend] --> C1[Basic data]
    D[Finance Backend] --> D1[Finance data]
    E[Touring Backend] --> E1[Touring data]
    F[Market Backend] --> F1[Market data]
    G[Venue Backend] --> G1[Venue data]
    H[AI Backend] --> H1[AI data]

12. Final blueprint rules

Hard rules

A company can only use modules it bought.
A user can only use modules:
- bought by company
- granted to that membership
A permission only works if its module is enabled for that user.
Roles do not replace module grants.
Frontend visibility is not security.
Backend must always validate module access and permission access.
Admin/Manager delegation must be enforced by DB-backed rules, not only by UI.

13. Final condensed architecture map

flowchart TD

    A[Login] --> B[Auth Backend]
    B --> C[(Auth DB)]

    B --> D[User identity]
    B --> E[Membership]
    B --> F[Role]
    B --> G[Module grants]
    B --> H[Permissions]
    B --> I[Delegation]

    J[Platform/Core] --> K[Package catalog]
    J --> L[Add-on catalog]
    J --> M[Company subscriptions]
    J --> N[Company add-ons]

    O[Access Engine] --> P[Company enabled modules]
    O --> Q[Membership granted modules]
    O --> R[Fine permissions]
    O --> S[Delegation rules]

    P --> T[Effective Access]
    Q --> T
    R --> T
    S --> T

    T --> U[Frontend visible apps]
    T --> V[Backend route checks]
    T --> W[Grant / revoke validation]

    X[Finance Backend] --> Y[(Finance DB)]
    Z[Market Backend] --> AA[(Market DB)]
    AB[Venue Backend] --> AC[(Venue DB)]
    AD[AI Backend] --> AE[(AI DB)]
    AF[Touring Backend] --> AG[(Touring DB)]

    V --> X
    V --> Z
    V --> AB
    V --> AD
    V --> AF

14. One-line summary

Auth decides who the user is and what they are allowed to do,
Platform/Core decides what the company bought,
and each module backend only serves requests that pass both checks.

🔐 IMPORTANT ARCHITECTURE CORRECTION (UPDATED)

The following rule MUST apply across all flows:

Auth computes effective access
Backends DO NOT compute access

Correct Runtime Flow

sequenceDiagram
    participant FE as Frontend
    participant AUTH as Auth Backend
    participant CORE as Platform Core
    participant MOD as Module Backend
    participant DB as Module DB

    FE->>AUTH: Login
    AUTH-->>FE: JWT

    FE->>MOD: API Request (JWT + x-org)

    MOD->>AUTH: Validate + /auth/me/access
    AUTH->>CORE: Get company entitlements
    CORE-->>AUTH: Enabled modules

    AUTH-->>MOD: Effective access

    MOD->>MOD: Enforce module + permission

    MOD->>DB: Execute if allowed
    DB-->>MOD: Data
    MOD-->>FE: Response

Critical Rule

Backends must NEVER:

call Core directly for access decisions
compute effective access
merge entitlements and grants

Only Auth performs:

entitlements ∩ grants → effective access

🧠 FINAL ENFORCEMENT RULE

Core = commercial truth
Auth = access truth
Backend = enforcement
Frontend = UX only