# neutron-robotics/neutron-web architecture

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

- Interactive diagram: https://gitdiagram.com/neutron-robotics/neutron-web
- Repository: https://github.com/neutron-robotics/neutron-web

## Overview

##### Project type and purpose
- From the README and file tree, this is a React + TypeScript front-end client (“Neutron Web”) for the Neutron robotics platform. It is not a full end-to-end stack (no server code here), but it interacts with multiple backend microservices (auth, graph, robot, ROS2, organization, analytics) and provides real-time control and monitoring of robots.

##### File structure
- Top-level: Dockerfile, docker-compose.yml, Vite config, Cypress & Jest tests, public/ (static assets, documentation, legal markdown).
- src/:
- api/: HTTP clients for various backend endpoints (admin, auth, graph, robot, ros2, …) and shared models.
- components/: modular UI elements, grouped by domain (Admin, Connection, Neutron graph editor, Organization, Robot, Settings, controls).
- contexts/: React Context providers (Auth, Alert, Connection, Theme, Graph).
- utils/: general-purpose helpers (async hooks, Elasticsearch, time, thumbnail generation).
- views/: page-level components (Login, Home, Connection, Neutron graph, Robot view, Settings, etc.).
- index.tsx + App.tsx: application entry point & top-level router.

##### README for additional insights
- It highlights “real-time control” and “analytics” over robotics solutions.
- Users authenticate, then connect to a robot and build “graphs” of operations.
- It points to external docs (cgu/privacy, component templates) under public/assets.

a. Main components:
- User’s Browser / Mobile Device
- Static Asset Host (CDN or static server serving Vite‐built JS/CSS/HTML)
- React Application
– UI Components
– Context Providers (Auth, Alert, Connection, Graph)
– Neutron Graph Editor (canvas, nodes, side panels)
- API Layer (HTTP clients in src/api)
– Auth Service
– Graph Service (save/load graphs)
– Robot Service (list robots, parts, status)
– ROS2 Service (topics, publishers, subscribers, actions)
– Analytics Service
– Organization & Admin Services
- Real-Time/Streaming Service (WebSocket or Server-Sent Events for robot telemetry & control)
- External Systems
– Robot hardware & ROS2 back-end
– ElasticSearch / Kibana for logs & analytics
– CI/CD (GitHub Actions, Docker registry)

b. Relationships and interactions:
- Browser loads React app from the Static Asset Host.
- React App on startup uses AuthContext to call Auth Service → receives JWT.
- Subsequent Graph/Robot/API calls use JWT in HTTP headers.
- Upon “Connect to Robot,” App opens WebSocket to Real-Time Service, routes data through ConnectionContext.
- Neutron Graph Editor reads/writes flows via Graph Service and renders nodes.
- UI triggers actions (publish/subscribe) through ROS2 Service REST endpoints or via WebSocket.
- Analytics events/warnings/errors are sent to Analytics Service or ElasticSearch.

c. Architectural patterns & principles:
- Componentized UI (atomic to composite) in React.
- Context API for cross-cutting concerns (auth, alerts, theme, real-time connection).
- Clear separation: Presentation (views + components) vs. Data (api clients, contexts) vs. Utilities.
- Single-Page Application with client-side routing (RouteManager).
- Dependency Injection-like pattern in Neutron Graph Editor via ComponentFactory.

