# Core Platform Architecture

**Asterisk 2** is a highly resilient, scalable multi-tenant Telephony Management System engineered on top of ASP.NET Core MVC. It functions as the administrative brain controlling distributed Asterisk PBX nodes, Dinstar SIM Banks, and automated AI logic layers.

---

## High-Level System Topology

The following diagram maps out the signal interfaces, control lifecycles, and database integration paths powering the Asterisk 2 ecosystem:

```mermaid
graph TD
    %% Client Layer
    subgraph Clients["Client Access Boundaries"]
        U_Web["Web Admin / Portal Browsers"]
        U_API["External API Handlers"]
    end

    %% Core Application Layer
    subgraph Core["Asterisk 2 Application Cluster"]
        MVC["ASP.NET Core MVC Engine"]
        API_Ctrl["API / MCP REST Controllers"]
        DI_Services["Domain Integration Services"]
        
        MVC --> DI_Services
        API_Ctrl --> DI_Services
    end

    %% Routing & Media Interception Layer
    subgraph Telephony["Telephony Core Infrastructure"]
        Kam["Kamailio SIP Proxy (Signal Routing)"]
        AstNode["Asterisk Realtime PBX Cluster"]
        FlowEng["AppFlow Logic Engine"]
        
        Kam -->|"SIP Route Dispatch"| AstNode
        AstNode <-->|"ARI Loop Interception"| FlowEng
    end

    %% Distributed Data Tier
    subgraph DataTier["Segregated Entity Contexts"]
        DB_App[("AppDbContext<br/>(Tenants, Users, Auth)")]
        DB_Tel[("TelephonyDbContext<br/>(Gateways, SIM Health)")]
        DB_Ast[("wb_ast External DB<br/>(Read-Only PJSIP/Realtime)")]
    end

    %% Data Connections
    DI_Services -->|"Read / Write"| DB_App
    DI_Services -->|"Read / Write"| DB_Tel
    DI_Services -->|"High-Speed Lookup"| DB_Ast
    AstNode -->|"Realtime Config Mapping"| DB_Ast

    %% Interfaces
    U_Web -->|"HTTPS Cookie Auth"| MVC
    U_API -->|"X-API-KEY / Bearer Token"| API_Ctrl
    DI_Services -->|"Heartbeat Polling"| AstNode

    %% Styling
    classDef client fill:#1e1e2d,stroke:#a855f7,stroke-width:2px,color:#fff;
    classDef core fill:#2d1b4e,stroke:#c084fc,stroke-width:2px,color:#fff;
    classDef tele fill:#162e3d,stroke:#06b6d4,stroke-width:2px,color:#fff;
    classDef db fill:#3b1822,stroke:#f43f5e,stroke-width:2px,color:#fff;

    class U_Web,U_API client;
    class MVC,API_Ctrl,DI_Services core;
    class Kam,AstNode,FlowEng tele;
    class DB_App,DB_Tel,DB_Ast db;
```

### Ultra-Premium Styling Layout: High-Fidelity Signal Topology

To maximize horizontal rendering width and deliver a highly professional visual presentation, this alternative chart employs thick structured routing paths (`==>`), custom node geometries, and deep corporate palette definitions:

```mermaid
graph LR
    %% Edge Access Layer
    subgraph Edge["Ingress Signal Boundaries"]
        Trunk["External SIP Trunks"]
        Sims["Dinstar GSM Gateways"]
        RestAPI["MCP REST Handlers"]
    end

    %% Distributed Processing Engine
    subgraph Cluster["Distributed Execution Core"]
        Proxy["Kamailio Edge Router"]
        VoiceCluster["Asterisk Realtime PBX Array"]
        FlowLogic["AppFlow Visual Interpreter"]
    end

    %% Orchestration Hub
    subgraph AdminHub["ASP.NET Core Central Hub"]
        WebDash["Enterprise Management Portal"]
        EventBus["Distributed Event Broker"]
    end

    %% Data Storage Tier
    subgraph StorageTier["High-Performance Persistence"]
        DbRealtime[("wb_ast Fast Proxy Store<br/>(Volatile PJSIP Lookups)")]
        DbCore[("Application System Databases<br/>(Multi-Tenant Ledger Contexts)")]
    end

    %% High-Width Structured Connections
    Trunk ==>|"Secure SIP INVITE"| Proxy
    Sims ==>|"Encrypted SIP Channels"| Proxy
    Proxy ==>|"Dynamic Route Resolution"| VoiceCluster
    VoiceCluster <==>|"Bi-Directional ARI Loop"| FlowLogic
    
    RestAPI ==>|"X-API-KEY Authorization"| AdminHub
    WebDash ==>|"Internal Controller Directives"| EventBus
    EventBus ==>|"State Synchronization Directives"| Cluster
    
    VoiceCluster -.->|"Direct Entity Lookups"| DbRealtime
    EventBus ==>|"Transactional Migrations"| DbCore

    %% Premium Professional CSS Tokens
    classDef edgeToken fill:#0f172a,stroke:#38bdf8,stroke-width:3px,color:#ffffff,rx:8px,ry:8px;
    classDef clusterToken fill:#1e293b,stroke:#a855f7,stroke-width:3px,color:#ffffff,rx:8px,ry:8px;
    classDef adminToken fill:#312e81,stroke:#ec4899,stroke-width:3px,color:#ffffff,rx:8px,ry:8px;
    classDef storeToken fill:#065f46,stroke:#10b981,stroke-width:3px,color:#ffffff,rx:8px,ry:8px;

    class Trunk,Sims,RestAPI edgeToken;
    class Proxy,VoiceCluster,FlowLogic clusterToken;
    class WebDash,EventBus adminToken;
    class DbRealtime,DbCore storeToken;
```

---

## Architectural Component Breakdown

### 1. Unified Interface Presentation
The web interface layers are structured via customized Razor views built directly on Bootstrap utilities. To separate core administration from commercial SaaS acquisition, the framework maintains dual master layout matrices:
- **Dashboard Application Engine** (`_Layout.cshtml`): Implements dynamic sidebars, session status monitors, and secure administrative controls.
- **Marketing Presentation Hub** (`_MarketingLayout.cshtml`): Delivers high-speed public landing templates optimized for low initial TTFB.

### 2. Multi-Context Database Decoupling
To enforce absolute isolation between volatile runtime routing loops and durable multi-tenant user ledgers, the repository separates domain structures across dedicated Entity Framework Core contexts:

| DbContext Class | Primary Focus Area | Network Access Strategy | Target Database Engine |
| :--- | :--- | :--- | :--- |
| `ApplicationDbContext` | Tenant orgs, user authentication identities, administrative global tokens, and interface customization options. | **Read / Write** | Internal SQL Server (`AppDb`) |
| `TelephonyDbContext` | Channel CDR logs, registered SIP trunks, active SIM card lifecycles, and gateway status arrays. | **Read / Write** | Telephony Infrastructure SQL Server |
| `AstDbContext` | Mapped directly to the live operational tables supporting Asterisk server clusters (`PsEndpoint`, `Server`, `Cdr`, `Cel`, `QueueLog`). | **Read-Only Proxy** | Dedicated Realtime Engine (`wb_ast`) |

---

## Global Access Guidelines
When updating logic or writing custom extensions targeting these boundaries, engineers must observe the **Strict Zero-Local Policy** and ensure read-only safety checks prevent downstream locking of active SIP database pools.