# prateek780/q-sim architecture

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

- Interactive diagram: https://gitdiagram.com/prateek780/q-sim
- Repository: https://github.com/prateek780/q-sim

## Overview

##### Project Type and Purpose
- This is a hybrid classical-quantum network simulator with both CLI and web-based GUI interfaces.
- It provides:
- A core simulation engine for classical and quantum networks
- An API server exposing simulation controls and AI-driven agents
- A React/TypeScript frontend for visualization and interaction
- A collection of AI “agents” for log summarization, topology generation/validation, routing advice, etc.
- Data models for conversations, embeddings, simulation results, and topologies

##### High-Level Component Breakdown
A. Core Simulation Layer (Python)
- core/ — the simulation engine coordinating events, nodes, worlds
- classical_network/ & quantum_network/ — implementations of nodes, packets, channels
- json_parser.py & main.py — CLI entry points for batch or interactive use
B. AI Agent Layer (Python)
- ai_agent/ — LLM-based agents (log summarizer, topology agent, router, validator)
- orchestration/ — agent_manager and coordinator that drive multi-agent workflows
- data/embedding & data/models — storage and retrieval of embeddings, conversation logs, and simulation data
C. Backend/API Server (Python)
- server/app.py & start.py — starts a REST/WebSocket server (Flask/FastAPI style)
- server/api/ — route handlers for agents, simulations, conversations, topology requests
- server/socket_server/ — real-time updates via websockets
D. Frontend/UI (TypeScript + React)
- ui/src/ — React components for network canvases, labs, metrics, AI chat panels, node detail panels
- ui/services/ — API and socket clients, import/export, local storage
- Vite config, ESLint, package.json — build/test environment
E. Configuration & Utilities
- config/ — YAML/JSON configs for LLM, data paths, simulation parameters
- utils/ — general helpers (debugging, visualization, encryption)
- log_schema.json & validation_report.json — input/output schema definitions

##### Relationships & Interaction Flows
- Frontend ↔ Backend
- REST calls to `/api/simulation`, `/api/agent`, `/api/topology`, `/api/conversation`
- WebSocket channel for streaming live simulation and agent messages
- Backend ↔ Core Simulation
- API handlers invoke core.main or simulation manager, passing JSON topologies & params
- core returns simulation events/logs to server
- Backend ↔ AI Agent Layer
- The coordinator instantiates agents (e.g., log summarizer) → they call LLM APIs using prompts in ai_agent/src
- Results are persisted to data/models then pushed back to client via API/socket
- Data Persistence
- In-memory or Redis (data/models/connection/redis.py) for conversation & simulation state
- File-based logs and JSON schemas for offline analysis

