Backend Modules

Related documentation: Kisum System · Backend implementation · Base Modules Backend · Addon Modules Backend · Checkout System - Backend · Data ownership

Current implementation snapshot

• Current Core taxonomy: modules are split into base and addon.
• Base modules: promoter, artist, vendor, venue
• Addon modules: finance, ai, touring, venue_marketplace
• Implemented now: some of those modules already have documented backend services; others exist in the taxonomy but still have deferred implementation work.
• Implemented now: the AI addon is split across multiple real repos (Chat-Kisum-MCP-Node, Backend-MCP-Kisum, Backend-Kisum-RAG-KB-LLM, prototype repos) rather than one unified backend.
• Also documented here: some backend systems sit outside the commercial module catalog entirely, such as Checkout. Those stay outside the modules tree.
• Docs rule for this page: this page explains the taxonomy first, then the currently documented backend surfaces under that taxonomy.

Status

This document is FINAL and ENFORCEABLE for all business module backends.

It defines:

• what modules exist
• what each module is responsible for
• how modules interact
• what modules must NOT do
• shared rules across all module backends

This is the business backend layer of the system.

---

1. Purpose

This document defines the backend module taxonomy and the backend services currently documented around it.

Commercial modules are:

product capabilities a company can subscribe to

Some modules already map to dedicated backend services.

Some modules are still planned or partial.

Some backend systems are real and important but live outside the current commercial module catalog.

---

2. Position in architecture

Frontend → Module Backend / Shared Service → DB
                                     → Middleware → Auth

Commercial module backends:

• do not compute access
• do not call Core for authorization
• do not decide permissions
• only enforce via middleware

---

3. Module taxonomy

Core’s modules.type is constrained to 'base' | 'addon'.

Each company has:

• exactly one base module
• zero or more addon modules

This is the reason the docs are now structured under:

• backend/modules/base/*
• backend/modules/addons/*

3.1 Base modules

| Module | Persona | Consumer frontend | Docs | |---|---|---| | promoter | Event organizer / promoter (renamed from legacy basic) | Frontend-Kisum | Promoters | | artist | Artist / Agent | Frontend Artist | Artist | | vendor | Vendor | not built yet | Vendor | | venue | Venue management | Frontend-Kisum-Venues | Venue |

See also:

• Base Modules Backend

3.2 Addon modules

| Module | Description | Docs | |---|---| | finance | Expenses, income, settlements, accounting | Finance | | ai | AI Copilot, MCP tooling, retrieval/reporting support | AI Addon | | touring | Tours, routing, schedules | Touring Addon | | venue_marketplace | Promoter → Venue booking flow | Venue Marketplace Addon |

See also:

• Addon Modules Backend

3.3 Non-module backend systems

Some backend systems are documented outside the modules tree because they are not one of the current commercial base or addon module rows.

• Checkout (self-serve + Xendit)

Auxiliary but real AI/runtime repos that sit under the AI addon documentation branch:

• Chat + MCP (Node)
• Backend MCP (Go)
• RAG KB LLM

3.4 Base-vs-addon rules

• A company without an active base subscription has access to nothing.
• Addons are additive: a company with promoter base + ai addon gets every permission key under both promoter.* and ai.*.
• Addons do NOT extend the persona — a venue company adding the ai addon gets ai.* permissions, NOT promoter.* ones. Cross-persona behavior requires a different base subscription.
• Per-persona pricing is the four basic_<audience> package rows in Core. Each is wired via package_modules to exactly one base module.

3.5 Documentation rule

The docs source tree now mirrors the taxonomy:

• backend/modules/base/*
• backend/modules/addons/*

Module docs should stay there. Non-module backend systems such as Checkout should stay outside the modules tree.

---

4. Core rules for ALL modules

4.1 Access enforcement

Modules MUST use:

• validateJwt
• requireCompanyContext
• resolveAccessContext
• requireModule()
• requirePermission()

Modules MUST NOT:

❌ compute access manually
❌ trust frontend access state
❌ call Core for entitlement checks
❌ call Auth directly for decisions (middleware handles it)

---

4.2 Module independence

Modules must be independently accessible.

Meaning:

• Promoters, Artist, Vendor, and Venue are separate base-module surfaces
• Finance, Touring, AI, and Venue Marketplace are add-ons that layer on top of a compatible base module
• Venue does not depend on Artist
• AI does not depend on Promoters specifically; it depends on the compatible base-module context

---

4.3 Module = feature gate

Access to a module is determined by:

company entitlement (Core)
+ membership grant (Auth)

---

5. Inter-module communication

5.1 Allowed pattern

Module → shared/promoter-side business backend where still needed
Module → own DB

Examples:

• Finance reads Events from shared business backends where needed
• Market reads Artists from shared business backends where needed
• Venue reads Events from shared business backends where needed

---

5.2 Forbidden pattern

❌ Module → Core (for access decisions)
❌ Module → Auth (for access decisions)
❌ Module → Module direct coupling (tight coupling)

---

6. Data ownership

Each module owns its domain data.

Examples:

Finance owns:

• expenses
• income
• settlements

Market owns:

• contracts
• deals
• negotiations

Touring owns:

• tours
• routing
• schedules

Venue owns:

• venue master records
• spaces
• availability
• bookings
• venue-side events
• venue-side commercial deal structures
• contract orchestration state

AI owns:

• predictions
• analytics
• scoring

---

6.1 Shared data

Shared entities (events, artists, etc.):

• live in Base backend
• are READ by modules
• not duplicated across modules

---

7. Dependency rules

7.1 Base dependency

Modules MAY depend on Base for:

• shared entities
• read-only operations

Modules MUST NOT:

❌ replicate Base logic
❌ become dependent on Base for access

---

7.2 No Core dependency for access

Modules must NEVER call Core for authorization

Core is only used indirectly through Auth.

---

8. Standard module structure

Each module backend should define:

8.1 Purpose

• what problem it solves

8.2 Data ownership

• what it owns
• what it reads

8.3 Required module key

Example:

finance
market
venue

8.4 Required permissions

Example:

finance.expense.view
finance.expense.create

8.5 Route groups

Example:

/api/finance/*
/api/market/*

8.6 Integration

• with Base
• with external APIs

8.7 What it must NOT do

• access logic duplication
• entitlement logic
• identity management

---

9. Communication model

Frontend → Module Backend
Module Backend → Middleware (Auth resolution)
Module Backend → DB
Module Backend → Base (optional)

---

10. Error contract

Modules must follow:

• 401 → auth problem
• 403 → access problem
• 503 → system failure

Defined in:

• Error contract

---

11. Caching

Modules:

• may use local cache for performance
• MUST NOT cache access incorrectly
• MUST align with the Access caching strategy

---

12. Logging

Modules must log:

• userId
• companyId
• endpoint
• action
• result

---

13. Migration note

Legacy systems (especially Finance):

• must migrate to this model
• must remove local user/permission logic
• must rely on Auth/Core

---

14. Future modules

New modules must:

1. be defined in Core (module catalog)
2. be enabled via entitlements
3. follow this document
4. implement middleware enforcement
5. integrate with Base if needed

---

15. Final rules

Modules own business logic.
Auth owns access.
Core owns entitlements.
Middleware enforces access.

---

16. One-line summary

Modules are independent backend services that execute business logic, relying on Auth for access enforcement and Core for entitlement definition.