Central Scope & Responsibilities

Defining the boundaries of the Central Hub is critical for maintaining a clean architecture. Central is the "Operating System", Modules are the "Apps".

Golden Principles:
1. Central owns cross-cutting platforms concerns (Licensing, Auth, Audit).
2. Central owns shared master identity and org structure (People, Branches).
3. Modules own deep domain rules and workflows (Payroll, Tax).
4. Modules NEVER write to other module databases directly.

1) What Central OWNS ✅

The Central Hub handles the non-negotiable foundations required by every tenant.

Tenant Management: Creation, suspended status, onboarding wizards. (Why: Multi-tenancy is a platform concern)
Identity & Access (IAM): Centralized Users, Roles, Permissions (RBAC), and Authentication. (Why: SSO across modules)
Marketplace / Module Registry: Knowing which modules exist and which tenant has enabled what. (Why: Dynamic extensibility)
Billing & Licensing: Managing subscriptions, payments, and invoices for platform usage. (Why: Centralized revenue collection)
Global Master Data:
- People (Unique identity linked to User).
- Branches / Locations (Physical sites).
- Departments (Functional units).
(Why: Shared language across modules)
Audit Logs: A central timeline of "who did what". (Why: Unified compliance)

Scope Boundary Map

            flowchart TD
                User[User] --> FE[Frontend]
                FE --> GW[Gateway]
                
                subgraph Central_Zone [Central Shared Zone]
                    GW --> Central[Central Hub]
                    Central --> CDB[(Central DB)]
                    Central --> EBus{Event Bus}
                    Central -.-> Auth[Auth Service]
                    Central -.-> Bill[Billing Service]
                end

                subgraph Module_Zone [Module Isolation Zone]
                    EBus --> HRM[HRM Service]
                    EBus --> ATT[Attendance]
                    EBus --> ACC[Accounts]
                    
                    HRM --> HDB[(HRM DB)]
                    ATT --> ADB[(Attendance DB)]
                    ACC --> ACDB[(Accounts DB)]
                end
                
                style Central_Zone fill:#eef2ff,stroke:#6366f1
                style Module_Zone fill:#fff7ed,stroke:#f97316

2) What Central does NOT Own ❌

Central should know nothing about specific module business logic.

HRM Logic: Leave policies, payroll calculations, shift rostering, hiring pipelines.
Accounting: General ledgers, tax rules, P&L reports, depreciation schedules.
Inventory: Stock levels, SKUs, warehouses, batch tracking.
CRM: Leads, deals, pipelines, sales forecasting.

Rule of Thumb: If a feature involves a calculation or policy specific to a department (e.g., "Calculate Overtime"), it belongs in a Module, NOT Central.

Decision Guide

            flowchart TD
                Start([Feature Request]) --> Q1{Is it Auth, Tenant, or Billing?}
                Q1 -- Yes --> Central[Central Hub]
                Q1 -- No --> Q2{Is it Shared Master Data?}
                Q2 -- Yes --> CentralMaster[Central Master Tables]
                Q2 -- No --> Q3{Is it Domain Specific?}
                Q3 -- Yes --> Module[Specific Module]
                Q3 -- No --> Q4{Is it Tech Infrastructure?}
                Q4 -- Yes --> Infra[Gateway / EventBus]

                subgraph Notes [Examples]
                    N1[Central Master: People, Branches, Depts]
                    N2[Module: Payroll, Stock, CRM]
                end

                CentralMaster -.-> N1
                Module -.-> N2
                
                style Notes fill:transparent,stroke:none
                style N1 fill:#fff,stroke:#333,stroke-dasharray: 5 5
                style N2 fill:#fff,stroke:#333,stroke-dasharray: 5 5

3) Responsibility Matrix

Feature	Owner	Reason
User Login / SSO	Central	One identity for all modules.
Enable Module (e.g. Turn on HRM)	Central	Licensing and feature provisioning is a platform concern.
Add Employee (Person)	Central	Identity is shared (User + Employee Profile) across apps.
Apply for Leave	HRM Module	Leave policies are deep HR domain logic.
Create Payroll Slip	HRM Module	Complex calculation involving attendance and salary rules.
Create Invoice (B2B)	Accounts Module	Business transaction, not platform billing.
Generate Platform Subscription Invoice	Central	This is the bill for using the ERP software itself.
Post Ledger Entry	Accounts Module	Core accounting function.
Create Stock Item	Inventory Module	Inventory domain data.
Send Notification Template	Shared Service	Central provides the delivery mechanism, Modules provide the content.

4) Cross-Module Data Access

Modules often need data from each other or Central. The rule is: Async Events or Master Data Reference. Never direct DB access.

Correct Pattern: Event-Driven Sync

            sequenceDiagram
                participant Admin
                participant HRM
                participant Central
                participant Bus as EventBus
                participant ATT as Attendance

                Admin->>HRM: Update Employee Name
                HRM->>Central: Sync Name to Master People Table
                Central->>Bus: Publish 'person.updated'
                Bus->>ATT: Deliver 'person.updated'
                ATT->>ATT: Update local Read Model
                note over ATT: Now Attendance has the new name
without querying HRM explicitly.

5) Common Mistakes to Avoid

❌ Bad Practice

Putting "Leave Approval" logic in the Central User table.
Attendance Module querying `hrm_employees` table directly.
Hardcoding module-specific permissions in Central seeder.
Logging audit trails without `tenant_id`.

✅ Correct Approach

Keep Central thin; User table only has auth fields.
Use Events or Central Master Data for cross-module needs.
Modules seed their own permissions on enablement.
Middleware injects `tenant_id` into every log entry.

Key Takeaways:

Central = Platform (Auth, Billing, Master Data).
Modules = Domain (Logic, Workflows, Specific Data).
Communication = Events (Async) or Master IDs (Ref).
Isolation = Strict DB separation per module.