Skip to content
Kisum • Documentation

Backend Implementation Plan

Related documentation: Kisum System · Backend modules · Data ownership · Infrastructure tasks

Detailed Backend Tasks (Auth / Core / Modules)

Section titled “Detailed Backend Tasks (Auth / Core / Modules)”

Current implementation snapshot

Section titled “Current implementation snapshot”

This page remains the platform-level backend plan, but the repositories in scope for this documentation pass are already at different stages of implementation:

  • Auth is live and exposes public, bearer-protected, and machine/internal routes from Backend-Kisum-Auth.
  • Core is live as an internal-only commercial service from Backend-Kisum-Core, but only a subset of the target ownership model is implemented today.
  • Admin is live from Backend-Kisum-Admin, and its published API surface must be read from the current OpenAPI rather than from target-state platform-admin prose alone.
  • Base in Backend-Kisum still contains migration-era auth and tenant logic while consuming external Auth/Core for the new access path.
  • Finance is live from Backend-Kisum-Finance with a published module/API page in this docs site.
  • Artist is live from Backend-Kisum-Artists as the current artist/agency booking-network module backend, with published module/API pages in this docs site.
  • Chat + MCP (Node) — Chat-Kisum-MCP-Node is a documented AI-addon support Docker Compose stack (AI agent + MCP tools + optional Postgres chat memory); it is not Auth/Core/Base. See Chat-Kisum-MCP-Node. Distinct from Backend-MCP-Kisum (Go MCP).
  • AI Event Intelligence Copilot Prototype — AI-Event-Intelligence-Copilot-Prototype is a documented standalone Node/Express AI copilot prototype for promoter/event-intelligence flows. It uses MongoDB + Redis, serves its own lightweight UI, and is currently documented under the AI addon support layer. See AI Event Intelligence Copilot Prototype.

Use this page for the intended backend layering, then read each backend page for the current implementation status and any documented gaps.

Backend Documentation Structure

Section titled “Backend Documentation Structure”

This phase is split into multiple documents:

0. Overview

Section titled “0. Overview”

This document defines all backend work required to implement the Kisum platform architecture.

It is intentionally:

  • long
  • explicit
  • implementation-focused
  • non-abstract

This is not theory — this is what engineers should build.

1. AUTH BACKEND — FULL TASK BREAKDOWN

Section titled “1. AUTH BACKEND — FULL TASK BREAKDOWN”

The Auth service is already implemented and should not be modified structurally beyond integration alignment with the final Core company model.

It is responsible for:

  • authentication (login / refresh / logout)
  • JWT issuance and validation
  • user management
  • company memberships
  • roles and permissions (grants)
  • access aggregation (/auth/me/access)

For full API details, refer to: Backend Auth.

Auth depends on Platform Core for company entitlements.

See Core implementation in: Backend Core.

Important integration note

Section titled “Important integration note”

Auth integrates with Platform Core to resolve company entitlements.

Flow:

  1. Caller sends GET /auth/me/access
    • Authorization: Bearer <JWT>
    • x-org: <COMPANY_ID>
    • service-specific X-Internal-API-Key for backend calls
      • AUTH_INTERNAL_API_KEY when calling Auth machine routes
      • CORE_INTERNAL_API_KEY when calling Core internal routes
  2. Auth validates JWT
  3. Auth validates x-org
  4. Auth loads membership for user + company
  5. Auth loads grants, permissions, delegation
  6. Auth calls Core: GET /internal/companies/{companyId}/entitlements
  7. Auth computes effective access
  8. Auth writes/reads Redis cache using versions
  9. Auth returns normalized access object
effectiveAccess = entitlements ∩ userGrants
  1. Auth returns final access model

1.1 Service bootstrap

Section titled “1.1 Service bootstrap”

Tasks

Section titled “Tasks”
  • Initialize backend service
  • Setup:
    • config loader (env-based)
    • logger (structured JSON logs)
    • HTTP router
    • middleware stack
    • graceful shutdown

Must include

Section titled “Must include”
  • request ID middleware
  • panic recovery middleware
  • timeout middleware
  • CORS config (for frontend)

1.2 Database setup (PostgreSQL)

Section titled “1.2 Database setup (PostgreSQL)”

Tables

Section titled “Tables”
  • users
  • sessions
  • memberships
  • business_unit_memberships
  • membership_modules
  • permissions
  • membership_permissions
  • membership_delegation_policies
  • invitations

Tasks

Section titled “Tasks”
  • create migrations
  • setup connection pooling
  • add retry logic
  • validate schema at startup
  • normalize any legacy auth table naming to the final schema:
    • memberships
    • membership_modules
    • membership_permissions

