# aurora-opensource/xviz architecture

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

- Interactive diagram: https://gitdiagram.com/aurora-opensource/xviz
- Repository: https://github.com/aurora-opensource/xviz

## Overview

##### Main Components and Architecture

The system should be represented as a modular architecture with these key components:

a) Core Protocol Layer:
- Three supported formats: JSON, Binary, and Protobuf
- Protocol message types (envelope, session, primitives, etc.)

b) Server-Side Components:
- XVIZ Server Module
- Provider System
- Data Conversion Layer
- WebSocket Communication

c) Client-Side Components:
- Parser Module
- Synchronizer
- Stream Buffer
- Data Access Layer

##### Component Relationships

a) Data Flow:
- Raw Data Sources → Converters → XVIZ Protocol
- XVIZ Protocol → Server → WebSocket → Client
- Client → Parser → Synchronized Data → Visualization

b) Module Dependencies:
- Builder → Schema (validation)
- Parser → Schema (validation)
- Server → IO (data handling)
- CLI → All Components (tooling)

##### Specific Implementation Details

Important architectural elements:

a) Builder Module:
- Metadata Builder
- Primitive Builder
- UI Builder
- Variable Builder

b) Parser Module:
- Stream Synchronizer
- Object Collection
- Style Parser
- Worker System

c) IO Module:
- Source/Sink System
- Providers
- Readers/Writers
- Format Handlers

##### Additional Layers

Supporting systems:

- Validation Layer (Schema)
- CLI Tools Interface
- ROS Integration
- Example Converters (KITTI, Nutonomy)

##### Implementation Notes

Architectural decisions:

- Modular design with clear separation of concerns
- Support for multiple data formats
- Real-time data handling capabilities
- Extensible converter system
- Flexible synchronization mechanisms

This architecture reflects XVIZ's design as a comprehensive system for handling autonomy data, from ingestion through conversion, transport, and visualization.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Legend
        A[Client Component]:::client
        B[Server Component]:::server
        C[Core Protocol]:::core
        D[Builder Component]:::builder
        E[IO Component]:::io
        F[ROS Component]:::ros
    end

    subgraph "Core Protocol Layer"
        Schema["Schema Definition"]:::core
        click Schema "https://github.com/aurora-opensource/xviz/tree/master/modules/schema/schema/"
        Formats["Protocol Formats"]:::core
        click Formats "https://github.com/aurora-opensource/xviz/tree/master/xviz/v2/"
        ProtocolDocs["Protocol Documentation"]:::core
        click ProtocolDocs "https://github.com/aurora-opensource/xviz/tree/master/docs/protocol-schema/"
    end

    subgraph "Server Components"
        XVIZServer["XVIZ Server"]:::server
        click XVIZServer "https://github.com/aurora-opensource/xviz/blob/master/modules/server/src/server/xviz-server.js"
        WebSocket["WebSocket Handler"]:::server
        click WebSocket "https://github.com/aurora-opensource/xviz/blob/master/modules/server/src/middlewares/xviz-websocket-sender.js"
        Provider["Provider System"]:::server
        click Provider "https://github.com/aurora-opensource/xviz/tree/master/modules/io/src/providers/"
        DataConversion["Data Conversion"]:::server
        click DataConversion "https://github.com/aurora-opensource/xviz/tree/master/modules/io/src/writers/"
    end

    subgraph "Client Components"
        Parser["Parser Module"]:::client
        click Parser "https://github.com/aurora-opensource/xviz/tree/master/modules/parser/src/parsers/"
        Synchronizer["Synchronizer"]:::client
        click Synchronizer "https://github.com/aurora-opensource/xviz/blob/master/modules/parser/src/synchronizers/stream-synchronizer.js"
        StreamBuffer["Stream Buffer"]:::client
        click StreamBuffer "https://github.com/aurora-opensource/xviz/blob/master/modules/parser/src/synchronizers/xviz-stream-buffer.js"
        StyleParser["Style Parser"]:::client
        click StyleParser "https://github.com/aurora-opensource/xviz/blob/master/modules/parser/src/styles/xviz-style-parser.js"
    end

    subgraph "Builder Components"
        MetadataBuilder["Metadata Builder"]:::builder
        click MetadataBuilder "https://github.com/aurora-opensource/xviz/blob/master/modules/builder/src/builders/xviz-metadata-builder.js"
        PrimitiveBuilder["Primitive Builder"]:::builder
        click PrimitiveBuilder "https://github.com/aurora-opensource/xviz/blob/master/modules/builder/src/builders/xviz-primitive-builder.js"
        UIBuilder["UI Builder"]:::builder
        click UIBuilder "https://github.com/aurora-opensource/xviz/blob/master/modules/builder/src/builders/xviz-ui-builder.js"
        VariableBuilder["Variable Builder"]:::builder
        click VariableBuilder "https://github.com/aurora-opensource/xviz/blob/master/modules/builder/src/builders/xviz-variable-builder.js"
    end

    subgraph "IO Components"
        SourceSink["Source/Sink System"]:::io
        click SourceSink "https://github.com/aurora-opensource/xviz/tree/master/modules/io/src/io/"
        FormatHandlers["Format Handlers"]:::io
        click FormatHandlers "https://github.com/aurora-opensource/xviz/tree/master/modules/io/src/writers/"
        IOProviders["Providers"]:::io
        click IOProviders "https://github.com/aurora-opensource/xviz/tree/master/modules/io/src/providers/"
        Readers["Readers"]:::io
        click Readers "https://github.com/aurora-opensource/xviz/tree/master/modules/io/src/readers/"
    end

    subgraph "ROS Integration"
        ROSModule["ROS Module"]:::ros
        click ROSModule "https://github.com/aurora-opensource/xviz/tree/master/modules/ros/"
        ROSConverters["ROS Converters"]:::ros
        click ROSConverters "https://github.com/aurora-opensource/xviz/tree/master/modules/ros/src/messages/"
    end

    %% Relationships
    Schema --> XVIZServer
    Schema --> Parser
    Formats --> XVIZServer
    Formats --> Parser

    XVIZServer --> WebSocket
    Provider --> XVIZServer
    DataConversion --> XVIZServer

    WebSocket --> Parser
    Parser --> Synchronizer
    Synchronizer --> StreamBuffer
    Parser --> StyleParser

    MetadataBuilder --> Schema
    PrimitiveBuilder --> Schema
    UIBuilder --> Schema
    VariableBuilder --> Schema

    SourceSink --> FormatHandlers
    FormatHandlers --> IOProviders
    IOProviders --> Readers

    ROSModule --> ROSConverters
    ROSConverters --> DataConversion

    classDef core fill:#2196F3,stroke:#1565C0,color:white
    classDef server fill:#4CAF50,stroke:#2E7D32,color:white
    classDef client fill:#FF9800,stroke:#EF6C00,color:white
    classDef builder fill:#9C27B0,stroke:#6A1B9A,color:white
    classDef io fill:#00BCD4,stroke:#00838F,color:white
    classDef ros fill:#795548,stroke:#4E342E,color:white
```
