Architecture blueprint

Related documentation: Master architecture · Diagrams · Permissions blueprint · Commercial model

Deep engineering blueprint for Kisum platform. This document contains full system flows, responsibilities, and execution logic.

---

🧱 1. Full System Blueprint

flowchart TD

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

B --> D[User Identity]
B --> E[Membership]
B --> F[Roles]
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]

D --> O[Access Engine]
E --> O
G --> O
H --> O
I --> O
K --> O
L --> O
M --> O
N --> O

O --> P[Effective Access]

P --> Q[Frontend Visibility]
P --> R[Backend Enforcement]

---

⚡ 2. Runtime Request Flow

sequenceDiagram
    participant FE as Frontend
    participant BE as Backend
    participant AUTH as Auth
    participant CORE as Core
    participant DB as Database

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

    FE->>BE: Request (JWT + x-org)
    BE->>AUTH: Validate + /auth/me/access
    AUTH->>CORE: Get entitlements
    CORE-->>AUTH: Modules

    AUTH-->>BE: Effective access

    BE->>BE: Validate module + permission
    BE->>DB: Execute if allowed
    DB-->>BE: Data
    BE-->>FE: Response

Company context in runtime requests is standardized as x-org.

---

🧠 3. Access Engine Logic

flowchart LR

A[Company Entitlements]
B[Membership Grants]
C[Permissions]
D[Delegation]

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

E --> F[Effective Modules]
E --> G[Effective Permissions]

---

🏢 4. Company vs User Access

flowchart TD

A[Company: Basic + Finance + Market]

A --> B1[User A: All]
A --> B2[User B: Finance]
A --> B3[User C: Basic + Finance]
A --> B4[User D: Market]

---

👑 5. Delegation Flow

flowchart TD

A[Superadmin]
B[Admin]
C[Manager]
D[User]

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

---

🔄 6. Module Decision Flow

flowchart TD

A[Request]
B[Validate JWT]
C[Validate x-org]
D[Resolve Access]
E{Module Allowed?}
F{Permission OK?}

A --> B --> C --> D --> E
E -->|No| G[Deny]
E -->|Yes| F
F -->|No| G
F -->|Yes| H[Execute]

---

🎯 Final Blueprint Rules

Company decides what exists
Auth decides who can use it
Backend enforces rules
Frontend only displays
Cross-persona references use the owning service's canonical id

For Artists, that canonical public reference is numeric PostgreSQL artists.id (or slug for navigation). Promoters must not cast Artist ids to Mongo ObjectId; it validates them through Backend-Kisum-Artists before storing Event lineup references.

Marketplace offers use one neutral cross-service contract with an explicit representation channel. Promoters sends exclusive or middle_agent per listing; Artists resolves the listing source and rejects mismatches. URL naming must not force official agency offers through a Middle Agent route.

The channel also selects ownership and persistence. exclusive uses normal Artists booking_offers plus approved agency/Core ownership; middle_agent uses middle_agent_offers plus the broker operator workspace. An Exclusive agency must never need the Middle Agent addon, operator record, or permission namespace.