d. Key technologies:
- React + TypeScript + Vite
- React Context + Hooks
- Axios or Fetch (in src/api)
- WebSocket (for real-time robot control)
- Cypress (component + e2e testing) and Jest
- Docker + docker-compose for local dev

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Front-end boundary
    Browser["User's Browser / Mobile Device"]:::frontend
    StaticHost["Static Asset Host\n(CDN / Static Server)"]:::frontend

    Browser -->|loads| StaticHost
    StaticHost -->|serves| ReactApp

    subgraph "React Application" 
        direction TB
        index["index.tsx"]:::frontend
        app["App.tsx\n(Router)"]:::frontend

        subgraph "Context Layer"
            direction TB
            AuthC["AuthContext"]:::frontend
            AlertC["AlertContext"]:::frontend
            ConnC["ConnectionContext"]:::frontend
            GraphC["NeutronGraphContext"]:::frontend
            LoggerC["LoggerProvider"]:::frontend
            ThemeC["MuiTheme"]:::frontend
        end

        subgraph "View Layer"
            direction TB
            LoginV["LoginView"]:::frontend
            HomeV["HomeView"]:::frontend
            ConnV["ConnectionView"]:::frontend
            NeutronV["NeutronView"]:::frontend
            RobotV["RobotView"]:::frontend
            OrgV["OrganizationView"]:::frontend
            AdminV["AdminView"]:::frontend
            SettingsV["SettingsView"]:::frontend
            RouteMgr["RouteManager"]:::frontend
            NotFound["NotFound"]:::frontend
        end

        subgraph "Component Library"
            direction TB
            AdminComp["src/components/Admin"]:::frontend
            ConnComp["src/components/Connection"]:::frontend
            NeutronComp["src/components/Neutron"]:::frontend
            OrgComp["src/components/Organization"]:::frontend
            RobotComp["src/components/Robot"]:::frontend
            SettingsComp["src/components/Settings"]:::frontend
            ControlsComp["src/components/controls"]:::frontend
        end

        subgraph "API Client Layer"
            direction TB
            apiBase["api.ts\n(base client)"]:::frontend
            authApi["auth.ts\n(/api/auth)"]:::frontend
            graphApi["graph.ts\n(/api/graphs)"]:::frontend
            robotApi["robot.ts\n(/api/robots)"]:::frontend
            ros2Api["ros2.ts\n(/api/ros2)"]:::frontend
            orgApi["organization.ts"]:::frontend
            adminApi["admin.ts"]:::frontend
            connApi["connection.ts"]:::frontend
            fileApi["file.ts"]:::frontend
            models["src/api/models"]:::frontend
        end

        subgraph "Utilities & Helpers"
            direction TB
            elasticsearch["elasticsearch.ts"]:::frontend
            thumbnail["makeGraphThumbnail.ts"]:::frontend
            ros2Util["ros2.ts\n(utils)"]:::frontend
            asyncHook["useAsync.ts"]:::frontend
            timeUtil["time.ts"]:::frontend
        end

        index --> app
        app --> AuthC
        app --> AlertC
        app --> ConnC
        app --> GraphC
        app --> ThemeC
        app --> RouteMgr

        AuthC --> authApi
        ConnC --> connApi
        GraphC --> graphApi
        GraphC --> apiBase
        LoggerC --> elasticsearch

        app --> LoginV
        app --> HomeV
        app --> ConnV
        app --> NeutronV
        app --> RobotV
        app --> OrgV
        app --> AdminV
        app --> SettingsV

        NeutronV --> NeutronComp
        ConnV --> ConnComp
        OrgV --> OrgComp
        RobotV --> RobotComp
        AdminV --> AdminComp
        SettingsV --> SettingsComp

        apiBase --> models
    end

    %% External Services
    subgraph "External Services"
        direction TB
        AuthService["Auth Service\n/api/auth"]:::external
        GraphService["Graph Service\n/api/graphs"]:::external
        RobotService["Robot Service\n/api/robots"]:::external
        ROS2Service["ROS2 Service\n/api/ros2"]:::external
        OrgService["Organization Service"]:::external
        AdminService["Admin Service"]:::external
        FileService["File Service"]:::external
        RealTimeService["Real-Time Service\n(WebSocket)"]:::external
    end

    %% Data Store
    Elastic["Elasticsearch / Kibana"]:::datastore

    %% CI/CD Infra
    subgraph "CI/CD & Dev Infrastructure"
        direction TB
        GHBuild[".github/workflows/build.yml"]:::infra
        GHPublish[".github/workflows/publish.yml"]:::infra
        DockerfileNode["Dockerfile"]:::infra
        DockerCompose["docker-compose.yml"]:::infra
        Tests["jest.config.js\n__tests__/\ncypress/"]:::infra
    end

    %% Connections to External
    authApi -->|HTTP| AuthService
    graphApi -->|HTTP| GraphService
    robotApi -->|HTTP| RobotService
    ros2Api -->|HTTP| ROS2Service
    orgApi -->|HTTP| OrgService
    adminApi -->|HTTP| AdminService
    fileApi -->|HTTP| FileService

    ConnC -.->|WebSocket| RealTimeService
    RealTimeService -.->|streams telemetry| ConnC

    LoggerC -->|logs| Elastic

    GHBuild --> DockerfileNode
    GHBuild --> DockerCompose
    GHPublish --> DockerfileNode

    %% Click events
    click index "https://github.com/neutron-robotics/neutron-web/blob/main/src/index.tsx"
    click app "https://github.com/neutron-robotics/neutron-web/blob/main/src/App.tsx"
    click AuthC "https://github.com/neutron-robotics/neutron-web/blob/main/src/contexts/AuthContext.tsx"
    click AlertC "https://github.com/neutron-robotics/neutron-web/blob/main/src/contexts/AlertContext.tsx"
    click ConnC "https://github.com/neutron-robotics/neutron-web/blob/main/src/contexts/ConnectionContext.tsx"
    click GraphC "https://github.com/neutron-robotics/neutron-web/blob/main/src/contexts/NeutronGraphContext.tsx"
    click LoggerC "https://github.com/neutron-robotics/neutron-web/blob/main/src/contexts/LoggerProvider.tsx"
    click ThemeC "https://github.com/neutron-robotics/neutron-web/blob/main/src/contexts/MuiTheme.tsx"

    click apiBase "https://github.com/neutron-robotics/neutron-web/blob/main/src/api/api.ts"
    click authApi "https://github.com/neutron-robotics/neutron-web/blob/main/src/api/auth.ts"
    click graphApi "https://github.com/neutron-robotics/neutron-web/blob/main/src/api/graph.ts"
    click robotApi "https://github.com/neutron-robotics/neutron-web/blob/main/src/api/robot.ts"
    click ros2Api "https://github.com/neutron-robotics/neutron-web/blob/main/src/api/ros2.ts"
    click orgApi "https://github.com/neutron-robotics/neutron-web/blob/main/src/api/organization.ts"
    click adminApi "https://github.com/neutron-robotics/neutron-web/blob/main/src/api/admin.ts"
    click connApi "https://github.com/neutron-robotics/neutron-web/blob/main/src/api/connection.ts"
    click fileApi "https://github.com/neutron-robotics/neutron-web/blob/main/src/api/file.ts"
    click models "https://github.com/neutron-robotics/neutron-web/tree/main/src/api/models"

    click AdminComp "https://github.com/neutron-robotics/neutron-web/tree/main/src/components/Admin"
    click ConnComp "https://github.com/neutron-robotics/neutron-web/tree/main/src/components/Connection"
    click NeutronComp "https://github.com/neutron-robotics/neutron-web/tree/main/src/components/Neutron"
    click OrgComp "https://github.com/neutron-robotics/neutron-web/tree/main/src/components/Organization"
    click RobotComp "https://github.com/neutron-robotics/neutron-web/tree/main/src/components/Robot"
    click SettingsComp "https://github.com/neutron-robotics/neutron-web/tree/main/src/components/Settings"
    click ControlsComp "https://github.com/neutron-robotics/neutron-web/tree/main/src/components/controls"

    click LoginV "https://github.com/neutron-robotics/neutron-web/blob/main/src/views/LoginView.tsx"
    click HomeV "https://github.com/neutron-robotics/neutron-web/blob/main/src/views/HomeView.tsx"
    click ConnV "https://github.com/neutron-robotics/neutron-web/blob/main/src/views/ConnectionView.tsx"
    click NeutronV "https://github.com/neutron-robotics/neutron-web/blob/main/src/views/NeutronView.tsx"
    click RobotV "https://github.com/neutron-robotics/neutron-web/blob/main/src/views/RobotView.tsx"
    click OrgV "https://github.com/neutron-robotics/neutron-web/blob/main/src/views/OrganizationView.tsx"
    click AdminV "https://github.com/neutron-robotics/neutron-web/blob/main/src/views/AdminView.tsx"
    click SettingsV "https://github.com/neutron-robotics/neutron-web/blob/main/src/views/SettingsView.tsx"
    click RouteMgr "https://github.com/neutron-robotics/neutron-web/blob/main/src/views/RouteManager.tsx"
    click NotFound "https://github.com/neutron-robotics/neutron-web/blob/main/src/views/NotFound.tsx"

    click elasticsearch "https://github.com/neutron-robotics/neutron-web/blob/main/src/utils/elasticsearch.ts"
    click thumbnail "https://github.com/neutron-robotics/neutron-web/blob/main/src/utils/makeGraphThumbnail.ts"
    click ros2Util "https://github.com/neutron-robotics/neutron-web/blob/main/src/utils/ros2.ts"
    click asyncHook "https://github.com/neutron-robotics/neutron-web/blob/main/src/utils/useAsync.ts"
    click timeUtil "https://github.com/neutron-robotics/neutron-web/blob/main/src/utils/time.ts"

    click GHBuild "https://github.com/neutron-robotics/neutron-web/blob/main/.github/workflows/build.yml"
    click GHPublish "https://github.com/neutron-robotics/neutron-web/blob/main/.github/workflows/publish.yml"
    click DockerfileNode "https://github.com/neutron-robotics/neutron-web/tree/main/Dockerfile"
    click DockerCompose "https://github.com/neutron-robotics/neutron-web/blob/main/docker-compose.yml"
    click Tests "https://github.com/neutron-robotics/neutron-web/blob/main/jest.config.js"
    
    classDef frontend fill:#D0E8FF,stroke:#0366D6
    classDef external fill:#DFFFE0,stroke:#2F8F00
    classDef infra fill:#F0F0F0,stroke:#666666
    classDef datastore fill:#FFF4E5,stroke:#D27B00
```
