Welcome to ABS Platform Documentation¶

Welcome to the ABS Platform - a comprehensive Asset-Based Services Platform within the DIRAC framework ecosystem. This documentation is organized to serve three distinct audiences:

🏢 For Business Leaders¶

Understanding the business value and market opportunity

Business Overview - Executive summary and business value proposition
Market Position - Competitive landscape and strategic positioning
Service Offerings - Complete service portfolio and packages
ROI & Analytics - Business metrics and performance indicators
Implementation Timeline - Business rollout phases and milestones

🏗️ For System Architects¶

Understanding the technical architecture and design decisions

Architecture Overview - High-level system architecture
DIRAC Framework - Integration within DIRAC ecosystem
Core Technologies - Technology choices and rationale
Design Patterns - Architectural patterns and principles
Integration Points - External system integrations

👨‍💻 For Developers¶

Implementation guides and technical specifications

Quick Start - Getting started with development
Development Guidelines - Coding standards and practices

🚀 New to ABS Platform?¶

Start with Business Overview to understand the platform's purpose and value.

🔧 Planning an Implementation?¶

Review Architecture Overview for technical design decisions.

💻 Ready to Code?¶

Jump to Quick Start for immediate development setup.

About This Documentation¶

This documentation follows a three-tier approach: - Business: Focus on value, outcomes, and strategic decisions - Architecture: Focus on design, patterns, and system interactions
- Developer: Focus on implementation, code, and operational details

Each section is designed to be independent while providing clear pathways to deeper technical detail when needed.

Overview¶

The ABS Platform is a comprehensive solution for managing battery swap services with advanced state management using optimized O(1) Finite State Machines (FSMs) and data-driven agents for reactive state handling. Built on a microservices architecture with GraphQL APIs and event-driven messaging within the DIRAC ecosystem.

🎯 Key Features¶

Optimized FSM Implementation¶

O(1) Performance: Precomputed transition maps for constant-time lookups
Mathematically Correct: Implements pure functions 𝑓:(𝑆,Σ)→(𝑆′,𝑃(Λ))
Template/Instance Pattern: ServicePlanTemplate → ServicePlan instance model
Set-Based Outputs: Supports multiple outputs per transition
GraphQL-First: Complete API with type safety

Data-Driven Agent Architecture¶

Function-Based: Agent logic as pure TypeScript functions
Plugin System: Extensible agent registration and execution
Context Injection: Rich context with utilities for complex calculations
Type Safety: Strongly typed with generics for all state types
Battery-Centric FSM: Asset tracking with BATTERY_ISSUED ⟷ BATTERY_RETURNED cycles

🏗️ DIRAC Framework Integration¶

Architecture Overview¶

The ABS Platform operates within the DIRAC Framework with six core components: - UXI: Unified User Experience Platform - FED: Federated API Layer
- BRO: Messaging Broker Exchange - ARM: Asset Relations Management - ABS: Asset-Based Services (this platform) - BIA: Business Intelligence & Analytics

Technology Stack¶

Backend: Node.js + TypeScript + Apollo GraphQL Server
Frontend: React.js with GraphQL client
Database: TypeORM with relational database
Messaging: MQTT for IoT, RabbitMQ for internal events
Workflow: n8n for external system integration
Deployment: Kubernetes
External Systems: Odoo CRM/Finance integration

🏗️ Architecture & Design¶

Architecture Overview - Complete system architecture
DIRAC Framework - Ecosystem overview
Design Guide - Agent development guide
Entity Model - Complete data model specifications

🔧 Developer Guides¶

Agent Specification Guide - Agent development guide
MQTT Guidelines - MQTT integration guide
Schema Alignment - Schema validation guide
Messaging Conventions - Unified messaging standards

📊 Current Status & Implementation¶

Architecture Overview - System architecture and design patterns

🚀 Quick Start Guide¶

For Understanding the Platform¶

Start Here: Agent Specification Guide - Core concepts and agent development
Architecture: ABS Hub Ecosystem - System overview
Agents: Agent Specification Guide - How to build agents

For Implementation¶

Messaging: Messaging Convention Dictionary - Communication patterns
FSM Design: FSM Duality Framework - State machine principles
Architecture Overview: Architecture Overview - System architecture and implementation status

🔋 Battery Swap Service (BSS)¶

The BSS is our flagship implementation demonstrating the platform's capabilities:

Complete business logic for battery swap operations
Integration with Odoo CRM/Finance systems
MQTT integration for IoT device communication
Multi-agent orchestration for complex workflows

Learn more about BSS implementation →

🎯 Current Status: Phase 5 Ready¶

✅ Completed Implementation¶

Core FSM Engine: O(1) performance with precomputed transition maps
GraphQL Schema: Complete schema with 840 lines of type definitions
ServicePlanTemplate System: Country-specific service product definitions
Battery Swap Service (BSS): Complete implementation with 8 canonical agent functions
Schema Alignment: All setup data files corrected and validated
Template-Driven Design: ServicePlanTemplate provides immutable configuration

🔧 Current Focus¶

BSS Agent Functions: Implementing canonical agent API
DIRAC Integration: FED/BRO/ARM interaction patterns
Odoo Integration: Commercial operations and subscription management

💻 Contributing¶

This documentation is built with MkDocs Material and is automatically deployed via GitHub Actions. For development and contributing guidelines, see our development documentation.

Need help? Check our development guide or explore the specific documentation sections above.