# princetonuniversity/ng-scope architecture

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

- Interactive diagram: https://gitdiagram.com/princetonuniversity/ng-scope
- Repository: https://github.com/princetonuniversity/ng-scope

## Overview

##### Main Components
- Signal Reception & Synchronization Module – This is where RF front-end input is received, and the PSS/SSS signals are used to align timing.
- Subframe Segmentation – Once synchronized, the incoming IQ data is broken into 1ms subframes and stored in a dedicated subframe buffer.
- Parallel DCI Decoding Engine – A thread-pool based system where multiple DCI decoder instances process the buffered subframes concurrently.
- DCI Buffer and Status Tracker – After decoding, the DCI messages are temporarily stored in a buffer and then “ordered” by the Status Tracker (which uses a ring buffer per cell) to ensure chronological output.
- DCI Logger and Streaming Module – This component logs the ordered DCI messages and also optionally streams them to remote endpoints.
- GUI Visualization – A frontend that provides real-time visualizations of decoded IQ constellations, Channel CSI, and related debugging/analysis information.
- Real-Time Processing Library – Set aside as a shared library that operates on the ring-buffer data to compute metrics such as cell bandwidth usage and throughput among other stats.

##### Data Flow and Interactions
- Data flows from the RF input and enters the Reception module where the synchronization process occurs.
- Synchronized IQ data is segmented into subframes and placed into a buffer.
- From the buffer, individual subframes are handed off to the parallel DCI Decoder threads.
- The parallel decoders dump decoded messages into an intermediate DCI buffer.
- The Status Tracker retrieves messages from this buffer, reorders them in its dedicated ring buffers (one per cell), and passes the ordered stream to both the logging module and the real-time processing library.
- The DCI logger writes messages (or streams them) externally, while the GUI retrieves and visualizes the same data.
- Additionally, configuration files (cellcfg.txt, rsrp.txt), CMake configuration, and integration with external libraries (e.g., updated srsRan, and possibly SDR drivers such as SoapySDR) support the operation.

##### Architectural Patterns and Design Principles
- Modular Design: Each major function (synchronization, segmentation, decoding, ordering, logging/streaming, GUI) is encapsulated in its own component.
- Pipeline Architecture: The system follows a clear linear data flow with well-defined buffering and thread-pool sections to promote parallelism.
- Concurrency and Multithreading: The DCI decoding is implemented via a thread pool, with separate threads for scheduling, decoding, status tracking, buffering, and logging.
- Real-Time Constraints: The design must minimize latency via minimal buffering and efficient inter-module communication (e.g., using ring buffers).
- Extensibility: The real-time processing library is structured for future extensibility in decoders and metrics.

##### Specify Technologies and Frameworks
- CMake is used as the build system.
- The project leverages the srsRan library (updated across versions as per the README) for many of the lower-level physical layer processes.
- It likely uses multi-threading libraries and low-level optimizations (with potential SIMD/C extensions for signal processing).
- The GUI component is an important element – its implementation isn’t fully detailed in the tree, but it should likely be represented as a separate presentation layer.
- Additionally, there are various scripts (e.g., for formatting, deployment, and even for DCI streaming to remote locations).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Acquisition Layer
    subgraph "Data Acquisition"
        A["RF Input"]:::acquisition
        B["Signal Reception & Synchronization"]:::acquisition
        C["Subframe Segmentation"]:::acquisition
    end

    %% Parallel Processing Pipeline
    subgraph "Processing Pipeline"
        subgraph "Parallel DCI Decoding"
            D["Thread Pool"]:::processing
            E["Parallel DCI Decoder Instances"]:::processing
        end
        F["DCI Buffer"]:::processing
        G["Status Tracker (Ring Buffers)"]:::processing
    end

    %% Output Interfaces
    subgraph "Output Interfaces"
        H["DCI Logger & Streaming"]:::output
        I["GUI Visualization"]:::output
        J["Real-Time Metrics Processor"]:::output
    end

    %% Configuration Management
    subgraph "Configuration"
        K["Cell Configuration"]:::config
        L["RSRP Configuration"]:::config
    end

    %% External Dependencies
    X["External Dependencies (srsRan, CMake, SDR drivers)"]:::external

    %% Data Flow Connections
    A -->|"rawRF"| B
    B -->|"syncIQ"| C
    C -->|"segFrames"| D
    D -->|"dispatch"| E
    E -->|"decodedDCIs"| F
    F -->|"bufferedDCIs"| G
    G -->|"orderedDCIs"| H
    G -->|"visualData"| I
    G -->|"metricsData"| J

    %% Configuration inputs
    K -->|"cellConfig"| B
    L -->|"rsrpConfig"| B

    %% External Dependencies influence
    X -->|"externalLibs"| E

    %% Click Events
    click B "https://github.com/princetonuniversity/ng-scope/tree/master/lib/src/phy/sync"
    click C "https://github.com/princetonuniversity/ng-scope/blob/master/ngscope/src/main.c"
    click D "https://github.com/princetonuniversity/ng-scope/blob/master/ngscope/hdr/ThreadPool.h"
    click E "https://github.com/princetonuniversity/ng-scope/blob/master/ngscope/src/dciLib/dci_decoder.c"
    click F "https://github.com/princetonuniversity/ng-scope/blob/master/ngscope/hdr/dciLib/dci_ring_buffer.h"
    click G "https://github.com/princetonuniversity/ng-scope/blob/master/ngscope/hdr/dciLib/status_tracker.h"
    click H "https://github.com/princetonuniversity/ng-scope/blob/master/ngscope/src/remote_server.c"
    click I "https://github.com/princetonuniversity/ng-scope/tree/master/cellinspector"
    click J "https://github.com/princetonuniversity/ng-scope/blob/master/lib/include/srsran/common/metrics_hub.h"
    click J "https://github.com/princetonuniversity/ng-scope/blob/master/lib/src/system/sys_metrics_processor.cc"
    click K "https://github.com/princetonuniversity/ng-scope/blob/master/ngscope/cellcfg.txt"
    click L "https://github.com/princetonuniversity/ng-scope/blob/master/ngscope/rsrp.txt"

    %% Styles
    classDef acquisition fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef processing fill:#A9DFBF,stroke:#145A32,stroke-width:2px;
    classDef output fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef config fill:#F5CBA7,stroke:#873600,stroke-width:2px;
    classDef external fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
```
