# alex-vesel/xai-hackathon architecture

> Architecture diagram of the GitHub repository alex-vesel/xai-hackathon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alex-vesel/xai-hackathon
- Repository: https://github.com/alex-vesel/xai-hackathon

## Overview

##### Project type and purpose
- This is a full-stack, data-visualization web application (“A Hitchhiker’s Guide to X”) that lets users enter an X (formerly Twitter) username, fetch their tweets and mentions, embed those with xAI/OpenAI, then render an interactive force-graph in the browser.
- Frontend: React app (built with Create React App) that provides UI components (chat sidebar, tweet input, force-graph).
- Backend: Python FastAPI (uvicorn) serving REST endpoints, orchestrating calls to the X API, xAI embed API, and Grok interface.

##### File structure
- Top-level: package.json & requirements.txt → Node and Python package management.
- src/backend: FastAPI app modules
- main.py (entrypoint)
- server.py (API routes)
- orchestrator.py (business logic)
- grok_interface.py, xai_embed_api.py, x_api.py (external-service wrappers)
- graph.py (graph data model)
- client_demo.py, testing.py (demos/tests)
- src/frontend: React app
- public/ (static HTML, manifest)
- src/ (JS/CSS)
– components/ (UI widgets)
– endpoints/ (JS modules calling backend)
– forcegraph.js (visualization logic)
– useScript.js, data.json (utilities, sample data)

##### README for additional insights
- No persistent database—graph built on-the-fly in memory.
- Deploy: `npm start` for frontend; `uvicorn main:app` for backend.
- Relies on environment variables for X API, xAI API, OpenAI API credentials.

