# opencord/voltha-openolt-adapter architecture

> Architecture diagram of the GitHub repository opencord/voltha-openolt-adapter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/opencord/voltha-openolt-adapter
- Repository: https://github.com/opencord/voltha-openolt-adapter

## Overview

##### Project type and purpose
- This is a Go-based “adapter” microservice that acts as a bridge between the VOLTHA core control plane and an OLT device running the OpenOLT agent.
- There is no UI; it’s purely a backend service packaged as a Docker image, driven via CLI (`cmd/openolt-adapter`) and configured through files and environment variables.

##### File structure
- cmd/openolt-adapter: the entry point (main.go), profile.go, release.go, common.go, tests
- internal/pkg: subdivided into
- config: reads CLI flags, environment variables, YAML/JSON files
- core: contains device_handler, event manager, flow manager, group manager, stats manager, state transitions, and OpenOLT client abstractions
- resourcemanager: allocates resources per ONU, maintains mappings
- olterrors: error definitions and handling utilities
- pkg/mocks: mock clients for unit testing each external dependency (VOLTHA core, KV store, OpenOLT agent, etc.)
- Docker and compose files: containerization and Kubernetes/Kind integration
- Vendor, go.mod/go.sum: dependency management

##### README for additional insights
- Describes the adapter’s purpose: connect VOLTHA core to OpenOLT agent
- Lists Makefile and Docker targets like `docker-build`, `docker-push`, `test`, `lint`
- Explains how to swap in local copies of voltha-protos and voltha-lib-go

