# asyncfuncai/rabbitholes architecture

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

- Interactive diagram: https://gitdiagram.com/asyncfuncai/rabbitholes
- Repository: https://github.com/asyncfuncai/rabbitholes

## Overview

##### Project type and purpose
- This is a full‑stack, open‑source React + Node.js application called “Open RabbitHoles – Knowledge Explorer.”

##### File structure
- Top‑level:
- Dockerfile, docker‑compose.yml, railway.toml – containerization and deployment
- frontend/ – React app (TypeScript, React Flow, Tailwind)
- backend/ – Express API (TypeScript)
- frontend/src/services/api.ts handles HTTP calls to backend
- backend/src/routes/rabbithole.ts defines “/api/rabbithole” endpoint
- backend/src/services/openaiService.ts orchestrates calls to Tavily and Google AI
- No database directory: state and cache are in‑memory or on the client

##### README for additional insights
- Tech stack details (React, Node.js, OpenAI, Tavily)

##### Elements
- Blue rectangles for frontend modules
- Green rectangles for backend modules
- Pink or red for external AI services

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client Layer
    subgraph "Client / Browser"
        Browser("User & Browser")
    end

    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        App["App.tsx"]:::frontend
        SearchView["SearchView.tsx"]:::frontend
        RabbitFlow["RabbitFlow.tsx"]:::frontend
        MainNode["MainNode.tsx"]:::frontend
        Modal["Modal.tsx"]:::frontend
        BounceCards["bounce-cards.tsx"]:::frontend
        APIService["api.ts"]:::frontend
    end

    %% Backend Core
    subgraph "Backend Core"
        direction TB
        Server["server.ts"]:::backend
        RabbitholeRoute["rabbithole.ts"]:::backend
        OpenAIService["openaiService.ts"]:::backend
        Cache["In-Memory Cache"]:::backend
    end

    %% External AI Services
    subgraph "AI Service Layer"
        direction TB
        Tavily["Tavily Search API"]:::external
        GoogleAI["Google AI / Gemini API"]:::external
    end

    %% Deployment Configurations
    subgraph "Containerization & Deployment"
        DockerfileCfg["Dockerfile"]:::config
        ComposeCfg["docker-compose.yml"]:::config
        RailwayCfg["railway.toml"]:::config
    end

    %% Data Flows
    Browser -->|"renders"| App
    App -->|"loads UI"| SearchView
    SearchView -->|"renders"| RabbitFlow
    RabbitFlow -->|"uses node UI"| MainNode
    RabbitFlow -->|"uses UI primitives"| Modal
    RabbitFlow -->|"uses UI primitives"| BounceCards
    SearchView -->|"calls API"| APIService
    APIService -->|"POST /api/rabbithole"| Server
    Server -->|"routes to"| RabbitholeRoute
    RabbitholeRoute -->|"orchestrates"| OpenAIService
    OpenAIService -->|"caches"| Cache
    OpenAIService -->|"queries"| Tavily
    OpenAIService -->|"queries"| GoogleAI
    OpenAIService -->|"returns graph"| RabbitholeRoute
    RabbitholeRoute -->|"responds"| APIService
    APIService -->|"delivers JSON"| RabbitFlow

    %% Click Events
    click App "https://github.com/asyncfuncai/rabbitholes/blob/main/frontend/src/App.tsx"
    click SearchView "https://github.com/asyncfuncai/rabbitholes/blob/main/frontend/src/components/SearchView.tsx"
    click RabbitFlow "https://github.com/asyncfuncai/rabbitholes/blob/main/frontend/src/components/RabbitFlow.tsx"
    click MainNode "https://github.com/asyncfuncai/rabbitholes/blob/main/frontend/src/components/nodes/MainNode.tsx"
    click Modal "https://github.com/asyncfuncai/rabbitholes/blob/main/frontend/src/components/ui/Modal.tsx"
    click BounceCards "https://github.com/asyncfuncai/rabbitholes/blob/main/frontend/src/components/ui/bounce-cards.tsx"
    click APIService "https://github.com/asyncfuncai/rabbitholes/blob/main/frontend/src/services/api.ts"
    click Server "https://github.com/asyncfuncai/rabbitholes/blob/main/backend/src/server.ts"
    click RabbitholeRoute "https://github.com/asyncfuncai/rabbitholes/blob/main/backend/src/routes/rabbithole.ts"
    click OpenAIService "https://github.com/asyncfuncai/rabbitholes/blob/main/backend/src/services/openaiService.ts"
    click DockerfileCfg "https://github.com/asyncfuncai/rabbitholes/tree/main/Dockerfile"
    click ComposeCfg "https://github.com/asyncfuncai/rabbitholes/blob/main/docker-compose.yml"
    click RailwayCfg "https://github.com/asyncfuncai/rabbitholes/blob/main/railway.toml"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#1E90FF,color:#000
    classDef backend fill:#D6F5D6,stroke:#28A745,color:#000
    classDef external fill:#F8D7DA,stroke:#DC3545,color:#000
    classDef config fill:#FFF3CD,stroke:#FFC107,color:#000
```
