Backend-Modules

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 Module Backends Domain.

Modules are:

independent backend services responsible for specific business domains

Examples:

• Finance
• Market
• Touring
• Venue
• AI

---

2. Position in architecture

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

Modules:

• DO NOT compute access
• DO NOT call Core for authorization
• DO NOT decide permissions
• ONLY enforce via middleware

---

3. Module catalog (initial)

Module	Description
basic	core platform features (events, dashboard, artists, etc.)
finance	expenses, income, settlements, accounting
market	contracts, deals, artist booking
touring	tours, routing, schedules
venue	venue management, availability
ai	analytics, copilots, predictions

3.1 Module documentation links

Each module backend must have its own detailed documentation.

Use the following structure:

• Finance Backend
• Market Backend
• Touring Backend
• Venue Backend
• AI Backend

---

Notes

• Each file defines:
  • module architecture
  • API
  • integration
  • permissions
• All modules MUST follow this document (2.3.-Backend-Modules.md)

---

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:

• Finance can exist without Basic
• Market can exist without Basic
• Venue can exist without Market
• AI can exist without any other module

---

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 → Base backend (shared entities)
Module → own DB

Examples:

• Finance reads Events from Base
• Market reads Artists from Base
• Venue reads Events from Base

---

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:

• availability
• layouts
• bookings

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:

• 2.11.-Error-Contract.md

---

11. Caching

Modules:

• may use local cache for performance
• MUST NOT cache access incorrectly
• MUST rely on Auth cache strategy (2.7)

---

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.