1.3 Redis setup

Section titled “1.3 Redis setup”

Purpose

Section titled “Purpose”
  • access cache
  • session cache
  • revocation
  • rate limits

Tasks

Section titled “Tasks”
  • connect Redis client
  • namespace keys
  • implement TTL strategy
  • add fallback if Redis down

1.4 JWT system

Section titled “1.4 JWT system”

Tasks

Section titled “Tasks”
  • generate RSA keypair
  • expose JWKS endpoint
  • implement token signing
  • implement token verification

Validate

Section titled “Validate”
  • exp
  • iss
  • aud
  • tokenVersion
  • sessionId

1.5 Session system

Section titled “1.5 Session system”

Tasks

Section titled “Tasks”
  • create session on login
  • store hashed refresh token
  • revoke session
  • revoke all sessions
  • check session validity on request

1.6 Auth endpoints

Section titled “1.6 Auth endpoints”

Implement:

Section titled “Implement:”

POST /auth/login POST /auth/refresh POST /auth/logout POST /auth/logout-all GET /auth/me GET /auth/me/access

  • require Authorization header
  • require x-org header
  • support frontend mode and backend service mode
  • return normalized response envelope
  • return 400/401/403/503 consistently

Tasks

Section titled “Tasks”
  • validate inputs
  • standardize responses
  • implement error codes
  • rate limit login

1.7 Membership + access system

Section titled “1.7 Membership + access system”

Tasks

Section titled “Tasks”
  • load membership by user + company
  • load module grants
  • load permissions
  • load delegation

1.8 Access aggregation

Section titled “1.8 Access aggregation”

Module resolution rules

Section titled “Module resolution rules”

Modules must be computed as:

enabledModules = (Basic package modules IF active) + (all active addon modules)

Example:

  • Basic inactive
  • Addons: finance, market

→ enabledModules = [“finance”, “market”]

  • Basic active
  • Addons: finance

→ enabledModules = [“basic”, “finance”]

Steps

Section titled “Steps”
  1. load membership
  2. call Core
  3. merge
  4. compute effective modules
  5. compute permissions
  6. compute delegation
  7. cache result

Output contract must include:

Section titled “Output contract must include:”
  • modules
  • permissions
  • tenantRole
  • delegation
  • meta.tokenVersion
  • meta.accessVersion
  • meta.entitlementVersion

1.9 Access cache

Section titled “1.9 Access cache”

Key format

Section titled “Key format”

access:{company}:{membership}:{version}

Tasks

Section titled “Tasks”
  • store cache
  • invalidate on change
  • fallback to DB if miss

1.10 Tenant management APIs

Section titled “1.10 Tenant management APIs”

Tasks

Section titled “Tasks”
  • list users
  • create membership
  • update membership
  • grant modules
  • revoke modules
  • grant permissions
  • revoke permissions
  • update delegation

2. PLATFORM CORE BACKEND

Section titled “2. PLATFORM CORE BACKEND”

2.1 Service bootstrap

Section titled “2.1 Service bootstrap”
  • same structure as Auth
  • internal API only

2.2 Database

Section titled “2.2 Database”

Tables

Section titled “Tables”
  • companies
  • modules
  • packages
  • addons
  • package_modules
  • addon_modules
  • company_addresses
  • company_profiles
  • company_social_links
  • company_documents
  • company_subscriptions
  • company_addons
  • company_entitlement_versions
  • entitlement_history
  • billing_products

2.3 Catalog management

Section titled “2.3 Catalog management”

Tasks

Section titled “Tasks”
  • CRUD modules
  • CRUD packages
  • CRUD addons
  • mapping tables

2.4 Company entitlements

Section titled “2.4 Company entitlements”

Tasks

Section titled “Tasks”
  • create company master row
  • create company addresses
  • create company profile record
  • create company social links
  • create company documents
  • update company lifecycle state
  • persist billing product/provider mapping structure
  • support company statuses:
    • draft
    • pending_payment
    • active
    • suspended
    • rejected
    • archived
  • activate Basic
  • deactivate Basic
  • activate addon
  • deactivate addon
  • update dates
  • update status
  • bump version

2.5 Core APIs

Section titled “2.5 Core APIs”

Company creation and lifecycle

Section titled “Company creation and lifecycle”

POST /internal/companies
PATCH /internal/companies/{companyId}
GET /internal/companies/{companyId}

Company entitlements (used by Auth)

Section titled “Company entitlements (used by Auth)”

GET /internal/companies/{companyId}/entitlements