##### Elements
- Clear labels: React SPA, FastAPI server, Orchestrator, X API, xAI API, Grok API
- Browser → Frontend HTTP calls (e.g. /init, /addNodes)
- Frontend → Backend
- Backend → External services
- Backend → Frontend (JSON response)
- Rectangles for internal components (Frontend modules in blue, Backend modules in green)
- Clouds for external services (X API, xAI Embed, Grok/OpenAI)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Tier
    subgraph "Frontend Tier"
        Browser(["User Browser"]):::external
        ReactSPA["React SPA"]:::frontend
        IndexHTML["index.html"]:::frontend
        App["App.js"]:::frontend
        ChatSidebar["ChatSidebar"]:::frontend
        TweetInput["TweetInput"]:::frontend
        TweetEmbed["TweetEmbed"]:::frontend
        ForceGraph["forcegraph.js"]:::frontend
        InitUG["Init_User_Graph.js"]:::frontend
        AddNodes["AddNodes.js"]:::frontend
        TweetFetcher["TweetFetcher.js"]:::frontend
        UseScript["useScript.js"]:::frontend
        DataJSON["data.json"]:::frontend
    end

    %% Backend Tier
    subgraph "Backend Tier"
        Main["main.py"]:::backend
        Server["server.py"]:::backend
        Orchestrator["orchestrator.py"]:::backend
        GraphModel["graph.py"]:::backend
        XAPI["x_api.py"]:::backend
        XAIEmbed["xai_embed_api.py"]:::backend
        GrokIF["grok_interface.py"]:::backend
        ClientDemo["client_demo.py"]:::backend
        Testing["testing.py"]:::backend
    end

    %% External Services
    subgraph "External Services"
        XAPICloud["X API"]:::external
        XAICloud["xAI Embed API"]:::external
        GrokCloud["Grok/OpenAI API"]:::external
    end

    %% Configuration & Dependencies
    Config["Env Vars / Config"]:::config
    PackageRoot["package.json"]:::config
    PackageFE["src/frontend/package.json"]:::config
    Requirements["requirements.txt"]:::config

    %% Connections
    Browser --> IndexHTML
    IndexHTML --> App
    App --> ChatSidebar
    App --> TweetInput
    App --> TweetEmbed
    App --> ForceGraph
    TweetInput --> InitUG
    TweetInput --> AddNodes
    TweetInput --> TweetFetcher
    InitUG --> Main
    AddNodes --> Main
    TweetFetcher --> Main
    Main --> Server
    Server --> Orchestrator
    Orchestrator --> XAPI
    Orchestrator --> GraphModel
    Orchestrator --> XAIEmbed
    Orchestrator --> GrokIF
    XAPI --> XAPICloud
    XAIEmbed --> XAICloud
    GrokIF --> GrokCloud
    Orchestrator --> Server
    Server --> ReactSPA
    Config --> Main
    Config --> Orchestrator
    Config --> XAPI
    Config --> XAIEmbed
    Config --> GrokIF
    PackageRoot --> ReactSPA
    PackageFE --> ReactSPA
    Requirements --> Main

    %% Click Events
    click ReactSPA "https://github.com/alex-vesel/xai-hackathon/tree/main/src/frontend"
    click ChatSidebar "https://github.com/alex-vesel/xai-hackathon/blob/main/src/frontend/src/components/ChatSidebar.js"
    click TweetInput "https://github.com/alex-vesel/xai-hackathon/blob/main/src/frontend/src/components/TweetInput.js"
    click TweetEmbed "https://github.com/alex-vesel/xai-hackathon/blob/main/src/frontend/src/components/tweetembed.js"
    click ForceGraph "https://github.com/alex-vesel/xai-hackathon/blob/main/src/frontend/src/forcegraph.js"
    click InitUG "https://github.com/alex-vesel/xai-hackathon/blob/main/src/frontend/src/endpoints/Init_User_Graph.js"
    click AddNodes "https://github.com/alex-vesel/xai-hackathon/blob/main/src/frontend/src/endpoints/AddNodes.js"
    click TweetFetcher "https://github.com/alex-vesel/xai-hackathon/blob/main/src/frontend/src/endpoints/TweetFetcher.js"
    click UseScript "https://github.com/alex-vesel/xai-hackathon/blob/main/src/frontend/src/useScript.js"
    click DataJSON "https://github.com/alex-vesel/xai-hackathon/blob/main/src/frontend/src/data.json"
    click App "https://github.com/alex-vesel/xai-hackathon/blob/main/src/frontend/src/App.js"
    click IndexHTML "https://github.com/alex-vesel/xai-hackathon/blob/main/src/frontend/public/index.html"
    click Main "https://github.com/alex-vesel/xai-hackathon/blob/main/src/backend/main.py"
    click Server "https://github.com/alex-vesel/xai-hackathon/blob/main/src/backend/server.py"
    click Orchestrator "https://github.com/alex-vesel/xai-hackathon/blob/main/src/backend/orchestrator.py"
    click GraphModel "https://github.com/alex-vesel/xai-hackathon/blob/main/src/backend/graph.py"
    click XAPI "https://github.com/alex-vesel/xai-hackathon/blob/main/src/backend/x_api.py"
    click XAIEmbed "https://github.com/alex-vesel/xai-hackathon/blob/main/src/backend/xai_embed_api.py"
    click GrokIF "https://github.com/alex-vesel/xai-hackathon/blob/main/src/backend/grok_interface.py"
    click ClientDemo "https://github.com/alex-vesel/xai-hackathon/blob/main/src/backend/client_demo.py"
    click Testing "https://github.com/alex-vesel/xai-hackathon/blob/main/src/backend/testing.py"
    click PackageRoot "https://github.com/alex-vesel/xai-hackathon/blob/main/package.json"
    click PackageFE "https://github.com/alex-vesel/xai-hackathon/blob/main/src/frontend/package.json"
    click Requirements "https://github.com/alex-vesel/xai-hackathon/blob/main/requirements.txt"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef backend fill:#E6FFEA,stroke:#28A745,color:#22863A;
    classDef external fill:#F5F5F5,stroke:#6A737D,color:#586069;
    classDef config fill:#FBEFEF,stroke:#d73a49,color:#cb2431;
```
