System Blueprint → Access engine (permissions)

---

🧱 Layered Architecture Overview

flowchart TB

%% =========================
%% LAYER 1 — ACCESS / ENTRY
%% =========================
subgraph L1["🌐 Access Layer"]
    A1["Platform Admin Login\nadmin.kisum.io"]
    A2["User Login\napp.kisum.io"]
end

%% =========================
%% LAYER 2 — AUTH
%% =========================
subgraph L2["🔐 Auth Layer"]
    B1["Auth Backend\n(auth.kisum.io)"]
    B2[(PostgreSQL Auth DB)]

    B1 <--> B2
end

A1 --> B1
A2 --> B1

%% =========================
%% LAYER 3 — FRONTENDS
%% =========================
subgraph L3["🖥️ Frontend Layer"]
    C1["Platform Admin Frontend"]
    C2["User Frontend (App Shell)"]
end

C1 <--> B1
C2 <--> B1

%% =========================
%% LAYER 4 — CORE / PLATFORM
%% =========================
subgraph L4["📦 Core / Platform Layer"]
    D1["Basic App (Core UI)"]
    D2["Basic Backend\n(api-v2.kisum.dev)"]
    D3[(Main DB)]

    D1 <--> D2
    D2 <--> D3
end

C2 --> D1

%% =========================
%% LAYER 5 — PLATFORM ADMIN
%% =========================
subgraph L5["⚙️ Platform Admin Layer"]
    E1["Admin Backend\n(api-v2-admin.kisum.dev)"]
    E2[(Platform/Core Config DB)]

    E1 <--> E2
end

C1 <--> E1
E1 -. Token Validation .-> B1

%% =========================
%% LAYER 6 — MODULES
%% =========================
subgraph L6["🧩 Add-on Modules"]
    F1["Finance Module"]
    F2["Touring Module"]
    F3["Market Module"]
    F4["Venue Module"]
    F5["AI Module"]
end

D1 --> F1
D1 --> F2
D1 --> F3
D1 --> F4
D1 --> F5

%% =========================
%% LAYER 7 — MODULE BACKENDS
%% =========================
subgraph L7["🧠 Module Backends"]
    G1["Finance Backend"]
    G2["Touring Backend"]
    G3["Market Backend"]
    G4["Venue Backend"]
    G5["AI Backend"]
end

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

%% =========================
%% LAYER 8 — MODULE DATABASES
%% =========================
subgraph L8["💾 Module Databases"]
    H1[(PostgreSQL Finance)]
    H2[(MongoDB Market/Touring)]
    H3[(Venue DB)]
    H4[(AI DB)]
end

G1 <--> H1
G2 <--> H2
G3 <--> H2
G4 <--> H3
G5 <--> H4

%% =========================
%% TOKEN VALIDATION LINKS
%% =========================
D2 -. Token Validation .-> B1
G1 -. Token Validation .-> B1
G2 -. Token Validation .-> B1
G3 -. Token Validation .-> B1
G4 -. Token Validation .-> B1
G5 -. Token Validation .-> B1

---

🧠 Access Control Engine (Core Logic)

flowchart LR

    A["Company Subscriptions\n(Basic + Add-ons)"]
    B["Membership Module Grants"]
    C["Membership Permissions"]
    D["Delegation Rules"]

    A --> E["Access Engine"]
    B --> E
    C --> E
    D --> E

    E --> F["Effective Modules"]
    E --> G["Effective Permissions"]
    E --> H["Grant Rules"]

    F --> I["Frontend App Visibility"]
    G --> J["Backend Route Authorization"]
    H --> K["Admin / User Management Rules"]

---

🏢 Company vs 👤 User Access

flowchart TD

    A["Company A\nBasic + Finance + Market"]

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

    B1 --> C1["Full Access"]
    B2 --> C2["Finance only"]
    B3 --> C3["Basic + Finance"]
    B4 --> C4["Basic + Market"]
    B5 --> C5["Finance + Market"]

---

👑 Role Hierarchy & Delegation

flowchart TD

    A["TENANT_SUPERADMIN\n(full control)"]
    B["ADMIN\n(no billing, limited delegation)"]
    C["MANAGER / APPROVAL\n(restricted control)"]
    D["USER / SUBMITTER\n(no control)"]

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

---

🔄 Request Flow (Runtime)

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 Token
    AUTH-->>MOD: User + Membership

    MOD->>CORE: Get Company Add-ons
    CORE-->>MOD: Enabled Modules

    MOD->>AUTH: Get Membership Grants
    AUTH-->>MOD: Module + Permissions

    MOD->>MOD: Compute Effective Access

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

---

🎯 Module Access Decision Flow

flowchart TD

    A["Request to Module"]
    B["Validate JWT"]
    C["Resolve Company"]
    D["Load Company Modules"]
    E["Load Membership Grants"]
    F["Compute Effective Modules"]

    G{"Module Allowed?"}
    H["Check Permission"]
    I{"Permission OK?"}

    J["Allow"]
    K["Deny"]

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

---

🧩 Final Mental Model

COMPANY decides what EXISTS
→ (Basic + Add-ons)

AUTH decides WHO can use it
→ (Membership + Roles + Grants)

MODULE decides WHAT happens
→ (Business logic)

-------------------------------------

Final Access:

User can access a module IF:

✔ Company bought it
✔ Membership has access
✔ Permission allows action
✔ Role allows operation (if admin action)

---

🔐 IMPORTANT ARCHITECTURE CORRECTION (UPDATED)

The following rule MUST apply across all diagrams:

Auth computes effective access
Modules DO NOT compute access

Correct Runtime Behavior

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 entitlements
    CORE-->>AUTH: Modules

    AUTH-->>MOD: Effective Access

    MOD->>MOD: Enforce (module + permission)

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

Critical Rule

Modules must NEVER:
- call Core 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