# seiggy/arke architecture

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

- Interactive diagram: https://gitdiagram.com/seiggy/arke
- Repository: https://github.com/seiggy/arke

## Overview

##### Project type and purpose
- Arke is a .NET 5.0–based IVR framework for Asterisk ARI.
- It provides:
- A core SIP/IVR engine (Arke.SipEngine)
- A DSL for defining call flows (Arke.DSL)
- A runtime host service (Arke.ServiceHost)
- A management REST API (Arke.ManagementApi)
- A plugin system of steps (Arke.Steps)
- Dependency-injection helpers (Arke.DependencyInjection)

##### File structure (key top-level projects)
- Arke.SipEngine: the core call logic, bridging, event handling, FSM, and Asterisk ARI client.
- Arke.DSL: JSON-based call-flow definitions and processors.
- Arke.DependencyInjection: abstractions and container extensions.
- Arke.IVR: glue between SIP engine and DSL (call-flow service).
- Arke.ServiceHost: console/WebHost entry point, loads DI, DSL, plugins, and connects to Asterisk.
- Arke.ManagementApi: ASP.NET Core Web API exposing REST endpoints for flows, steps, sounds, monitoring.
- Arke.Steps: prebuilt step-plugin library implementing common IVR steps.
- Arke.Tests: unit/integration tests.
- AsteriskDockerDemo & sample: deployment examples and sample call flows.

##### README for additional insights
- Uses AsterNET.ARI client library to connect to Asterisk.
- Plugins auto-loaded at runtime from a directory.
- Highly modular: each step implements IStepProcessor/ISettings.
- Uses SimpleInjector for DI, Serilog for logging, Consul for service discovery (in SipEngine).

##### Main components and relationships

A. External Systems
1. Asterisk Server (ARI interface)
2. Consul (optional service registry)
3. External storage (if any – e.g., file system, database for call-flow JSON, recordings)

B. Runtime Hosts
1. Arke.ServiceHost
- Loads Arke.DependencyInjection container
- Loads JSON call-flow definitions via Arke.DSL
- Discovers and loads Arke.Steps plugins
- Instantiates ArkeCallFlowService (from Arke.IVR)
- Hosts AsterNET.ARI client (from Arke.SipEngine.Api)
2. Arke.ManagementApi (separate ASP.NET Core process)
- Exposes REST controllers for flows, sounds, steps, monitoring
- Reads/writes call-flow JSON files or backing store

C. Libraries (internal)
1. Arke.SipEngine
- API layer for ARI calls, events, DTMF, prompts, recordings
- FSM for call state machine
- Bridging implementations (Mix, Hold, Proxy, DTMF)
2. Arke.DSL
- JSON parser + DSLProcessor → sequence of IStepProcessor calls
3. Arke.IVR
- Coordinates SipEngine events with DSL execution via ICallFlowService

D. Plugin System
- Directory of .NET assemblies namespace “Arke.*”
- Each plugin assembly contains one or more IStepProcessor + ISettings
- Loaded dynamically by ServiceHost at startup

##### Architectural patterns & design principles
- Modular library services (SipEngine, DSL, DI)
- Micro-services style (ServiceHost / ManagementApi)
- Plugin architecture for extensibility
- FSM for robust call state transitions
- Asynchronous Task-based processing for high concurrency

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    subgraph "External Systems"
        direction TB
        AST["Asterisk Server (ARI)"]:::external
        CONSUL["Consul Service Registry"]:::external
        STORAGE["Storage (File system/DB)"]:::external
    end

    %% Runtime Hosts
    subgraph "Runtime Hosts"
        direction TB
        SH["Arke.ServiceHost"]:::runtime
        MA["Arke.ManagementApi"]:::runtime
    end

    %% ServiceHost Modules
    subgraph "Arke.ServiceHost Modules"
        direction TB
        DI["Dependency Injection (SimpleInjector)"]:::library
        DSLModule["DSL Loader"]:::library
        PLUGIN_LOADER["Plugin Loader"]:::library
        CALLFLOW_SVC["ArkeCallFlowService"]:::library
        ARI_CLIENT["AsterNET.ARI Client"]:::library
    end

    SH --> DI
    SH --> DSLModule
    SH --> PLUGIN_LOADER
    SH --> CALLFLOW_SVC
    SH --> ARI_CLIENT

    %% Management API Modules
    subgraph "Management API Modules"
        direction TB
        CONTROLLERS["API Controllers"]:::library
        STORE["JSON/DB Store"]:::library
    end

    MA --> CONTROLLERS
    MA --> STORE

    %% Core Libraries
    subgraph "Core Libraries"
        direction TB
        SIP["Arke.SipEngine"]:::library
        DSL_LIB["Arke.DSL"]:::library
        IVR_LIB["Arke.IVR"]:::library
    end

    CALLFLOW_SVC --> IVR_LIB
    ARI_CLIENT --> SIP
    DSLModule --> DSL_LIB

    %% Plugin System
    subgraph "Plugin System"
        direction TB
        PLG["Arke.Steps Plugins"]:::plugin
    end

    PLUGIN_LOADER --> PLG
    PLG -->|"implements IStepProcessor"| IVR_LIB

    %% Call Flow Execution Path
    AST -->|"Events"| SIP
    SIP --> IVR_LIB
    IVR_LIB --> DSL_LIB
    DSL_LIB --> PLG
    PLG --> SIP

    %% Interactions with External Systems
    SH -->|"Connects"| AST
    SH -->|"Registers"| CONSUL
    SH -->|"Reads/Writes"| STORAGE
    MA -->|"Reads/Writes"| STORAGE

    %% Click Events
    click SIP "https://github.com/seiggy/arke/tree/master/Arke.SipEngine/"
    click DSL_LIB "https://github.com/seiggy/arke/tree/master/Arke.DSL/"
    click DSL_LIB "https://github.com/seiggy/arke/blob/master/Arke.DSL/data/dslFirst.json"
    click DI "https://github.com/seiggy/arke/tree/master/Arke.DependencyInjection/"
    click IVR_LIB "https://github.com/seiggy/arke/tree/master/Arke.IVR/"
    click CALLFLOW_SVC "https://github.com/seiggy/arke/blob/master/Arke.IVR/ArkeCallFlowService.cs"
    click DSLModule "https://github.com/seiggy/arke/blob/master/Arke.IVR/DSL/DSLProcessor.cs"
    click SH "https://github.com/seiggy/arke/tree/master/Arke.ServiceHost/"
    click SH "https://github.com/seiggy/arke/blob/master/Arke.ServiceHost/Program.cs"
    click SH "https://github.com/seiggy/arke/blob/master/Arke.ServiceHost/WebApiStartup.cs"
    click SH "https://github.com/seiggy/arke/blob/master/Arke.ServiceHost/DefaultCallFlow.json"
    click MA "https://github.com/seiggy/arke/tree/master/Arke.ManagementApi/"
    click CONTROLLERS "https://github.com/seiggy/arke/tree/master/Arke.ManagementApi/Controllers/"
    click PLG "https://github.com/seiggy/arke/tree/master/Arke.Steps/"

    %% Styles
    classDef external fill:#CCCCCC,stroke:#333,stroke-width:1px
    classDef runtime fill:#AEDFF7,stroke:#333,stroke-width:1px
    classDef library fill:#CFFFCF,stroke:#333,stroke-width:1px
    classDef plugin fill:#FFDCA8,stroke:#333,stroke-dasharray:5 5
```