##### Architectural Patterns & Design Principles
- Layered Architecture: UI → API → Core/Agent → Data
- Modular Agents: each AI capability is a plug-in agent class following base_agent interface
- Separation of Concerns: distinct directories for simulation, AI, server, UI, config, utils
- Event-Driven Simulation: core/event.py and orchestration/coordinator coordinate asynchronous tasks
- Extensibility: new network types, new agents, or new UI labs can be added by dropping in modules

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        UI["React/TypeScript UI"]:::ui
        Services["API & Socket Clients"]:::ui
        Components["UI Components"]:::ui
    end

    %% Backend/API Layer
    subgraph "Backend/API Layer"
        API["REST API Server"]:::api
        WS["WebSocket Server"]:::api
    end

    %% Core Simulation Layer
    subgraph "Core Simulation Layer"
        CoreEngine["Core Simulation Engine"]:::core
        Classical["Classical Network Module"]:::core
        Quantum["Quantum Network Module"]:::core
        CLI_JSON["JSON Parser CLI"]:::core
        CLI_Main["Main CLI"]:::core
    end

    %% AI Agent Layer
    subgraph "AI Agent Layer"
        Orchestrator["Agent Orchestrator"]:::agents
        BaseAgents["Agent Base Classes"]:::agents
        LogAgent["Log Summarization Agent"]:::agents
        RouterAgent["Router Agent"]:::agents
        TopologyAgent["Topology Agent"]:::agents
        ValidationAgent["Validation Agent"]:::agents
    end

    %% Data Layer
    subgraph "Data Layer"
        Redis["Redis Store"]:::data
        FileSys["File System Logs"]:::data
        EmbeddingDB["Embedding DB"]:::data
        ConvModels["Conversation Models"]:::data
        SimModels["Simulation Models"]:::data
        TopoModels["Topology Models"]:::data
    end

    %% External Services
    LLM["External LLM Service"]:::ext

    %% Connections
    UI -->|"HTTP POST JSON\n/api/simulation"| API
    UI -->|-- WS MSG --| WS
    Services --> API
    API -->|"Invokes\ncore.main()"| CoreEngine
    CoreEngine --> Classical
    CoreEngine --> Quantum
    API -->|"POST JSON\n/api/agent/*"| Orchestrator
    Orchestrator --> BaseAgents
    Orchestrator --> LogAgent
    Orchestrator --> RouterAgent
    Orchestrator --> TopologyAgent
    Orchestrator --> ValidationAgent
    LogAgent -->|"LLM Prompt"| LLM
    RouterAgent -->|"LLM Prompt"| LLM
    TopologyAgent -->|"LLM Prompt"| LLM
    ValidationAgent -->|"LLM Prompt"| LLM
    LogAgent --> Redis
    RouterAgent --> Redis
    TopologyAgent --> Redis
    ValidationAgent --> Redis
    LogAgent --> FileSys
    SimModels --> FileSys
    API --> SimModels
    API --> ConvModels
    API --> TopoModels
    EmbeddingDB --> ConvModels
    EmbeddingDB --> SimModels

    %% Click Events
    click UI "https://github.com/prateek780/q-sim/tree/main/ui/src/"
    click Services "https://github.com/prateek780/q-sim/blob/main/ui/src/services/api.ts"
    click Services "https://github.com/prateek780/q-sim/blob/main/ui/src/services/socket.ts"
    click Components "https://github.com/prateek780/q-sim/tree/main/ui/src/components/"
    click API "https://github.com/prateek780/q-sim/blob/main/server/app.py"
    click WS "https://github.com/prateek780/q-sim/blob/main/server/socket_server/socket_server.py"
    click CoreEngine "https://github.com/prateek780/q-sim/tree/main/core/"
    click Classical "https://github.com/prateek780/q-sim/tree/main/classical_network/"
    click Quantum "https://github.com/prateek780/q-sim/tree/main/quantum_network/"
    click CLI_JSON "https://github.com/prateek780/q-sim/blob/main/json_parser.py"
    click CLI_Main "https://github.com/prateek780/q-sim/blob/main/main.py"
    click Orchestrator "https://github.com/prateek780/q-sim/blob/main/ai_agent/src/orchestration/agent_manager.py"
    click Orchestrator "https://github.com/prateek780/q-sim/blob/main/ai_agent/src/orchestration/coordinator.py"
    click BaseAgents "https://github.com/prateek780/q-sim/tree/main/ai_agent/src/agents/base/"
    click LogAgent "https://github.com/prateek780/q-sim/blob/main/ai_agent/src/agents/log_summarization/log_summarization_agent.py"
    click RouterAgent "https://github.com/prateek780/q-sim/blob/main/ai_agent/src/agents/router/router_agent.py"
    click TopologyAgent "https://github.com/prateek780/q-sim/blob/main/ai_agent/src/agents/topology_agent/topology_agent.py"
    click ValidationAgent "https://github.com/prateek780/q-sim/blob/main/ai_agent/src/agents/validation_agent/validation_agent.py"
    click EmbeddingDB "https://github.com/prateek780/q-sim/blob/main/data/embedding/embedding_util.py"
    click EmbeddingDB "https://github.com/prateek780/q-sim/blob/main/data/embedding/langchain_integration.py"
    click Redis "https://github.com/prateek780/q-sim/blob/main/data/models/connection/redis.py"
    click ConvModels "https://github.com/prateek780/q-sim/blob/main/data/models/conversation/conversation_model.py"
    click ConvModels "https://github.com/prateek780/q-sim/blob/main/data/models/conversation/conversation_ops.py"
    click SimModels "https://github.com/prateek780/q-sim/blob/main/data/models/simulation/simulation_model.py"
    click SimModels "https://github.com/prateek780/q-sim/blob/main/data/models/simulation/log_model.py"
    click TopoModels "https://github.com/prateek780/q-sim/blob/main/data/models/topology/world_model.py"
    click TopoModels "https://github.com/prateek780/q-sim/blob/main/data/models/topology/node_model.py"
    click TopoModels "https://github.com/prateek780/q-sim/blob/main/data/models/topology/zone_model.py"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#333,shape:hexagon;
    classDef api fill:#98FB98,stroke:#333,shape:rect;
    classDef core fill:#FFA500,stroke:#333,shape:cylinder;
    classDef agents fill:#DDA0DD,stroke:#333,shape:rect;
    classDef data fill:#D3D3D3,stroke:#333,shape:cylinder;
    classDef ext fill:#FFFF99,stroke:#333,shape:cloud;
```
