# ntutangyun/ai-ran-sim architecture

> Architecture diagram of the GitHub repository ntutangyun/ai-ran-sim, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ntutangyun/ai-ran-sim
- Repository: https://github.com/ntutangyun/ai-ran-sim

## Overview

##### Project Type & Purpose
- Type: Full-stack simulation & visualization tool.
- Purpose: Simulate an O-RAN network (base stations, cells, UEs, Core, RIC, edge), integrate AI “xApps” for control/monitoring, and provide a web UI for interactive visualization and chat.

##### High-Level Components
A. Frontend (Next.js)
– User Browser (React UI)
– HTTP / WebSocket Client
B. Backend (Python)
1. WebSocket Server (main.py)
2. Simulation Engine (network_layer)
3. Knowledge Layer (knowledge_layer)
4. Intelligence Layer (intelligence_layer + xApps)
5. Configuration Module (settings)
6. Utility Modules (utils)
7. Evaluations & Logging (evaluations, assets)
C. External Services
– AI Model Providers (e.g., OpenAI APIs)
– Docker (for containerized backend)

##### Relationships & Data Flow
1. User Interaction → Frontend UI
- HTTP for page load
- WebSocket for real-time commands & simulation events
2. Frontend → Backend
- “Connect” via WebSocket
- Send user/chat commands, AI service requests
3. Backend WebSocket Server
- Receives UI events → routes to appropriate backend layers
4. Backend Simulation Engine (network_layer)
- Maintains O-RAN state (base stations, cells, UEs, core, RIC, xApps)
- Emits state updates & metrics
5. Backend Knowledge Layer
- Consumes raw simulation data
- Builds knowledge entries, routes queries
6. Backend Intelligence Layer
- Hosts AI pipeline & chat agents
- Invokes external AI services via client_ai_service_deployer
- Feeds AI output back into network decisions or chat responses
7. Backend → Frontend
- Pushes simulation state snapshots & AI chat events over WebSocket
- Frontend renders dashboards & chat components

