# accurateproject/accurate architecture

> Architecture diagram of the GitHub repository accurateproject/accurate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/accurateproject/accurate
- Repository: https://github.com/accurateproject/accurate

## Overview

##### Project type and purpose
- Full-stack, Go-based real-time rating engine with:
– Event ingestion (Freeswitch, Kamailio, Diameter, SMG, etc.)
– Core rating/charging engine
– REST API & CLI console
– Configurable data stores (Mongo, MySQL, Postgres)
– Load balancing, caching, scheduling, and packaging

##### Top-level components (map to your file tree)
- Session Manager(s) (folder `sessionmanager`): protocol adapters for FreeSWITCH, OpenSIPS/Kamailio, Diameter, SMG
- Engine (folder `engine`): core rating logic (accounts, LCR, call cost, stats, triggers, derived charging) with internal pub/sub
- API Server (folder `api/v1` + `utils/server.go`): HTTP/JSON endpoints exposing accounts, CDRs, triggers, statistics
- CLI Console (folder `console` + `cmd/cc-console`): operator commands calling RPC/HTTP on the API Server
- Agents (folder `agents`): Diameter agent, DMT agent, HA pool connectors
- Load Balancer (folder `balancer2go`): incoming request distribution for high availability
- Cache (folder `cache2go`): in-memory TTL caching layer for tariff and lookup data
- Scheduler (folder `scheduler`): timed triggers and job queue
- Configuration Loader (folder `config` + `data/conf`): JSON/YAML configurations and model definitions
- Persistence:
– CDR store (Mongo/MySQL/Postgres via `engine/storage_*`)
– Metadata store (accounts, rating plans, triggers)
– History logger (folder `history`)
- Packaging & Deployment (`data/docker`, `packages/*`, Vagrant, scripts)

##### Interactions and data flows
- External telecom elements → Session Manager
– e.g. FreeSWITCH JSON CDR over event socket
– Kamailio via TCP events
– Diameter traffic
- Session Manager → Engine
– Transforms events into internal CDR representations
– Publishes to Engine’s pub/sub (`engine/pubsub.go`)
- Engine → Storage
– Writes rated CDRs to CDR DB
– Reads tariff plans, accounts, LCR rules from metadata store (cache layer)
– Emits statistics to stats queue & metrics subsystem
- API Server → Engine/Storage
– CRUD on accounts, triggers, tariff plans
– Query CDRs and stats
- CLI Console → API Server
– Ad‐hoc administrative commands (e.g. add account, reload config)
- Balancer sits in front of API Server & Engine (if sharded)
- Scheduler periodically enqueues triggers → Engine

##### Architectural patterns & design principles
- Modularity: each concern in its own Go package
- Pub/Sub: decouples ingestion from processing
- Adapter pattern: sessionmanager for each protocol
- Cache aside: cache2go for static lookup data
- Separation of concerns: API, engine, console, agents are separate binaries (`cmd/`)
- Config‐as‐code: JSON models under `data/conf` loaded at startup

