# thedevteam420/project-x architecture

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

- Interactive diagram: https://gitdiagram.com/thedevteam420/project-x
- Repository: https://github.com/thedevteam420/project-x

## Overview

##### Project Type & Purpose
- This is a client-side Single-Page Application (SPA) called “Project X: Quantum Neural Interface.”
- Purpose: enable users to converse with AI “digital personalities” via a WebGL/3D holographic interface, backed by Venice.ai and OpenAI embeddings.

##### File Structure
- Top-level folders:
- src/
– pages/ (route-level React pages)
– components/ (UI building blocks: ChatInterface, HologramScene, Banner3D, etc.)
– agents/ (TypeScript definitions for each AI character)
– store/ (Zustand hooks for state slices: agentStore, conspiracyStore, etc.)
– db/ (IndexedDB schema + wrapper)
– utils/ (API client modules for Venice.ai, OpenAI, Twilio, CSV loader, embeddings, neuralAI, rateLimiter)
– config/ (API endpoint config)
– types/ (domain models: agent, conspiracy, neural, etc.)
– hooks/ (custom React hooks)
– layouts/ (DashboardLayout)
- public/ (static assets: 3D models, CSV datasets, images)
- scripts/ (deploy.js)
- config files: Vite, Tailwind, Netlify, ESLint, tsconfig

##### README for Additional Insights
- Frontend: React 18 + TypeScript, React Three Fiber, Framer Motion, Tailwind CSS
- AI/ML: Venice.ai Chat API, OpenAI Embeddings, custom prompt engineering, semantic analysis
- Persistence: IndexedDB for conversation history
- Real-time: WebSocket support
- Future: Twilio voice, advanced hologram animations