##### Architectural Patterns & Principles
- Layered Architecture: clear separation of network simulation, knowledge aggregation, and AI logic.
- Event-Driven / Message-Driven: WebSocket events trigger simulation steps and AI workflows.
- Configuration-Driven: all network, slice, RIC, AI service parameters live in settings/*.
- Modular & Extensible: xApps can be dropped into network_layer/xApps, new knowledge sources in knowledge_layer/knowledge_sources.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend (Next.js)"
        Browser["User Browser"]:::external
        UI["Frontend UI"]:::frontend
        Components["Frontend Components"]:::frontend
        FUtils["Frontend Utilities"]:::frontend
    end

    Browser -->|"HTTP / WebSocket"| UI
    UI --> Components
    UI --> FUtils
    UI -->|"WS / JSON"| WS

    subgraph "Backend (Python)"
        WS["WebSocket Server"]:::backend
        subgraph "Network Layer (Simulation)"
            Sim["Simulation Engine"]:::network
            BS["Base Station"]:::network
            Cell["Cell"]:::network
            UE["UE"]:::network
            Core["Core Network"]:::network
            RIC["RIC"]:::network
            Edge["Edge Server"]:::network
            xApps["xApps"]:::network
        end
        subgraph "Knowledge Layer"
            KLayer["Knowledge Layer"]:::knowledge
            KS["Knowledge Sources"]:::knowledge
        end
        subgraph "Intelligence Layer"
            ILayer["Intelligence Layer"]:::intelligence
            AIPipe["AI Service Pipeline"]:::intelligence
            UserChat["User Chat Agents"]:::intelligence
            EngChat["Engineer Chat Agent"]:::intelligence
        end
        Config["Configuration Module"]:::config
        BUtils["Utility Modules"]:::utils
        Eval["Evaluations & Logging"]:::eval
    end

    WS -->|"routes events"| Sim
    WS --> KLayer
    WS --> ILayer

    Sim -->|"emits state_update"| KLayer
    KLayer -->|"queries"| ILayer
    ILayer -->|"invokes"| AIPipe
    AIPipe -->|"calls external"| ExternalAI
    ILayer --> UserChat
    ILayer --> EngChat
    Sim --> xApps

    WS --> Config
    WS --> BUtils
    WS --> Eval

    subgraph "External Services"
        ExternalAI["External AI Model Providers"]:::external
        Docker["Docker"]:::external
    end

    AIPipe --> ExternalAI
    WS --> Docker

    click UI "https://github.com/ntutangyun/ai-ran-sim/tree/main/frontend/src/app"
    click Components "https://github.com/ntutangyun/ai-ran-sim/tree/main/frontend/src/app/components"
    click FUtils "https://github.com/ntutangyun/ai-ran-sim/tree/main/frontend/src/app/utils"
    click WS "https://github.com/ntutangyun/ai-ran-sim/blob/main/backend/main.py"
    click Sim "https://github.com/ntutangyun/ai-ran-sim/blob/main/backend/network_layer/simulation_engine.py"
    click BS "https://github.com/ntutangyun/ai-ran-sim/blob/main/backend/network_layer/base_station.py"
    click Cell "https://github.com/ntutangyun/ai-ran-sim/blob/main/backend/network_layer/cell.py"
    click UE "https://github.com/ntutangyun/ai-ran-sim/blob/main/backend/network_layer/ue.py"
    click Core "https://github.com/ntutangyun/ai-ran-sim/blob/main/backend/network_layer/core_network.py"
    click RIC "https://github.com/ntutangyun/ai-ran-sim/blob/main/backend/network_layer/ric.py"
    click Edge "https://github.com/ntutangyun/ai-ran-sim/blob/main/backend/network_layer/edge_server.py"
    click xApps "https://github.com/ntutangyun/ai-ran-sim/tree/main/backend/network_layer/xApps"
    click KLayer "https://github.com/ntutangyun/ai-ran-sim/tree/main/backend/knowledge_layer"
    click KS "https://github.com/ntutangyun/ai-ran-sim/tree/main/backend/knowledge_layer/knowledge_sources"
    click ILayer "https://github.com/ntutangyun/ai-ran-sim/tree/main/backend/intelligence_layer"
    click AIPipe "https://github.com/ntutangyun/ai-ran-sim/tree/main/backend/intelligence_layer/ai_service_pipeline"
    click UserChat "https://github.com/ntutangyun/ai-ran-sim/tree/main/backend/intelligence_layer/user_chat"
    click EngChat "https://github.com/ntutangyun/ai-ran-sim/blob/main/backend/intelligence_layer/engineer_chat_agent.py"
    click Config "https://github.com/ntutangyun/ai-ran-sim/tree/main/backend/settings"
    click BUtils "https://github.com/ntutangyun/ai-ran-sim/tree/main/backend/utils"
    click Eval "https://github.com/ntutangyun/ai-ran-sim/tree/main/backend/evaluations"
    click Docker "https://github.com/ntutangyun/ai-ran-sim/blob/main/backend/.env.template"
    click BUtils "https://github.com/ntutangyun/ai-ran-sim/blob/main/backend/utils/docker_utils.py"
    click AIPipe "https://github.com/ntutangyun/ai-ran-sim/blob/main/backend/intelligence_layer/ai_service_pipeline/client_ai_service_deployer.py"

    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef backend fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef network fill:#98FB98,stroke:#333,stroke-width:1px
    classDef knowledge fill:#FFFF99,stroke:#333,stroke-width:1px
    classDef intelligence fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef config fill:#E6E6FA,stroke:#333,stroke-width:1px
    classDef utils fill:#FFC0CB,stroke:#333,stroke-width:1px
    classDef eval fill:#FFE4B5,stroke:#333,stroke-width:1px
```