##### Essential elements checklist
– Clear labels on every component (use folder/binary names)
– External systems (telecom switches, DB servers, operator console)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Telecom Networks
    FS["FreeSWITCH"]:::external
    Kam["Kamailio/OpenSIPS"]:::external
    DiamNet["Diameter Network"]:::external
    SMG["SMG"]:::external

    %% Ingestion Layer
    subgraph "Session Manager" 
        SM["Protocol Adapters"]:::ingestion
    end

    %% Core Engine Layer
    subgraph "Core Rating Engine"
        Engine["Engine (accounts, LCR, cost, stats)"]:::core
        PubSub["Internal Pub/Sub"]:::core
    end

    %% Caching & Metadata
    Cache["Cache2Go (TTL Cache)"]:::cache
    MetaDB["Metadata Store<br/>(Accounts, Plans, LCR)"]:::db
    ConfigFiles["Config Files"]:::config

    %% Persistence
    subgraph "Persistence"
        CDRDB["CDR Store<br/>(Mongo/MySQL/Postgres)"]:::db
        History["History Logger"]:::persistence
    end

    %% API & CLI Layer
    subgraph "Interface Layer"
        API["API Server (HTTP/JSON)"]:::interface
        Console["CLI Console"]:::interface
    end

    %% Agents & Scheduler
    Agents["Agents (Diameter, DMT, HA)"]:::ingestion
    Scheduler["Scheduler<br/>(timed triggers)"]:::core

    %% Load Balancer
    LB["Load Balancer"]:::infra

    %% Deployment
    subgraph "Packaging & Deployment"
        Docker["Docker Manifests"]:::deploy
        Vagrant["Vagrant Setup"]:::deploy
        Packages["Packaging Scripts"]:::deploy
    end

    %% Flows
    FS -->|"FS JSON CDR"| SM
    Kam -->|"TCP Events"| SM
    DiamNet -->|"Diameter Traffic"| SM
    SM -->|"Transformed CDR"| PubSub
    PubSub -->|"Feed to Engine"| Engine
    Scheduler -->|"Enqueue Triggers"| Engine
    Agents -->|"Agent Events"| Engine

    Engine -->|"Read/Write Metadata"| Cache
    Cache -->|"Cache Aside"| MetaDB
    Engine -->|"Write Rated CDR"| CDRDB
    Engine -->|"Write Logs"| History

    LB -->|"HTTP/JSON"| API
    Console -->|"RPC/HTTP"| API
    API -->|"CRUD & Queries"| Engine
    API -->|"Read Metadata"| Cache

    ConfigFiles -->|"Load on Startup"| ConfigFiles
    ConfigFiles -->|"Provide Config"| Engine
    ConfigFiles -->|"Provide Config"| API
    ConfigFiles -->|"Provide Config"| Console

    %% Deployment Connections
    Docker --> LB
    Docker --> SM
    Docker --> Engine
    Docker --> API
    Vagrant --> LB
    Packages --> Docker

    %% Click Events
    click SM "https://github.com/accurateproject/accurate/tree/master/sessionmanager/"
    click Engine "https://github.com/accurateproject/accurate/tree/master/engine/"
    click API "https://github.com/accurateproject/accurate/tree/master/api/v1/"
    click Server "https://github.com/accurateproject/accurate/blob/master/utils/server.go"
    click Console "https://github.com/accurateproject/accurate/tree/master/console/"
    click Console "https://github.com/accurateproject/accurate/blob/master/cmd/cc-console/cc-console.go"
    click Engine "https://github.com/accurateproject/accurate/blob/master/cmd/cc-engine/cc-engine.go"
    click Loader "https://github.com/accurateproject/accurate/blob/master/cmd/cc-loader/cc-loader.go"
    click Agents "https://github.com/accurateproject/accurate/tree/master/agents/"
    click LB "https://github.com/accurateproject/accurate/tree/master/balancer2go/"
    click Cache "https://github.com/accurateproject/accurate/tree/master/cache2go/"
    click Scheduler "https://github.com/accurateproject/accurate/blob/master/scheduler/scheduler.go"
    click ConfigFiles "https://github.com/accurateproject/accurate/tree/master/config/"
    click ConfigFiles "https://github.com/accurateproject/accurate/tree/master/data/conf/"
    click CDRDB "https://github.com/accurateproject/accurate/blob/master/engine/storage_mongo_cdrdb.go"
    click CDRDB "https://github.com/accurateproject/accurate/blob/master/engine/storage_mongo_datadb.go"
    click CDRDB "https://github.com/accurateproject/accurate/blob/master/engine/storage_interface.go"
    click History "https://github.com/accurateproject/accurate/tree/master/history/"
    click Docker "https://github.com/accurateproject/accurate/tree/master/data/docker/"
    click Packages "https://github.com/accurateproject/accurate/tree/master/packages/"
    click Vagrant "https://github.com/accurateproject/accurate/tree/master/data/vagrant/"

    %% Styles
    classDef ingestion fill:#cce5ff,stroke:#66b0ff
    classDef core fill:#d4edda,stroke:#28a745
    classDef cache fill:#e2e3e5,stroke:#6c757d
    classDef db fill:#fff3cd,stroke:#ffcd39
    classDef persistence fill:#ffe5d9,stroke:#ff7b00
    classDef interface fill:#f5e1ff,stroke:#b66dff
    classDef infra fill:#e2e3e5,stroke:#adb5bd
    classDef deploy fill:#f8d7da,stroke:#d63384
    classDef external fill:#e9ecef,stroke:#868e96
    classDef config fill:#fffbea,stroke:#ffe066
```