a. Main Components
- User (Browser)
- UI Layer (React Components & Pages)
- 3D Rendering Engine (Three.js + React Three Fiber)
- State Management (Zustand stores)
- Persistence Layer (IndexedDB via src/db)
- API Layer (client wrappers in src/utils: venice.ts, openai.ts, twilio.ts, csvApi)
- External Services (Venice.ai, OpenAI Embeddings, Twilio, WebSocket endpoint)
- Static Asset Server (public folder served by Vite/Netlify)
b. Relationships & Data Flow
1. User action → React Component
2. Component dispatch → Zustand store update
3. Store effect → call API client (HTTP or WebSocket)
4. API client → External Service → response
5. Store receives data → updates state
6. React re-renders UI + 3D scene
7. Conversation history persisted → IndexedDB read/write
8. On load, CSV loader pulls datasets from public/csv
c. Architectural Patterns
- Feature-folder modularity
- Unidirectional data flow (React → Store → API → Store → React)
- Separation of concerns: UI, state, API, persistence
- Client-side rendering with progressive enhancement (3D, real-time, offline)
d. Key Technologies
- React/TypeScript, Zustand, IndexedDB, Three.js/R3F, Framer Motion, Tailwind
- Venice.ai Chat API, OpenAI Embeddings API, Twilio Voice, WebSocket

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    User["User (Browser)"]:::external

    %% UI Layer
    subgraph "UI Layer"
        subgraph "Pages" 
            AgentsPage["Agents Page"]:::frontend
            ConspiracyPage["Conspiracy Builder Page"]:::frontend
            DataVaultPage["Data Vault Page"]:::frontend
            NeuralPage["Neural Network Page"]:::frontend
            WelcomePage["Welcome Page"]:::frontend
        end
        subgraph "Components"
            ChatInterface["ChatInterface"]:::frontend
            HologramScene["HologramScene"]:::frontend
            Banner3D["Banner3D"]:::frontend
            Sidebar["Sidebar"]:::frontend
            DashboardLayout["DashboardLayout"]:::frontend
        end
    end

    %% State & Persistence
    subgraph "State & Persistence"
        AgentStore["useAgentStore"]:::state
        ConspiracyStore["useConspiracyStore"]:::state
        NeuralStore["useNeuralStore"]:::state
        IndexedDB["IndexedDB"]:::persistence
    end

    %% API Layer
    subgraph "API Layer"
        VeniceClient["venice.ts"]:::api
        OpenAIClient["openai.ts"]:::api
        Embeddings["embeddings.ts"]:::api
        TwilioClient["twilio.ts"]:::api
        CSVLoader["csvLoader.ts"]:::api
        CSVApi["csvApi.ts"]:::api
        RateLimiter["rateLimiter.ts"]:::api
        APIConfig["api.ts"]:::api
    end

    %% External Services
    subgraph "External Services"
        VeniceService["Venice.ai Chat API"]:::external
        OpenAIService["OpenAI Embeddings API"]:::external
        TwilioService["Twilio Voice"]:::external
        WebSocket["WebSocket Endpoint"]:::external
    end

    %% Static Assets
    subgraph "Static Assets"
        Models["public/models"]:::assets
        CSV["public/csv"]:::assets
    end

    %% Data Flows
    User -->|"interacts with"| AgentsPage
    User --> WelcomePage
    User --> ConspiracyPage
    User --> DataVaultPage
    User --> NeuralPage

    AgentsPage -->|renders| ChatInterface
    AgentsPage -->|renders| HologramScene
    ConspiracyPage -->|renders| Sidebar
    DataVaultPage -->|renders| Banner3D
    NeuralPage -->|renders| HologramScene

    ChatInterface -->|dispatch| AgentStore
    ChatInterface -->|dispatch| ConspiracyStore
    ChatInterface -->|dispatch| NeuralStore

    AgentStore -->|effect| VeniceClient
    ConspiracyStore -->|effect| CSVApi
    NeuralStore -->|effect| OpenAIClient

    VeniceClient -->|HTTP POST| VeniceService
    OpenAIClient -->|HTTP POST| OpenAIService
    Embeddings -->|HTTP POST| OpenAIService
    TwilioClient -->|WebSocket subscribe| TwilioService
    CSVLoader -->|fetch| CSV
    CSVApi -->|fetch| CSV
    RateLimiter -->|wraps| VeniceClient
    RateLimiter -->|wraps| OpenAIClient

    AgentStore -->|read/write| IndexedDB
    ConspiracyStore -->|read/write| IndexedDB
    NeuralStore -->|read/write| IndexedDB

    HologramScene -->|loads models| Models
    HologramScene -->|loads datasets| CSV

    %% Click Events
    click ChatInterface "https://github.com/thedevteam420/project-x/blob/main/src/components/ChatInterface.tsx"
    click HologramScene "https://github.com/thedevteam420/project-x/blob/main/src/components/HologramScene.tsx"
    click Banner3D "https://github.com/thedevteam420/project-x/blob/main/src/components/Banner3D.tsx"
    click Sidebar "https://github.com/thedevteam420/project-x/blob/main/src/components/Sidebar.tsx"
    click DashboardLayout "https://github.com/thedevteam420/project-x/blob/main/src/layouts/DashboardLayout.tsx"
    click AgentsPage "https://github.com/thedevteam420/project-x/blob/main/src/pages/Agents.tsx"
    click ConspiracyPage "https://github.com/thedevteam420/project-x/blob/main/src/pages/ConspiracyBuilder.tsx"
    click DataVaultPage "https://github.com/thedevteam420/project-x/blob/main/src/pages/DataVault.tsx"
    click NeuralPage "https://github.com/thedevteam420/project-x/blob/main/src/pages/NeuralNetwork.tsx"
    click WelcomePage "https://github.com/thedevteam420/project-x/blob/main/src/pages/Welcome.tsx"
    click AgentStore "https://github.com/thedevteam420/project-x/blob/main/src/store/useAgentStore.ts"
    click ConspiracyStore "https://github.com/thedevteam420/project-x/blob/main/src/store/useConspiracyStore.ts"
    click NeuralStore "https://github.com/thedevteam420/project-x/blob/main/src/store/useNeuralStore.ts"
    click IndexedDB "https://github.com/thedevteam420/project-x/blob/main/src/db/index.ts"
    click VeniceClient "https://github.com/thedevteam420/project-x/blob/main/src/utils/venice.ts"
    click OpenAIClient "https://github.com/thedevteam420/project-x/blob/main/src/utils/openai.ts"
    click Embeddings "https://github.com/thedevteam420/project-x/blob/main/src/utils/embeddings.ts"
    click TwilioClient "https://github.com/thedevteam420/project-x/blob/main/src/utils/twilio.ts"
    click CSVLoader "https://github.com/thedevteam420/project-x/blob/main/src/utils/csvLoader.ts"
    click CSVApi "https://github.com/thedevteam420/project-x/blob/main/src/api/csvApi.ts"
    click RateLimiter "https://github.com/thedevteam420/project-x/blob/main/src/utils/rateLimiter.ts"
    click APIConfig "https://github.com/thedevteam420/project-x/blob/main/src/config/api.ts"
    click Models "https://github.com/thedevteam420/project-x/tree/main/public/models/"
    click CSV "https://github.com/thedevteam420/project-x/tree/main/public/csv/"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,color:#000
    classDef state fill:#90EE90,stroke:#000,color:#000
    classDef persistence fill:#98FB98,stroke:#000,color:#000
    classDef api fill:#FFA500,stroke:#000,color:#000
    classDef external fill:#D8BFD8,stroke:#000,color:#000
    classDef assets fill:#D3D3D3,stroke:#000,color:#000
```
