Backend Implementation Plan

Detailed Backend Tasks (Auth / Core / Modules)

---

Backend Documentation Structure

This phase is split into multiple documents:

• Auth Backend (fully implemented API) → See: 2.1.-Backend-Auth.

• Platform Core Backend (to implement) → See: 2.2.-Backend-Core.

• Module Backends (Finance / Market / Touring / Venue / AI) → Defined in this document

---

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

The Auth service is already implemented and should not be modified structurally.

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: 👉 2.1.-Backend-Auth.md

Auth depends on Platform Core for company entitlements.

See Core implementation in section: 👉 2.2.-Backend-Core.md

---

Important integration note

Auth integrates with Platform Core to resolve company entitlements.

Flow:

1. Frontend calls /auth/me/access
2. Auth loads:
   • user grants (Auth DB)
3. Auth calls Platform Core:
   • GET /internal/companies/{companyId}/entitlements
4. Auth merges:

effectiveAccess = entitlements ∩ userGrants

5. Auth returns final access model

1.1 Service bootstrap

Tasks

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

Must include

• request ID middleware
• panic recovery middleware
• timeout middleware
• CORS config (for frontend)

---

1.2 Database setup (PostgreSQL)

Tables

• users
• sessions
• company_memberships
• membership_module_grants
• permissions
• membership_permissions
• membership_delegation_policies

Tasks

• create migrations
• setup connection pooling
• add retry logic
• validate schema at startup

---

1.3 Redis setup

Purpose

• access cache
• session cache
• revocation
• rate limits

Tasks

• connect Redis client
• namespace keys
• implement TTL strategy
• add fallback if Redis down

---

1.4 JWT system

Tasks

• generate RSA keypair
• expose JWKS endpoint
• implement token signing
• implement token verification

Validate

• exp
• iss
• aud
• tokenVersion
• sessionId

---

1.5 Session system

Tasks

• create session on login
• store hashed refresh token
• revoke session
• revoke all sessions
• check session validity on request

---

1.6 Auth endpoints

Implement:

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

Tasks

• validate inputs
• standardize responses
• implement error codes
• rate limit login

---

1.7 Membership + access system

Tasks

• load membership by user + company
• load module grants
• load permissions
• load delegation

---

1.8 Access aggregation

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

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

---

1.9 Access cache

Key format

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

Tasks

• store cache
• invalidate on change
• fallback to DB if miss

---

1.10 Tenant management APIs

Tasks

• list users
• create membership
• update membership
• grant modules
• revoke modules
• grant permissions
• revoke permissions
• update delegation

---

2. PLATFORM CORE BACKEND

2.1 Service bootstrap

• same structure as Auth
• internal API only

---

2.2 Database

Tables

• modules
• packages
• addons
• package_modules
• addon_modules
• company_subscriptions
• company_addons

---

2.3 Catalog management

Tasks

• CRUD modules
• CRUD packages
• CRUD addons
• mapping tables

---

2.4 Company entitlements

Tasks

• activate Basic
• deactivate Basic
• activate addon
• deactivate addon
• update dates
• update status
• bump version

---

2.5 Core APIs

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)

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

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

---

Rules

• These endpoints are internal only
• Must require service-to-service authentication
• Must NOT be exposed publicly

---

2.6 Entitlement invalidation

Tasks

• bump version
• notify Auth
• clear cache

---

3. BUSINESS BACKENDS

3.1 Shared middleware

Every backend MUST:

1. validate JWT
2. resolve x-org
3. load access from Auth:

   GET /auth/me/access

4. check module
5. check permission
6. proceed or 403

---

3.2 Basic Backend

Rules

• requires Basic subscription
• requires basic module

---

3.3 Finance Backend

Rules

• MUST check module:

  module = "finance"

• MUST check permission:

  finance.*

• MUST reject if:

  module disabled → 403
  permission missing → 403

---

3.4 Market Backend

Rules

• requires market module

---

3.5 Touring Backend

Rules

• requires touring module

---

3.6 Venue Backend

Rules

• requires venue module

---

3.7 AI Backend

Rules

• requires ai module

---

4. CROSS-SERVICE TASKS

4.1 x-org

• must be required header
• must resolve company

---

4.2 Caching

• implement Redis keys
• implement invalidation

---

4.3 Observability

Track:

• login errors
• auth failures
• permission denials
• cache hits/misses

---

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

This backend interacts with Platform Core.

Tasks

• manage packages (Core)
• manage modules (Core)
• manage permissions (Auth)
• approve companies
• manage subscriptions (Core)

---

6. FINAL RULES

• Auth = access truth
• Core = commercial truth
• Backend = execution
• Frontend = UI only

---

END OF DOCUMENT