Skip to content

ABS Platform Entity Model

This document provides a comprehensive view of the ABS Platform data model, linking the GraphQL schema to its persistent ORM implementation.

Entity Relationship Diagram

The complete entity model is visualized in the following diagram:

ABS Platform ERD

Source: entities-erd.puml

Schema-to-ORM Mapping

Core Business Entities

ServicePlan (Central Hub)

  • GraphQL Type: ServicePlan
  • ORM Table: service_plans
  • Key Relationships:
  • template_id → ServicePlanTemplate (Many-to-One)
  • service_account_id → ServiceAccount (One-to-One)
  • payment_account_id → PaymentAccount (One-to-One)

ServicePlanTemplate (Configuration)

  • GraphQL Type: ServicePlanTemplate
  • ORM Table: service_plan_templates
  • Key Features:
  • Immutable configuration
  • Version pinning for contract stability
  • Country-specific legal terms
  • FSM references (service_cycle_fsm, payment_cycle_fsm)

Service & ServiceBundle

  • GraphQL Types: Service, ServiceBundle
  • ORM Tables: services, service_bundles
  • Relationship: Many-to-Many via bundle_services join table
  • Asset Integration: References Thing Microservice for FLEET/ITEM assets

State Management

Embedded States

These are embedded JSON objects, not separate tables: - ServiceState - Runtime service usage tracking - ServiceConfiguration - Template-level service parameters
- CommonState - Plan lifecycle state - MealyTransition - FSM transition definitions

Reference Entities

Separate tables for analytics and cross-plan analysis: - ServiceAction - Service usage history - PaymentAction - Payment transaction history - MealyStateRecord - FSM execution audit trail

FSM System

MealyFSM

  • GraphQL Type: MealyFSM
  • ORM Table: mealy_fsms
  • Purpose: Template definitions for service and payment cycles
  • Key Feature: Enforced initial_state consistency

Account Management

ServiceAccount & PaymentAccount

  • ORM Tables: service_accounts, payment_accounts
  • Binding: One-to-One with ServicePlan
  • History Tracking: Via separate Action entities

Key Design Patterns

Template-Instance Pattern

  • Templates: Immutable configuration (ServicePlanTemplate)
  • Instances: Runtime state (ServicePlan)
  • Versioning: Contract stability through version pinning

Embedded vs Referenced

  • Embedded: Configuration and state objects (no separate IDs)
  • Referenced: Entities requiring cross-plan analysis
  • Binding: One-to-One relationships with FK constraints
  • Shared: Many-to-One relationships (templates, FSMs)

FSM-Driven State Management

  • Service Cycle: Operational state transitions
  • Payment Cycle: Financial state transitions
  • Agent Integration: External signals → FSM inputs

Asset Type Handling

  • FLEET: Dynamic asset assignment at service time
  • ITEM: Static asset assignment throughout lifecycle
  • Thing Microservice: External asset management integration

Persistence Considerations

Database Constraints

  • Referential Integrity: FK constraints for bindings
  • Uniqueness: Template versions, plan-account relationships
  • Validation: FSM initial_state consistency

JSON Schema Validation

  • Domain-Specific Fields: agent_state, agent_params
  • Embedded Objects: ServiceState, ServiceConfiguration
  • FSM Definitions: States, inputs, outputs arrays

Performance Optimizations

  • O(1) FSM Operations: Precomputed transition maps
  • Aligned Arrays: ServiceBundle.services ↔ ServiceAccount.service_states
  • Indexing Strategy: Template lookups, customer queries

Integration Points

External Systems

  • Thing Microservice: Asset management (FLEET/ITEM)
  • Odoo CRM: Commercial operations sync
  • MQTT Messaging: IoT device communication

Agent System

  • Function-Based: Pure calculation functions
  • Context Injection: Rich execution environment
  • Signal Generation: FSM input emission

For implementation details, see the Agent Specification.