# stakwork/sphinx-nav-fiber architecture

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

- Interactive diagram: https://gitdiagram.com/stakwork/sphinx-nav-fiber
- Repository: https://github.com/stakwork/sphinx-nav-fiber

## Overview

Based on our analysis, this project is a front‐end, React/TypeScript single page application (SPA) that is built using modern tooling (e.g. Vite, Babel, Yarn) with a heavy emphasis on modular, component-based design. In addition to the UI, it contains well‑structured state management (via “stores” and “hooks”), a dedicated network layer (API integrations, authentication, and data fetching such as graph and source data), and a robust testing story (Cypress for end-to-end and component tests, Jest for unit testing). There is also clear support for Docker-based build and deployment as seen in the Dockerfile, docker-compose, and GitHub workflows.

##### Main Components and Their Roles
a. User Interface (UI) Layer:
- Central “App” and “Components” directory with its numerous subcomponents (such as AppBar, SideBar, Universe, and common UI elements).
b. State Management Layer:
- That the UI communicates with these stores and hooks for managing application state and interactive behaviors (such as navigation, control states, and socket messages).
c. Data / Network Layer:
- “network” directory as the API layer responsible for authentication, fetching graph & sources data, and actions such as posting bounties.
d. Utility / Helper Functions:
- Utilities (from the “utils” directory) that provide formatting, validation, and helper operations (e.g. formatting dates, budgets, and text) that support both the UI and network operations.
e. Build, Deployment, and Testing Infrastructure:
- Integration with Docker (Dockerfile and docker-compose) for containerized deployment.
- A separate section for testing – highlighting both end-to-end tests (Cypress scripts) and unit/component tests (Jest, as hinted by setup scripts and test directories).
- CI/CD processes (GitHub workflows) that enforce linting, testing, and Docker build processes.

##### Relationships and Data Flow
- State management with the network layer to indicate “data fetch/update” flows.
- From the build/deployment section, indicate that the compiled static assets (in the “build” folder) are what get deployed in production (possibly via Docker).

##### Architectural Patterns and Design Principles
- Component-based design and separation of concerns (UI components vs. state management vs. API calls).
- That the project applies modern practices such as modularity, reusability, and automated testing.
- Optionally, note that some “Providers” (like the Socket provider) show use of React Context for dependency injection and global state management.

##### Relevant Technologies & Tools
- That the UI is built with React and TypeScript.
- Mention build tools (Vite/Babel, Yarn) and testing tools (Cypress, Jest).
- Docker for containerization and GitHub Actions for CI/CD.
- Optionally, note the use of WebGL / Three.js (based on the “Universe/Graph/Cubes” directories), which add an extra layer in the UI for interactive graphics.

## Diagram (Mermaid)

```mermaid
graph TD
    %% UI Layer
    subgraph "UI Layer"
        UIComponents["Components (React/TypeScript)"]:::ui
    end

    %% State Management Layer
    subgraph "State Management"
        Stores["Stores (State Containers)"]:::state
        Hooks["Hooks (Custom Logic)"]:::state
    end

    %% Data / Network Layer
    subgraph "Data / Network Layer"
        Network["Network (API, Auth, Data Fetching)"]:::data
    end

    %% Utility / Helper Functions
    subgraph "Utility / Helper Functions"
        Utils["Utils (Helper Functions)"]:::utils
    end

    %% Build, Deployment, and Testing Infrastructure
    subgraph "Build, Deployment, and Testing"
        BuildOutput["Build Output (Static Assets)"]:::devops
        Dockerfile["Dockerfile"]:::devops
        DockerCompose["docker-compose.yml"]:::devops
        CICD["CI/CD (.github/workflows)"]:::devops
        CypressTests["Cypress Tests (E2E & Component)"]:::testing
        JestTests["Jest Tests (Unit/Component)"]:::testing
        JestSetup["Jest Setup (jest.setup.js)"]:::testing
    end

    %% Relationships between UI and State Management
    UIComponents -->|"userActions_triggerStateUpdates"| Stores
    UIComponents -->|"userActions_triggerStateUpdates"| Hooks

    %% Relationships between State Management and Data Layer
    Stores -->|"apiRequests_updates"| Network
    Hooks -->|"apiRequests_updates"| Network
    Network -->|"dataResponses_updateState"| Stores
    Network -->|"dataResponses_updateState"| Hooks

    %% Utilities supporting UI and Network Layers
    Utils -->|"supportsOperations"| UIComponents
    Utils -->|"supportsDataOps"| Network

    %% Build and Deployment Flow
    BuildOutput -->|"deployedVia"| Dockerfile
    BuildOutput -->|"deployedVia"| DockerCompose
    CICD -->|"triggersBuildAndTests"| BuildOutput
    CICD -->|"integratesWorkflow"| Dockerfile
    CICD -->|"integratesWorkflow"| DockerCompose

    %% Testing Flows
    CypressTests -->|"validateUIComponents"| UIComponents
    JestTests -->|"validateComponents"| UIComponents
    JestTests -->|"relatedTo"| JestSetup

    %% Click Events
    click UIComponents "https://github.com/stakwork/sphinx-nav-fiber/tree/master/src/components"
    click Stores "https://github.com/stakwork/sphinx-nav-fiber/tree/master/src/stores"
    click Hooks "https://github.com/stakwork/sphinx-nav-fiber/tree/master/src/hooks"
    click Network "https://github.com/stakwork/sphinx-nav-fiber/tree/master/src/network"
    click Utils "https://github.com/stakwork/sphinx-nav-fiber/tree/master/src/utils"
    click BuildOutput "https://github.com/stakwork/sphinx-nav-fiber/tree/master/build"
    click Dockerfile "https://github.com/stakwork/sphinx-nav-fiber/tree/master/Dockerfile"
    click DockerCompose "https://github.com/stakwork/sphinx-nav-fiber/blob/master/docker-compose.yml"
    click CICD "https://github.com/stakwork/sphinx-nav-fiber/tree/master/.github/workflows"
    click CypressTests "https://github.com/stakwork/sphinx-nav-fiber/tree/master/cypress"
    click JestTests "https://github.com/stakwork/sphinx-nav-fiber/blob/master/src/setupTests.ts"
    click JestSetup "https://github.com/stakwork/sphinx-nav-fiber/blob/master/jest.setup.js"

    %% Styles
    classDef ui fill:#f9e79f,stroke:#5D6D7E,stroke-width:2px;
    classDef state fill:#aed6f1,stroke:#5D6D7E,stroke-width:2px;
    classDef data fill:#abebc6,stroke:#5D6D7E,stroke-width:2px;
    classDef utils fill:#f5cba7,stroke:#5D6D7E,stroke-width:2px;
    classDef devops fill:#d7bde2,stroke:#5D6D7E,stroke-width:2px;
    classDef testing fill:#fadbd8,stroke:#5D6D7E,stroke-width:2px;
```
