Skip to content

Core Configuration & System Management Module

Overview

The Core module handles system-wide configuration, entity management, audit logging, error tracking, and user journey analytics. It provides foundational services used by all other modules.

API Prefix: /api/v1/core

Route Verification Status

  • Source Router: app/api/v1/endpoints/core.py
  • Live Route Count: 17
  • Verification State: Verified (2026-06-28)
  • Canonical Tracking: docs/API_ROUTE_DOCUMENTATION_TODO.md
  • Verification Method: Route decorators extracted from @r.<method>(...) in app/api/v1/endpoints/core.py.

Key Features

1. Entity Management

  • Create and manage core entities (Category, Type, Status)
  • Lifecycle management (staging, approval, disposition)
  • Entity relationships and hierarchies
  • Entity versioning and history
  • Bulk operations support

2. Configuration Management

  • System-wide configuration settings
  • Dictionary/lookup management
  • Translations and localization
  • Configuration versioning
  • Feature flags and toggles

3. Audit & Compliance

  • Complete audit trail of all operations
  • User action logging
  • System change tracking
  • Compliance report generation
  • Regulatory audit support

4. Error Tracking

  • Centralized error logging
  • Error categorization and classification
  • Error analytics and reporting
  • Error pattern detection
  • Exception handling

5. User Journey Analytics

  • Track user sessions and interactions
  • User activity timeline
  • User journey mapping
  • Behavior analysis
  • Usage metrics

6. Access Control

  • Access log tracking
  • Permission audit trail
  • Resource access monitoring
  • Unauthorized access detection
  • Security event logging

7. Dictionary & Translation

  • Multi-language support
  • Term and definition management
  • Translation management
  • Dynamic dictionary updates
  • Language-specific content

API Endpoints (Verified Against Live Router)

For the complete core endpoint inventory (all 17 routes with method, effective path, and source line), use: - docs/API_ROUTE_LIVE_REFERENCE.md -> section core.py (17 routes)

Integration and admin configuration routes are documented in: - docs/SUPPORTING_MODULES.md (integration, totp, config modules)

Permission Dependency Notes (Verified: Core)

Confirmed explicit permission checks in core.py include: - Entity lifecycle: add_entity, edit_entity, fetch_entity, decline_entity, dispose_entity, stage_entity, get_entity, delete_entity, lock_entity. - Audit and observability: fetch_audit, fetch_error, fetch_access.

Operational note: - Journey analytics routes currently include empty placeholders (permission_required("")) and should be made explicit.

Standard Error Response Matrix (Core)

{
  "status_code": 400,
  "error_code": "CORE_ERROR",
  "message": "Human-readable summary",
  "details": {}
}

Common mappings: - 400 invalid lifecycle transition or malformed request state. - 401 unauthenticated request. - 403 permission denied. - 404 entity/resource not found. - 409 conflicting state update. - 422 schema validation failure. - 429 throttled request. - 500 internal processing error.

Database Models

Entity Models

  • Entity (symbol: Entity in app/models/core.py)
  • Canonical entity table in schema core.
  • Key fields: id, name, code, description, active, currency_id, language_id, country_id.
  • Hierarchy relationships: parent_links and child_links via EntityParent.

  • Role association: roles via core.entity_roles.

  • EntityParent (symbol: EntityParent in app/models/core.py)

  • Parent-child relationship join model between Entity records.

  • Keys: entity_id, parent_id.

  • EntityParentStaging (symbol: EntityParentStaging in app/models/core.py)

  • Staged parent-child relationships before approval.

  • Keys: entity_staging_id, parent_id (plus linked entity_id).

  • EntityStaging (symbol: EntityStaging in app/models/core.py)

  • Staging copy of Entity used in lifecycle actions such as stage/decline/dispose/approve flows.

  • Includes decline_reason and staged role relationships via core.entity_roles_staging.

  • EntityRoles (symbol: EntityRoles in app/models/core.py)

  • Mapping between approved entities and user roles.

  • EntityRolesStaging (symbol: EntityRolesStaging in app/models/core.py)

  • Staging mapping between staged entities and roles.

  • Identity and IdentityType (symbols: Identity, IdentityType in app/models/core.py)

  • Identity backbone used by Entity and EntityStaging foreign key roots.

Configuration Models

  • ItemKind / Item / ItemTranslation: Dictionary and translation-backed lookup structures.
  • Language / Currency / Country / Status: Core reference datasets used by entity and platform workflows.
  • PlatformConfig: Singleton platform branding and organization configuration.

Audit & Logging Models

  • AuditLog: All system changes and actions
  • User ID, action type, resource
  • Before/after values
  • Timestamp, IP address

  • Success/failure status

  • ErrorLog: Application errors

  • Error type, message, stack trace
  • User/request context

  • Timestamp, frequency

  • AccessLog: Resource access tracking

  • User ID, resource, action
  • Granted/denied, timestamp
  • IP address, device info

Note: session identifiers are captured across AuditLog, ErrorLog, and AccessLog; there is no standalone SessionHistory model in app/models/core.py.

Journey Models

Journey analytics are exposed by core journey endpoints and derived from activity/audit data rather than dedicated UserJourney or SessionTimeline ORM models in app/models/core.py.

Entity Lifecycle

Standard Entity Flow

1. Create (Submission)
   ├─ Validate data
   ├─ Create entity record
   ├─ Set status: NEW
   └─ Save to database