##### Final recommendations
- Container boundary (Docker) around the service to separate it from external systems
- That resource manager and error handling are visible—they’re crucial extensibility points

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Adapter Service Container"
        direction TB
        subgraph "Configuration Layer"
            direction TB
            ConfigLoader["Configuration Loader"]:::config
            CLICommon["CLI Common Utilities"]:::config
        end
        subgraph "Core Modules"
            direction TB
            CommonDefs["Core Package Common Definitions"]:::core
            EventMgr["Event Manager"]:::core
            DeviceHandler["Device Handler"]:::core
            StateTransMgr["State Transition Manager"]:::core
            FlowMgr["Flow Manager"]:::core
            GroupMgr["Group Manager"]:::core
            StatsMgr["Stats Manager"]:::core
        end
        subgraph "Resource Manager Layer"
            direction TB
            ResCommon["Resource Manager Common Definitions"]:::resource
            ResManager["Resource Manager"]:::resource
        end
        subgraph "Error Handling Layer"
            direction TB
            ErrCommon["Error Package Common Definitions"]:::error
            ErrorHandler["Error Handling Layer"]:::error
        end
    end

    subgraph "External Interfaces"
        direction TB
        VOLTHACoreClient["VOLTHA Core Client Interface"]:::external
        OpenOLTClient["OpenOLT Agent Client"]:::external
    end

    subgraph "Deployment Artifacts"
        direction TB
        Dockerfile["Dockerfile"]:::deployment
        DockerCompose["Docker Compose Config"]:::deployment
    end

    subgraph "Testing & Mocks"
        direction TB
        Mocks["Mock Clients for Testing"]:::tests
        ConfigTests["Configuration Tests"]:::tests
        CoreTests["Core Module Tests"]:::tests
        ResTests["Resource Manager Tests"]:::tests
        EntryTests["Entry Point Tests"]:::tests
    end

    %% Relationships
    ConfigLoader -->|"initializes"| EventMgr
    ConfigLoader -->|config flags| CLICommon
    CLICommon -->|provides args| EventMgr

    VOLTHACoreClient -->|"control messages"| EventMgr
    EventMgr -->|delegates| DeviceHandler
    DeviceHandler -->|executes| StateTransMgr
    StateTransMgr -->|manages flows| FlowMgr
    StateTransMgr -->|manages groups| GroupMgr
    StateTransMgr -->|collects stats| StatsMgr
    FlowMgr -->|"gRPC/REST calls"| OpenOLTClient
    GroupMgr -->|"gRPC/REST calls"| OpenOLTClient
    StatsMgr -->|"gRPC/REST calls"| OpenOLTClient

    OpenOLTClient -->|"events/stats"| EventMgr
    EventMgr -->|"forwards"| VOLTHACoreClient

    DeviceHandler -->|"tracks resources"| ResManager
    ResManager -->|"allocations data"| DeviceHandler

    %% Error Handler interactions
    EventMgr -->|error| ErrorHandler
    DeviceHandler -->|error| ErrorHandler
    StateTransMgr -->|error| ErrorHandler
    FlowMgr -->|error| ErrorHandler
    GroupMgr -->|error| ErrorHandler
    StatsMgr -->|error| ErrorHandler
    ResManager -->|error| ErrorHandler

    %% Deployment
    Dockerfile -->|builds image| AdapterServiceContainer(("Adapter Service Container"))
    DockerCompose -->|orchestrates| AdapterServiceContainer

    %% Testing & Mocks
    Mocks -->|injects| VOLTHACoreClient
    Mocks -->|injects| OpenOLTClient
    ConfigTests -->|tests| ConfigLoader
    CoreTests -->|tests| DeviceHandler
    CoreTests -->|tests| StateTransMgr
    CoreTests -->|tests| EventMgr
    CoreTests -->|tests| FlowMgr
    CoreTests -->|tests| GroupMgr
    CoreTests -->|tests| StatsMgr
    ResTests -->|tests| ResManager
    EntryTests -->|tests| CLICommon

    %% Click Events
    click ConfigLoader "https://github.com/opencord/voltha-openolt-adapter/blob/master/internal/pkg/config/config.go"
    click CLICommon "https://github.com/opencord/voltha-openolt-adapter/blob/master/cmd/openolt-adapter/common.go"
    click DeviceHandler "https://github.com/opencord/voltha-openolt-adapter/blob/master/internal/pkg/core/device_handler.go"
    click StateTransMgr "https://github.com/opencord/voltha-openolt-adapter/blob/master/internal/pkg/core/olt_state_transitions.go"
    click EventMgr "https://github.com/opencord/voltha-openolt-adapter/blob/master/internal/pkg/core/openolt_eventmgr.go"
    click FlowMgr "https://github.com/opencord/voltha-openolt-adapter/blob/master/internal/pkg/core/openolt_flowmgr.go"
    click GroupMgr "https://github.com/opencord/voltha-openolt-adapter/blob/master/internal/pkg/core/openolt_groupmgr.go"
    click StatsMgr "https://github.com/opencord/voltha-openolt-adapter/blob/master/internal/pkg/core/statsmanager.go"
    click OpenOLTClient "https://github.com/opencord/voltha-openolt-adapter/blob/master/internal/pkg/core/openolt.go"
    click VOLTHACoreClient "https://github.com/opencord/voltha-openolt-adapter/blob/master/internal/pkg/core/openoltInterAdapter.go"
    click ResManager "https://github.com/opencord/voltha-openolt-adapter/blob/master/internal/pkg/resourcemanager/resourcemanager.go"
    click ErrorHandler "https://github.com/opencord/voltha-openolt-adapter/blob/master/internal/pkg/olterrors/olterrors.go"
    click Dockerfile "https://github.com/opencord/voltha-openolt-adapter/blob/master/docker/Dockerfile.openolt"
    click DockerCompose "https://github.com/opencord/voltha-openolt-adapter/blob/master/compose/adapters-openolt-go.yml"
    click Mocks "https://github.com/opencord/voltha-openolt-adapter/tree/master/pkg/mocks"
    click CommonDefs "https://github.com/opencord/voltha-openolt-adapter/blob/master/internal/pkg/core/common.go"
    click ResCommon "https://github.com/opencord/voltha-openolt-adapter/blob/master/internal/pkg/resourcemanager/common.go"
    click ErrCommon "https://github.com/opencord/voltha-openolt-adapter/blob/master/internal/pkg/olterrors/common.go"
    click ConfigTests "https://github.com/opencord/voltha-openolt-adapter/blob/master/internal/pkg/config/config_test.go"
    click CoreTests "https://github.com/opencord/voltha-openolt-adapter/tree/master/internal/pkg/core/"
    click ResTests "https://github.com/opencord/voltha-openolt-adapter/blob/master/internal/pkg/resourcemanager/resourcemanager_test.go"
    click EntryTests "https://github.com/opencord/voltha-openolt-adapter/blob/master/cmd/openolt-adapter/main_test.go"

    %% Styles
    classDef config fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px
    classDef resource fill:#FFA500,stroke:#333,stroke-width:1px
    classDef error fill:#FF6347,stroke:#333,stroke-width:1px
    classDef external fill:#9370DB,stroke:#333,stroke-width:1px
    classDef deployment fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef tests fill:#C0C0C0,stroke-dasharray: 5 5,stroke:#333,stroke-width:1px
    classDef default stroke:#333,stroke-width:1px
```
