Skip to content
Kisum • Documentation

Kisum System

Master home document for the Kisum platform. This file is the entry point for the full system documentation.

System Map (Detailed)

Section titled “System Map (Detailed)”
---

1. What this system is

Section titled “1. What this system is”

Kisum is a multi-module platform designed to operate as a centralized business system where:

  • Auth manages identity, memberships, roles, permissions, delegation, and access computation
  • Core manages the commercial model, including packages, add-ons, company entitlements, and subscriptions
  • Base manages shared business-domain entities and core platform features
  • Modules manage specialized business domains such as Finance, Market, Touring, Venue, and AI
  • Frontend consumes resolved access and renders the correct experience, but never becomes the source of truth
  • Cross-cutting backend rules define how access, middleware, caching, migration, QA, and error handling must work across the entire system

This is not a monolithic application with one permission table and one backend doing everything.

This is a layered platform architecture where each domain has a clearly defined responsibility.

2. What this system is for

Section titled “2. What this system is for”

The purpose of this system is to provide one coherent platform where:

  • companies can subscribe to products and add-ons
  • users can belong to one or more companies
  • each company can own different module combinations
  • each user can be granted different module access inside a company
  • each user can also receive fine-grained permissions inside those modules
  • higher-level tenant roles can manage lower-level users through controlled delegation
  • each module backend can evolve independently while still following the same access model

This architecture is designed to support:

  • scalability
  • modular product growth
  • strong access control
  • clean separation between commercial logic and user access logic
  • safe future migration away from legacy systems
  • clear responsibility boundaries for development teams

3. Core system idea

Section titled “3. Core system idea”

The platform follows this central rule:

Company ownership and user access are not the same thing.

A company may own:

  • Basic
  • Finance
  • Market
  • Touring
  • Venue
  • AI

But users inside that company may still have different access.

So the real access model is:

effective_access = company_entitlements ∩ membership_grants

Where:

  • company_entitlements come from Core
  • membership_grants come from Auth
  • effective access is computed by Auth
  • backend services enforce the result
  • frontend only consumes the result for UX

This separation is the foundation of the system.

4. High-level architecture

Section titled “4. High-level architecture”

The system is built around these layers:

4.1 Auth layer

Section titled “4.1 Auth layer”

Auth is the identity and access brain.

It is responsible for:

  • login
  • JWT/session lifecycle
  • memberships
  • tenant roles
  • module grants
  • permissions
  • delegation rules
  • invitations
  • effective access computation

4.2 Core layer

Section titled “4.2 Core layer”

Core is the commercial brain.

It is responsible for:

  • package catalog
  • add-on catalog
  • module catalog
  • subscriptions
  • company entitlements
  • enabled modules per company

Core defines what the company owns.

It does not define what a specific user can use.

4.3 Base layer

Section titled “4.3 Base layer”

Base is the shared business backend.

It contains common platform business entities and core business features.

It relies on Auth for access enforcement and must not become a duplicate access system.

4.4 Module layers

Section titled “4.4 Module layers”

Modules are independent backend services for specific business domains.

Initial modules include:

  • Finance
  • Market
  • Touring
  • Venue
  • AI

Each module owns its own business logic and business data.

Modules are not allowed to compute their own access truth.

4.5 Frontend layer

Section titled “4.5 Frontend layer”

Frontend is the UX layer.

It handles:

  • login screens
  • app shell
  • company switching
  • module visibility
  • route visibility
  • action visibility

Frontend does not:

  • compute effective access
  • decide entitlements
  • replace backend enforcement

4.6 Cross-cutting system layer

Section titled “4.6 Cross-cutting system layer”

These rules apply to everything:

  • access integration
  • access matrix
  • middleware behavior
  • Redis access caching
  • admin control plane
  • migration from legacy systems
  • QA expectations
  • error contract

This layer keeps the entire platform consistent.

5. How the system works

Section titled “5. How the system works”

5.1 Login flow

Section titled “5.1 Login flow”
  1. user logs in through Auth
  2. Auth validates credentials
  3. Auth creates session and returns JWT/refresh token
  4. frontend calls /auth/me
  5. frontend determines memberships / active company
  6. frontend calls /auth/me/access
  7. Auth loads:
    • membership data
    • grants
    • permissions
    • delegation
    • company entitlements from Core
  8. Auth computes effective access
  9. frontend renders the correct UI
  10. module/backend requests are later enforced again server-side

5.2 Company context

Section titled “5.2 Company context”

The system is tenant-aware.

For tenant-scoped requests, frontend and backends use:

x-org: <companyId>

This identifies the active company context.

Without company context, tenant routes must not proceed.

5.3 Access enforcement

Section titled “5.3 Access enforcement”

Backend enforcement follows this order:

  1. validate JWT
  2. validate x-org
  3. resolve effective access from Auth
  4. check module
  5. check permission
  6. execute or deny

This means:

  • Core does not decide user access
  • modules do not compute access
  • frontend is not trusted
  • access is enforced consistently everywhere

5.4 Module visibility vs backend truth

Section titled “5.4 Module visibility vs backend truth”

Frontend may hide modules and buttons based on access context, but backend still remains the final authority.

This means:

  • UI can improve UX
  • UI cannot replace security

6. What we want from this system

Section titled “6. What we want from this system”

The expected outcome of this architecture is:

6.1 Clear separation of concerns

Section titled “6.1 Clear separation of concerns”

No duplicated access logic across services.

6.2 Modular growth

Section titled “6.2 Modular growth”

New modules can be added without redesigning the whole platform.

6.3 Strong tenant isolation

Section titled “6.3 Strong tenant isolation”

Users only operate within valid company context.

6.4 Safe commercial model

Section titled “6.4 Safe commercial model”