2. Staging (Review)
   ├─ Move to staging status
   ├─ Ready for approval
   ├─ Can still be edited
   └─ Lock if needed

3. Approval/Activation
   ├─ Reviewer examines
   ├─ Approve or reject
   ├─ If approved: Set to ACTIVE
   ├─ If rejected: Set to DECLINED
   └─ Notify stakeholders

4. Active Use
   ├─ System can use entity
   ├─ Edits allowed (if not locked)
   ├─ Full audit trail maintained
   └─ Usage tracked

5. Deactivation/Disposal
   ├─ Mark as DISPOSED/INACTIVE
   ├─ Keep for compliance/audit
   ├─ Cannot be reactivated
   └─ Archive after retention period

Configuration Examples

System Configuration

{
  "key": "system.timezone",
  "value": "Africa/Lusaka",
  "type": "string",
  "editable": true,
  "scope": "global"
}

Feature Flags

{
  "key": "feature.ai_agent",
  "value": true,
  "type": "boolean",
  "scope": "global",
  "rollout_percentage": 100
}

Dictionary Entry

{
  "category": "transaction_type",
  "key": "p2p_transfer",
  "value": "Peer-to-Peer Transfer",
  "description": "Transfer between two customers",
  "language": "en"
}

Audit Trail Examples

Sample Audit Log Entry

{
  "id": "audit_123456",
  "user_id": "user_789",
  "action": "UPDATE",
  "resource_type": "Loan",
  "resource_id": "loan_456",
  "old_value": {
    "status": "pending",
    "score": 65
  },
  "new_value": {
    "status": "approved",
    "score": 75
  },
  "timestamp": "2024-06-20T14:30:00Z",
  "ip_address": "192.168.1.100",
  "user_agent": "Mozilla/5.0...",
  "status": "success"
}

Sample Error Log Entry

{
  "id": "error_789",
  "error_type": "ValidationError",
  "message": "Invalid transaction amount",
  "stack_trace": "...",
  "user_id": "user_123",
  "context": {
    "endpoint": "/api/v1/transaction/transfer",
    "method": "POST",
    "params": {...}
  },
  "timestamp": "2024-06-20T10:15:00Z",
  "frequency": 5
}

Controllers & Business Logic

Core Controllers

  • controller/core.py: Core configuration
  • get_configuration(): Retrieve config value
  • set_configuration(): Update config
  • get_dictionary(): Get lookup values

  • get_translations(): Get multi-language content

  • controller/entity.py: Entity management

  • create_entity(): Create new entity
  • stage_entity(): Move to staging
  • approve_entity(): Approve staged entity

  • get_entity_history(): Version history

  • controller/audit.py: Audit logging

  • log_action(): Log user action
  • log_error(): Log application error
  • log_access(): Log resource access

  • generate_audit_report(): Compliance report

  • controller/journey.py: User journey analytics

  • track_session(): Track user session
  • record_activity(): Record user action
  • get_user_journey(): Get user's activity path
  • analyze_behavior(): Analyze usage patterns

Common Use Cases

1. Adding New Transaction Type

1. Admin creates entity (Category: "TransactionType", Value: "QR Code Transfer")
2. Entity placed in staging
3. Manager reviews and approves
4. System now recognizes new transaction type
5. Audit log records all changes

2. Compliance Audit

1. Audit officer requests audit trail for specific user
2. System pulls all actions from AuditLog
3. Generates compliance report
4. Shows all changes with before/after values
5. Report certified and stored

3. Error Analysis

1. System logs error: "Database connection timeout"
2. Error aggregated with frequency count
3. Alert generated if frequency > threshold
4. Analytics show error patterns
5. System automatically retries if configured

4. User Journey Analysis

1. User logs in
2. Each action tracked (page view, transaction, etc.)
3. Session timeline created
4. Behavior patterns analyzed
5. Used for user experience improvement

Error Handling

Core Errors

  • ENTITY_NOT_FOUND: Entity doesn't exist
  • ENTITY_ALREADY_EXISTS: Duplicate entity
  • INVALID_STATE_TRANSITION: Cannot move entity to that state
  • CONFIGURATION_NOT_FOUND: Config key doesn't exist
  • TRANSLATION_NOT_AVAILABLE: Translation missing for language
  • AUDIT_UNAVAILABLE: Audit log temporarily unavailable

Performance Considerations

  1. Audit Logging: Async log writing to not block operations
  2. Dictionary Caching: Cache frequently used lookups
  3. Configuration Caching: Cache config values in Redis
  4. Archiving: Archive old audit logs periodically
  5. Indexing: Index audit logs by user, timestamp, resource

Security & Compliance

  1. Audit Immutability: Audit logs cannot be modified
  2. Encryption: Sensitive config values encrypted
  3. Access Control: Only admins can view audit logs
  4. Retention: Keep audit logs per compliance requirements
  5. Integrity: Verify audit log integrity periodically

Module Boundary Clarification

Core documentation is intentionally scoped to internal platform capabilities only: - Entity lifecycle and hierarchy. - Internal configuration and dictionaries. - Audit, access, and error observability. - Internal journey analytics.

All external provider and third-party concerns have been moved to: - docs/INTEGRATION_SERVICES.md

This includes CBS connectors, email/SMS gateways, biller integrations, and all /api/v1/integration/* endpoint documentation.