# ths41461/spacedj architecture

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

- Interactive diagram: https://gitdiagram.com/ths41461/spacedj
- Repository: https://github.com/ths41461/spacedj

## Overview

##### Project type and purpose
- This is a single-page front-end application built in TypeScript, using Vite as the bundler and React/JSX (index.tsx) for rendering.
- Its primary purpose is to provide an AI-powered “studio” interface in the browser—rendering a dynamic scene/grid/points/spaceship, capturing user interactions, and calling the Gemini API for AI capabilities.

##### File structure
- Top-level config:
- vite.config.ts – Vite build/dev server configuration
- tsconfig.json – TypeScript compiler options
- package.json – dependencies, scripts (npm run dev)
- .gitignore
- Entry point:
- index.html – static HTML shell
- index.tsx – React/JSX root component
- index.css / styles.ts – global styles
- Core UI & logic modules (all .ts/.tsx):
- scene.ts, grid.ts, points.ts, spaceship.ts, selection.ts, labels.ts, icon_button.ts, toast.ts, tooltip.ts, space.ts, space_settings.ts, embeddings.ts, utils.ts
- No “backend” folder—external AI calls go directly to the Gemini API via HTTP (configured via GEMINI_API_KEY in .env.local).

##### README for additional insights
- Confirms purely front-end usage: “Run and deploy your AI Studio app,” “View your app in AI Studio.”
- Prerequisite: Node.js + setting GEMINI_API_KEY.
- No mention of any server-side microservice or database—calls to Gemini API are the only external integration.

##### Important details
- Live data flow: user → renderer → API → UI feedback
- Environment configuration (dotenv) as part of the build/deploy path

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User"]:::external
    subgraph "Client / Browser" 
        direction TB
        HTML["index.html"]:::frontend
        Entry["index.tsx"]:::frontend
        Styles["Global Styles\nindex.css, styles.ts"]:::frontend

        subgraph "Rendering Components"
            direction TB
            Scene["Scene Renderer\n(scene.ts)"]:::frontend
            Grid["Grid Component\n(grid.ts)"]:::frontend
            Points["Points Component\n(points.ts)"]:::frontend
            Spaceship["Spaceship Component\n(spaceship.ts)"]:::frontend
        end

        subgraph "State Management"
            direction TB
            SpaceState["Space State\n(space.ts)"]:::frontend
            Settings["Space Settings\n(space_settings.ts)"]:::frontend
            Selection["Selection State\n(selection.ts)"]:::frontend
        end

        subgraph "UI Widgets"
            direction TB
            IconBtn["Icon Button\n(icon_button.ts)"]:::frontend
            Tooltip["Tooltip\n(tooltip.ts)"]:::frontend
            Toast["Toast Notifications\n(toast.ts)"]:::frontend
            Labels["Labels\n(labels.ts)"]:::frontend
        end

        subgraph "AI Integration & Utilities"
            direction TB
            Embeddings["Embeddings & API Calls\n(embeddings.ts)"]:::frontend
            Utils["Utilities\n(utils.ts)"]:::frontend
        end

        Entry -->|renders| Scene
        Entry -->|renders| Grid
        Entry -->|renders| Points
        Entry -->|renders| Spaceship
        Entry -->|initializes| SpaceState
        Entry -->|loads| Settings
        Entry -->|loads| Selection
        Entry -->|uses| IconBtn
        Entry -->|uses| Tooltip
        Entry -->|uses| Toast
        Entry -->|uses| Labels
        Entry -->|calls| Embeddings
        Entry -->|calls| Utils
        Scene -->|updates view| SpaceState
        Grid --> SpaceState
        Points --> SpaceState
        Spaceship --> SpaceState
        Embeddings -->|fetch| API
        Utils -->|helper| Embeddings
    end

    subgraph "Build & Configuration"
        direction TB
        Vite["Vite Config / Dev Server\n(vite.config.ts)"]:::build
        TSConfig["TypeScript Config\n(tsconfig.json)"]:::config
        Package["package.json"]:::config
        GitIgnore[".gitignore"]:::config
    end

    subgraph "Deployment"
        direction TB
        Hosting["AI Studio Hosting\n(static /dist)"]:::external
        README["README & Metadata\n(README.md, metadata.json)"]:::external
    end

    API["Gemini API"]:::external

    User -->|interacts| Entry
    Styles --> Entry
    Vite --> Entry
    TSConfig --> Vite
    Package --> Vite
    GitIgnore --> Vite
    Vite -->|bundles| Hosting
    Hosting -->|serves| User
    README --> Hosting
    API -->|responds| Embeddings
    Embeddings -->|updates| Scene
    Embeddings -->|displays| Toast

    %% Click Events
    click HTML "https://github.com/ths41461/spacedj/blob/main/index.html"
    click Entry "https://github.com/ths41461/spacedj/blob/main/index.tsx"
    click Styles "https://github.com/ths41461/spacedj/blob/main/index.css"
    click Styles "https://github.com/ths41461/spacedj/blob/main/styles.ts"
    click Vite "https://github.com/ths41461/spacedj/blob/main/vite.config.ts"
    click TSConfig "https://github.com/ths41461/spacedj/blob/main/tsconfig.json"
    click Package "https://github.com/ths41461/spacedj/blob/main/package.json"
    click GitIgnore "https://github.com/ths41461/spacedj/blob/main/.gitignore"
    click Scene "https://github.com/ths41461/spacedj/blob/main/scene.ts"
    click Grid "https://github.com/ths41461/spacedj/blob/main/grid.ts"
    click Points "https://github.com/ths41461/spacedj/blob/main/points.ts"
    click Spaceship "https://github.com/ths41461/spacedj/blob/main/spaceship.ts"
    click SpaceState "https://github.com/ths41461/spacedj/blob/main/space.ts"
    click Settings "https://github.com/ths41461/spacedj/blob/main/space_settings.ts"
    click Selection "https://github.com/ths41461/spacedj/blob/main/selection.ts"
    click IconBtn "https://github.com/ths41461/spacedj/blob/main/icon_button.ts"
    click Tooltip "https://github.com/ths41461/spacedj/blob/main/tooltip.ts"
    click Toast "https://github.com/ths41461/spacedj/blob/main/toast.ts"
    click Labels "https://github.com/ths41461/spacedj/blob/main/labels.ts"
    click Embeddings "https://github.com/ths41461/spacedj/blob/main/embeddings.ts"
    click Utils "https://github.com/ths41461/spacedj/blob/main/utils.ts"
    click README "https://github.com/ths41461/spacedj/blob/main/README.md"
    click README "https://github.com/ths41461/spacedj/blob/main/metadata.json"

    classDef frontend fill:#e0f7fa,stroke:#006064,color:#006064
    classDef external fill:#e8f5e9,stroke:#2e7d32,color:#2e7d32
    classDef build fill:#fff3e0,stroke:#ef6c00,color:#e65100
    classDef config fill:#fffde7,stroke:#f9a825,color:#f57f17
```