Returns:

  • active Basic subscription
  • active addons
  • enabled modules
  • entitlementVersion

Catalog APIs (used by Platform Admin)

Section titled “Catalog APIs (used by Platform Admin)”

GET /internal/catalog/modules
GET /internal/catalog/packages
GET /internal/catalog/addons

POST /internal/catalog/modules
POST /internal/catalog/packages
POST /internal/catalog/addons

Company subscription management

Section titled “Company subscription management”

POST /internal/companies/{companyId}/basic
POST /internal/companies/{companyId}/addons

Rules

Section titled “Rules”
  • These endpoints are internal only
  • Must require service-to-service authentication
  • Must NOT be exposed publicly

2.6 Entitlement invalidation

Section titled “2.6 Entitlement invalidation”

Tasks

Section titled “Tasks”
  • bump version
  • notify Auth
  • clear cache

2.7 Company creation flows

Section titled “2.7 Company creation flows”

A. Admin-created company

Section titled “A. Admin-created company”
  1. Platform Admin frontend submits company form to Platform Admin backend
  2. Platform Admin backend creates Core.companies row
  3. Core sets lifecycle state, creation source, and optional contact/billing fields
  4. Core creates initial entitlement version row
  5. Platform Admin backend may then create initial Auth membership(s)

B. Self-serve checkout company

Section titled “B. Self-serve checkout company”
  1. Frontend starts self-serve checkout
  2. checkout/backend creates Core.companies row first
  3. Core stores:
    • created_via = self_serve
    • status = pending_payment
  4. checkout/backend creates or prepares company_subscriptions / company_addons
  5. after payment confirmation, Core activates subscription state
  6. Core bumps entitlement version
  7. Auth creates or activates initial membership(s) for the company creator

Rule

Section titled “Rule”

Both flows must create the same authoritative company row in Core first.

Core company setup must support the full company structure:

  • companies
  • company_addresses
  • company_profiles
  • company_social_links
  • company_documents
  • company_subscriptions
  • company_addons
  • entitlement/version tables

3. BUSINESS BACKENDS

Section titled “3. BUSINESS BACKENDS”

3.1 Shared middleware

Section titled “3.1 Shared middleware”

Every backend MUST:

  1. validate JWT
  2. resolve x-org
  3. load access from Auth:
   GET /auth/me/access
  1. check module
  2. check permission
  3. proceed or 403

3.2 Basic Backend

Section titled “3.2 Basic Backend”

Rules

Section titled “Rules”
  • requires Basic subscription
  • requires basic module

3.3 Finance Backend

Section titled “3.3 Finance Backend”

Rules

Section titled “Rules”
  • MUST check module:
  module = "finance"
  • MUST check permission:
  finance.*
  • MUST reject if:
  module disabled → 403
  permission missing → 403

3.4 Market Backend

Section titled “3.4 Market Backend”

Rules

Section titled “Rules”
  • requires market module

3.5 Touring Backend

Section titled “3.5 Touring Backend”

Rules

Section titled “Rules”
  • requires touring module

3.6 Venue Backend

Section titled “3.6 Venue Backend”

Rules

Section titled “Rules”
  • requires venue module

3.7 AI Backend

Section titled “3.7 AI Backend”

Rules

Section titled “Rules”
  • requires ai module

4. CROSS-SERVICE TASKS

Section titled “4. CROSS-SERVICE TASKS”

4.1 x-org

Section titled “4.1 x-org”
  • must be required header
  • must resolve company

4.2 Caching

Section titled “4.2 Caching”
  • implement Redis keys
  • implement invalidation

4.3 Observability

Section titled “4.3 Observability”

Track:

Section titled “Track:”
  • login errors
  • auth failures
  • permission denials
  • cache hits/misses

4.4 Internal service authentication

Section titled “4.4 Internal service authentication”

All internal calls must be secured.

Required for:

  • Auth → Core
  • Backends → Auth (optional)

Options:

  • internal JWT
  • shared secret
  • mTLS (preferred for production)

Never expose internal endpoints publicly.

5. PLATFORM ADMIN BACKEND

Section titled “5. PLATFORM ADMIN BACKEND”

This backend interacts with Platform Core.

Tasks

Section titled “Tasks”
  • manage packages (Core)
  • manage modules (Core)
  • manage permissions (Auth)
  • create companies in Core
  • approve companies by updating Core company lifecycle state
  • manage subscriptions (Core)

6. FINAL RULES

Section titled “6. FINAL RULES”
  • Auth = access truth
  • Core = commercial truth
  • Backend = execution
  • Frontend = UI only

END OF DOCUMENT

Section titled “END OF DOCUMENT”