# lod-io/centaur architecture

> Architecture diagram of the GitHub repository lod-io/centaur, 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/lod-io/centaur
- Repository: https://github.com/lod-io/centaur

## Overview

##### Project Type & Purpose
- Type: Full-stack interactive web application.
- Purpose: To simulate horse races where each horse’s progress is determined by the performance (speed and correctness) of AI models answering questions.
- Key Feature: Real-time updates via WebSockets allow users to see AI model performance in a visually engaging way.

##### Components from the File Structure
- Frontend (Client):
- The main code is located in the “client” directory.
- Standard React project structure with directories like public, src, and components that include UI pieces such as HeaderButtons, RaceTrack, HorseSelector, etc.
- Utility folders like hooks (e.g., usePopovers) and data files (questionBank) support dynamic interactions.
- The client handles user interactions, rendering the race, and calls to the backend.

- Backend (Server):
- The “server” directory uses Go, with subdirectories for constants, handlers, models, and services.
- Handlers (e.g., answer.go, websocket.go) define endpoints and WebSocket connections, managing incoming requests.
- Models and services encapsulate business logic and data structures.
- Configuration and dependency management via go.mod and go.sum are also present.

a. Main Components:
- Client (React application): Represents the user interface, interactive elements, and hooks/components like RaceTrack, HorseSelector, etc.
- Server (Go backend): Hosts API endpoints, WebSocket server, and internal processing logic including models, services, and constants.
- External Services: Highlight the use of the CLōD API (set via .env) for additional data or processing if necessary.

b. Relationships & Data Flow:
- The client sends requests (via REST and/or WebSockets) to the server.
- The server processes these requests (e.g., checking answers or updating race states) and pushes real-time updates back to the client.
- Data flow: User actions in the UI trigger API calls → Server validates/processes → Real-time updates pushed via WebSockets → UI updates to reflect current race progress.

c. Architectural Patterns & Principles:
- Clear separation of concerns between frontend and backend.
- MVC-like structure on the server (handlers for routing, models for data structure, services for business logic).
- Real-time communication handled with WebSockets.
- Use of client-side state management to drive dynamic UI updates.

d. Relevant Technologies:
- Frontend: React, TypeScript, Node.js (npm) for dependency management.
- Backend: Go programming language, using standard modules and WebSocket handling.
- API Key management with environment variables (.env) for CLōD API.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Block
    subgraph "Frontend"
        FE_main["Client App"]:::entry
        subgraph "UI Components"
            UI1["RaceTrack"]:::ui
            UI2["HeaderButtons"]:::ui
            UI3["HorseSelector"]:::ui
            UI4["CustomizePopover"]:::ui
            UI5["QAContainer"]:::ui
        end
        subgraph "Data & State Management"
            DS1["Question Bank"]:::data
            DS2["Hooks (usePopovers)"]:::data
        end
        subgraph "Client Entry Points"
            CP1["App Component"]:::entry
            CP2["Application Starter"]:::entry
        end
    end

    %% Backend Block
    subgraph "Backend"
        BE_main["Go Server"]:::entryBackend
        subgraph "API Handlers"
            BH1["WebSocket Handler"]:::handler
            BH2["Answer Handler"]:::handler
            BH3["Additional Handler"]:::handler
        end
        subgraph "Business Logic & Services"
            BL1["Answer Service"]:::service
            BL2["Models Logic"]:::service
        end
        subgraph "Data Models"
            DM1["Types Definition"]:::model
        end
        subgraph "Constants & Config"
            CC1["Constants"]:::constant
        end
        subgraph "Server Entry"
            SE1["Main Go File"]:::entryBackend
        end
    end

    %% External Services Block
    subgraph "External Services"
        ES1["CLōD API"]:::external
    end

    %% Connections within Frontend
    FE_main -->|"renders"| UI1
    FE_main -->|"renders"| UI2
    FE_main -->|"renders"| UI3
    FE_main -->|"renders"| UI4
    FE_main -->|"renders"| UI5
    DS1 -->|"supplies_data"| CP1
    DS2 -->|"manages_state"| CP1

    %% Connections from Frontend to Backend Handlers
    CP1 -->|"REST_call"| BH2
    CP1 -->|"WS_connect"| BH1
    CP2 -->|"initiate"| CP1

    %% Backend Internal Connections
    SE1 -->|"registers"| BH1
    SE1 -->|"registers"| BH2
    SE1 -->|"registers"| BH3
    BH1 -->|"push_updates"| UI1
    BH2 -->|"processes_request"| BL1
    BH3 -->|"delegates_logic"| BL2
    BL1 -->|"uses"| CC1
    BL2 -->|"uses"| CC1
    BL2 -->|"references"| DM1
    BL1 -->|"calls"| ES1

    %% Connections from Backend to Frontend
    BH1 -->|"realTime_updates"| FE_main

    %% Click Events for Frontend
    click FE_main "https://github.com/lod-io/centaur/tree/main/client/"
    click UI1 "https://github.com/lod-io/centaur/blob/main/client/src/components/RaceTrack.tsx"
    click UI2 "https://github.com/lod-io/centaur/blob/main/client/src/components/HeaderButtons.tsx"
    click UI3 "https://github.com/lod-io/centaur/blob/main/client/src/components/HorseSelector.tsx"
    click UI4 "https://github.com/lod-io/centaur/blob/main/client/src/components/CustomizePopover.tsx"
    click UI5 "https://github.com/lod-io/centaur/blob/main/client/src/components/QAContainer.tsx"
    click DS1 "https://github.com/lod-io/centaur/blob/main/client/src/data/questionBank.ts"
    click DS2 "https://github.com/lod-io/centaur/blob/main/client/src/hooks/usePopovers.ts"
    click CP1 "https://github.com/lod-io/centaur/blob/main/client/src/App.tsx"
    click CP2 "https://github.com/lod-io/centaur/blob/main/client/src/index.tsx"

    %% Click Events for Backend
    click BE_main "https://github.com/lod-io/centaur/tree/main/server/"
    click BH1 "https://github.com/lod-io/centaur/blob/main/server/handlers/websocket.go"
    click BH2 "https://github.com/lod-io/centaur/blob/main/server/handlers/answer.go"
    click BH3 "https://github.com/lod-io/centaur/blob/main/server/handlers/models.go"
    click BL1 "https://github.com/lod-io/centaur/blob/main/server/services/answer.go"
    click BL2 "https://github.com/lod-io/centaur/blob/main/server/services/models.go"
    click DM1 "https://github.com/lod-io/centaur/blob/main/server/models/types.go"
    click CC1 "https://github.com/lod-io/centaur/blob/main/server/constants/constants.go"
    click SE1 "https://github.com/lod-io/centaur/blob/main/server/main.go"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef data fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef entry fill:#ffcccb,stroke:#333,stroke-width:2px;
    classDef handler fill:#FFA500,stroke:#333,stroke-width:2px;
    classDef service fill:#DDA0DD,stroke:#333,stroke-width:2px;
    classDef model fill:#E6E6FA,stroke:#333,stroke-width:2px;
    classDef constant fill:#F0E68C,stroke:#333,stroke-width:2px;
    classDef entryBackend fill:#87CEEB,stroke:#333,stroke-width:2px;
    classDef external fill:#E0FFFF,stroke:#333,stroke-width:2px;
```