Company subscriptions and add-ons are owned by Core, not scattered around business services.

6.5 Strong user access model

Section titled “6.5 Strong user access model”

User access is centrally computed by Auth, not guessed by each backend.

6.6 Consistent developer experience

Section titled “6.6 Consistent developer experience”

Every service follows the same enforcement, error, caching, and integration rules.

6.7 Safe migration

Section titled “6.7 Safe migration”

Legacy systems can be moved into the new model in phases without chaos.

7. Documentation map / index

Section titled “7. Documentation map / index”

This section is the master index of the backend and frontend documentation.

7.1 Auth

Section titled “7.1 Auth”

Defines:

  • identity
  • memberships
  • roles
  • permissions
  • delegation
  • invitations
  • effective access computation

7.2 Core

Section titled “7.2 Core”

Defines:

  • package model
  • module catalog
  • add-on model
  • entitlement model
  • internal APIs and Core boundaries

7.3 Module backends

Section titled “7.3 Module backends”

Defines:

  • module backend domain
  • module boundaries
  • data ownership
  • integration patterns
  • module-specific rules

7.4 Base

Section titled “7.4 Base”

Defines:

  • shared business backend architecture
  • API surface
  • integration role in the full system

7.5 Cross-cutting backend rules

Section titled “7.5 Cross-cutting backend rules”

Defines:

  • access rules
  • access matrix
  • middleware patterns
  • cache and invalidation
  • admin control plane
  • migration strategy
  • QA scenarios
  • system-wide error contract

7.6 Frontend

Section titled “7.6 Frontend”

Defines:

  • frontend behavior
  • login/bootstrap flow
  • /auth/me and /auth/me/access
  • company switching
  • route and module visibility
  • implementation tasks and sequencing

7.7 Architecture and diagrams

Section titled “7.7 Architecture and diagrams”

Defines:

  • visual system model
  • access engine logic
  • commercial model
  • blueprint flows
  • high-level architecture understanding

8. Recommended reading order

Section titled “8. Recommended reading order”

For a new engineer or architect, the best reading order is:

8.1 To understand the system first

Section titled “8.1 To understand the system first”
  1. Architecture documentation
  2. Architecture diagrams
  3. 0.-Kisum-System.md

8.2 To understand access and commercial model

Section titled “8.2 To understand access and commercial model”
  1. 2.1.-Backend-Auth.md
  2. 2.2.-Backend-Core.md
  3. 2.5.-Access-Control-Integration.md
  4. 2.6.-Access-Matrix.md

8.3 To understand implementation rules

Section titled “8.3 To understand implementation rules”
  1. 2.7.-Middleware-Implementation.md
  2. 2.8.-Access-Caching-Strategy.md
  3. 2.12.-Error-Contract.md

8.4 To understand application and UI behavior

Section titled “8.4 To understand application and UI behavior”
  1. 3.-Frontend-Implementation.md
  2. 3.1.-Frontend-Tasks-Breakdown.md

8.5 To understand rollout and safety

Section titled “8.5 To understand rollout and safety”
  1. 2.9.-Admin-Platform-Spec.md
  2. 2.10.-Migration-Plan-Mongo-to-Auth-Core.md
  3. 2.11.-QA-Test-Scenarios.md

9. Setup and implementation expectations

Section titled “9. Setup and implementation expectations”

9.1 Development expectation

Section titled “9.1 Development expectation”

Teams must not implement features by guessing.

They must use the corresponding documentation layer:

  • architecture docs for system intent
  • backend docs for service behavior
  • cross-cutting docs for consistency
  • frontend docs for UI behavior

9.2 Service expectation

Section titled “9.2 Service expectation”

Every backend must follow:

  • Auth for identity/access truth
  • Core for company entitlement truth
  • middleware for enforcement
  • unified error contract
  • unified cache strategy

9.3 Frontend expectation

Section titled “9.3 Frontend expectation”

Frontend must:

  • use /auth/me
  • use /auth/me/access
  • use x-org
  • reload access after company change
  • never decide final security

9.4 Admin expectation

Section titled “9.4 Admin expectation”

Platform Admin is the control plane.

It is the only place allowed to write:

  • packages
  • add-ons
  • subscriptions
  • entitlement-affecting state
  • delegation control rules

9.5 Migration expectation

Section titled “9.5 Migration expectation”

Legacy systems must be phased into:

  • Auth
  • Core
  • unified access model

No long-term dual source of truth is acceptable.

10. Build philosophy

Section titled “10. Build philosophy”

This system is intentionally designed to avoid the classic problems of a growing product:

  • business backends carrying their own access logic
  • package logic mixed with user logic
  • frontend guessing entitlements
  • legacy IDs and legacy access models blocking scale
  • module sprawl without domain boundaries

Instead, Kisum is designed as a platform where:

  • access is centralized
  • commercial logic is centralized
  • business services are modular
  • integration rules are explicit
  • migration is planned
  • QA is built into the architecture
  • error behavior is standardized

11. Final system principles

Section titled “11. Final system principles”

Principle 1

Section titled “Principle 1”
Auth decides who can use something.

Principle 2

Section titled “Principle 2”
Core decides what the company owns.

Principle 3

Section titled “Principle 3”
Backends enforce, not invent.

Principle 4

Section titled “Principle 4”
Frontend renders, not authorizes.

Principle 5

Section titled “Principle 5”
Stale access is a security issue.

Principle 6

Section titled “Principle 6”
Every service must fail closed.

12. Final one-line summary

Section titled “12. Final one-line summary”
Kisum is a modular, entitlement-driven, access-controlled platform where Core defines company ownership, Auth computes user access, backends enforce it, and frontend renders the correct experience without becoming the source of truth.

System Map

Section titled “System Map”