Backend Admin Specification

Related documentation: Kisum System · Backend implementation · Backend Core · Backend Auth · Admin API contract · Admin Platform Spec

Detailed Implementation Specification for Platform Admin Backend

Audience: backend engineers, platform-admin frontend engineers, operations, QA
Status: docs-first target specification with runtime notes
Scope: this page defines what the Admin backend is supposed to be in the new Kisum architecture, how it relates to Core, Auth, and Market, and how to interpret the current legacy Admin service during migration.

Current implementation snapshot

• Current runtime reality: Backend-Kisum-Admin already exists and exposes staff-only routes for approvals, artists, venues, files, AI, and companies.
• Current runtime reality: /api/v1/admin/companies is the Core tenant-company control-plane namespace, not the Market directory-company namespace.
• Current runtime reality: Backend-Kisum-Admin also exposes a separate Market-directory proxy namespace at /api/v1/admin/artists-directory/* for Market companies, people, taxonomy, and geo lookups.
• Current runtime reality: package/module/add-on/commercial-control routes are not yet implemented in the current Admin backend.
• Target architecture: Admin is the control plane where platform staff operate the system, but Core remains the source of truth for companies and commercial configuration, and Auth remains the source of truth for users, memberships, permissions, invitations, and delegation.

---

1. Final admin role in the platform

The Admin backend exists to answer this question:

What actions can platform staff take to operate the platform safely?

In the final architecture:

• Admin is the control plane
• Core is the commercial and company source of truth
• Auth is the identity and access source of truth
• Base and Modules are the business execution plane

This means:

• Admin initiates company and package actions
• Core stores company, package, add-on, subscription, and entitlement data
• Admin initiates delegation and access-governance actions
• Auth stores and computes permissions, memberships, grants, and delegation policy

Final rule

Admin writes the rules.
Core stores commercial truth.
Auth stores access truth.
Backends enforce the result.

---

2. What Admin owns versus what it orchestrates

2.1 Admin owns

Admin should own:

• platform staff operational APIs
• approval workflows
• staff-side orchestration flows
• audit trails for admin actions
• payment-provider configuration flows used by platform staff
• artist-management APIs
• venue-management APIs
• admin file-upload APIs
• admin AI helper APIs

2.2 Admin does not own

Admin must not become the long-term persistence owner for:

• company master records
• package catalog
• module catalog
• add-on catalog
• subscriptions
• entitlements
• user identities
• memberships
• permission grants
• delegation policy state

Those belong to:

• Core for company and commercial truth
• Auth for identity and access truth

Admin may still expose Artists-backed operational or directory routes, but in those cases it acts as a staff-side adapter/proxy to Backend-Kisum-Artists, not as the persistence owner.

2.3 What Admin should call

For commercial and company operations

Admin should call Core for:

• create company
• update company
• create package
• update package
• create module
• update module
• create add-on
• update add-on
• assign company package
• add or remove company add-ons
• read entitlements
• read company subscription summary
• read company commercial history

For access and delegation operations

Admin should call Auth for:

• platform staff invitations if Auth is the identity authority
• company membership updates
• permission grants
• module grants
• delegation rules and delegation limits

For artists-directory operations

Admin should call Market for:

• curated artist CRUD/read
• artists-directory company reads and writes
• people/contact reads and writes
• genre, subgenre, platform, and provider-source taxonomy reads
• company roster, location, people, and social-metric relations
• geo lookup reads used by the directory

---

3. Current service versus target service

3.1 Current Backend-Kisum-Admin

The current repository already has:

• bearer JWT validation through Auth JWKS
• platform-role checks
• real admin routes for:
  • approvals
  • artists
  • Market-directory proxy routes
  • venues
  • files
  • AI
• legacy company proxy routes

3.2 Deprecated overlap

The following current patterns must be considered deprecated when they conflict with the new architecture:

• Admin directly behaving as if it owns company persistence
• Admin being the commercial source of truth
• Admin UI/backend package assumptions that do not map to Core
• legacy company payload shapes that do not match the new Core company model

The following are not deprecated and remain valid Admin responsibilities:

• approvals
• artists
• Artists-backed artists-directory orchestration
• venues
• files
• AI helpers
• platform-staff user administration and orchestration into Auth

3.3 Migration interpretation

Until the runtime is fully updated:

• existing Admin routes may continue to exist
• documentation must still describe the target architecture first
• legacy routes should be labeled as migration-era or deprecated where necessary

Important route boundary:

• /api/v1/admin/companies = Core tenant-company control plane
• /api/v1/admin/artists-directory/companies = Market directory companies

---

4. Core responsibilities that Admin must expose

Admin is the platform staff surface for Core-driven operations.

That means Admin must provide UI and backend orchestration for:

4.1 Package management

Platform staff need to:

• create packages
• edit package metadata
• enable or disable packages
• map modules to packages

Underlying source of truth:

• Core

4.2 Module management

Platform staff need to:

• create modules
• edit module metadata
• enable or disable modules
• define what modules exist in the commercial catalog

Underlying source of truth:

• Core

4.3 Add-on management

Platform staff need to:

• create add-ons
• edit add-on metadata
• enable or disable add-ons
• map modules to add-ons

Underlying source of truth:

• Core

4.4 Company lifecycle

Platform staff need to:

• create company master records
• edit company metadata
• approve company onboarding
• reject company onboarding
• activate or deactivate a company

Underlying source of truth:

• Core for company record and commercial state
• approval/audit workflow may still be coordinated through Admin

4.5 Subscription and entitlement control

Platform staff need to:

• assign a package to a company
• upgrade or downgrade the package
• add or remove add-ons
• inspect entitlement output
• inspect subscription summary
• inspect history of changes

Underlying source of truth:

• Core

4.6 Delegation and access governance

Platform staff need to:

• define what tenant roles can grant
• restrict delegation boundaries
• set role-based grant limits

Underlying source of truth:

• Auth

---

5. Payment-provider configuration

The Admin backend should also be the privileged platform-staff surface for deployment/payment-provider configuration where relevant.

Examples:

• Stripe configuration
• Xendit configuration
• country or deployment specific payment setup

Important rule:

• Admin may provide the write surface
• the final persistence location must be explicitly defined in the implementation
• docs must state whether payment configuration belongs to Admin config, Core billing config, or another infra-owned config layer

For now, the documentation treats these as admin-owned operational flows that are still pending implementation detail.

---

6. Security model

6.1 Who can call Admin

Only platform staff.

Current roles accepted by the existing Admin runtime:

• PLATFORM_SUPERADMIN
• PLATFORM_ADMIN
• PLATFORM_MODERATOR

6.2 What Admin checks

Admin should check:

• bearer JWT validity
• platform staff eligibility

6.3 What Admin should not compute

Admin should not compute:

• effective tenant access
• tenant permissions for product flows
• company entitlements as source of truth

Admin triggers write operations, but the final business truth still belongs elsewhere.

---

7. Audit requirements

Every admin write action should produce auditable records, including:

• actor id
• actor platform role
• action name
• target type
• target id
• previous state
• new state
• timestamp
• request correlation id

This is especially important for:

• packages
• modules
• add-ons
• company lifecycle
• subscription changes
• delegation rule changes
• payment-provider configuration

---

8. Cache invalidation and downstream effects

Admin write operations are not isolated UI events. They change downstream runtime behavior.

Examples:

• package/add-on changes in Admin should lead to Core entitlement changes
• entitlement changes should invalidate access caches
• delegation changes in Admin should update Auth-side policy and invalidate access resolution caches

The admin docs must therefore always document:

• what system stores the change
• what downstream caches must be invalidated
• what user-facing behavior should change afterward

---

9. Recommended target route groups

The target Admin backend should expose logical route groups like:

• /api/v1/admin/packages
• /api/v1/admin/modules
• /api/v1/admin/addons
• /api/v1/admin/companies
• /api/v1/admin/company-approvals
• /api/v1/admin/company-subscriptions
• /api/v1/admin/delegation-rules
• /api/v1/admin/payment-providers
• /api/v1/admin/approvals
• /api/v1/admin/artists
• /api/v1/admin/venues
• /api/v1/admin/files
• /api/v1/admin/ai

The exact endpoint list and request bodies are defined in the Admin API contract page.

---

10. What the docs should treat as deprecated

The following should be documented as legacy or migration-era behavior when they still exist in code:

• direct legacy company proxy routes that bypass the new Core company model
• old package or permission assumptions from the older Admin/backend model
• frontend forms still shaped around legacy company documents or team structures from the monolith

These should not be documented as final platform truth.

---

11. Summary

The final Admin backend is not supposed to replace Core or Auth.

It is supposed to be the staff control plane that:

• exposes the privileged admin workflows
• orchestrates writes into Core and Auth
• keeps auditability and operational control centralized
• leaves company/commercial truth in Core
• leaves identity/access truth in Auth

That is the model all future Admin backend and frontend implementation should follow.