# improdead/vector-roblox architecture

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

- Interactive diagram: https://gitdiagram.com/improdead/vector-roblox
- Repository: https://github.com/improdead/vector-roblox

## Overview

##### Project type and purpose
- Vector is a full-stack system comprising a Roblox Studio plugin (written in Luau) and a Next.js backend (TypeScript).
- Purpose: Provide an AI-driven “copilot” inside Roblox Studio that gathers context (scripts, selection), calls LLM tools in a deterministic, proposal-first workflow, previews diffs, and applies safe, undoable edits or asset operations.

##### File structure
- Top level:
- vector/apps/web → Next.js backend (API routes, orchestrator, tool schemas, stores, providers)
- vector/plugin → Roblox Studio plugin (Luau code under src, tools for edits and instance ops)
- Backend substructure:
- app/api/... → REST endpoints for chat, proposals, stream, assets/search, assets/generate3d
- lib/orchestrator → LLM orchestration logic, tool registry, context management
- lib/store → file-based persistence for proposals and workflows
- lib/catalog, lib/checkpoints, lib/diff → supporting modules
- Plugin substructure:
- src/main.server.lua → entrypoint
- src/net/http.lua → HTTP helpers
- src/tools/*.lua → per-tool implementations (apply_edit, create_instance, etc.)

##### README insights
- Runtime split: plugin handles UI, diff rendering, using Roblox’s ChangeHistoryService; backend handles planning, LLM calls, proposal building, persistence.
- One-tool-per-message, approval-first pattern (mirroring Cline).
- Streaming via long-poll for plugin, SSE for dashboards; caching and audit logging.
- External integrations: Roblox Catalog API or stubs, Meshy for 3D generation, Open Cloud for uploads.

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Plugin Layer
  subgraph "Roblox Studio Plugin"
    direction TB
    Entry["Entrypoint (main.server.lua)"]:::plugin
    HTTP["HTTP Helpers (http.lua)"]:::plugin
    UI["Chat UI & Context Collector"]:::plugin
    Renderer["Proposal Renderer & Approval Gate"]:::plugin
    Executor["Tool Executor"]:::plugin
    CHS["ChangeHistoryService"]:::plugin
    Entry --> HTTP
    HTTP --> UI
    UI --> Renderer
    Renderer --> Executor
    Executor --> CHS
  end

  %% Backend Layer
  subgraph "Next.js Backend"
    direction TB
    %% API Layer
    subgraph "API Layer" 
      direction TB
      ChatAPI["POST /api/chat"]:::backend
      ProposalsAPI["/api/proposals"]:::backend
      ProposalsItem["/api/proposals/:id"]:::backend
      ProposalsApply["/api/proposals/:id/apply"]:::backend
      StreamPoll["/api/stream"]:::backend
      StreamSSE["/api/stream/sse"]:::backend
      AssetsSearch["/api/assets/search"]:::backend
      AssetsGen3D["/api/assets/generate3d"]:::backend
      CheckpointsAPI["/api/checkpoints"]:::backend
      CheckpointItem["/api/checkpoints/:id"]:::backend
      CheckpointRestore["/api/checkpoints/:id/restore"]:::backend
      WorkflowsAPI["/api/workflows"]:::backend
      WorkflowItem["/api/workflows/:id"]:::backend
    end

    %% Orchestrator
    subgraph "Orchestrator"
      direction TB
      CoreLogic["Core Logic & Registry"]:::backend
      ContextMgr["Context Manager"]:::backend
      ProposalBuilder["Proposal Builder"]:::backend
      AutoApprove["Auto-approval Logic"]:::backend
      TaskState["Task State Tracking"]:::backend
    end

    %% LLM Providers
    subgraph "LLM Providers"
      direction TB
      OpenAI["OpenAI"]:::external
      OpenRouter["OpenRouter"]:::external
      Gemini["Gemini"]:::external
    end

    %% Tools & Diff
    subgraph "Tools & Diff Modules"
      direction TB
      Schemas["Tool Schemas & Intel"]:::backend
      Diff3["Diff3 Module"]:::backend
      RangeEdits["Range Edits Module"]:::backend
    end

    %% Catalog & Checkpoints & Persistence
    subgraph "Integrations & Stores"
      direction TB
      Catalog["Roblox Catalog API"]:::external
      Meshy["Meshy API + Open Cloud"]:::external
      PersistUtil["Persistence Utilities"]:::store
      ProposalsStore["Proposals Store"]:::store
      SessionsStore["Sessions Store"]:::store
      StreamStore["Stream Store"]:::store
      WorkflowsStore["Workflows Store"]:::store
      CheckpointsMgr["Checkpoints Manager"]:::backend
    end

    %% UI Shell
    Layout["Next.js Layout & UI Shell"]:::backend
    Page["Landing Page"]:::backend

    %% Connections in Backend
    ChatAPI --> CoreLogic
    CoreLogic --> ContextMgr
    CoreLogic --> ProposalBuilder
    ContextMgr --> ProposalBuilder
    ProposalBuilder --> AutoApprove
    AutoApprove --> TaskState
    ProposalBuilder --> Schemas
    CoreLogic --> Diff3
    CoreLogic --> RangeEdits
    CoreLogic --> ProposalsStore
    CoreLogic --> SessionsStore
    CoreLogic --> StreamStore
    CoreLogic --> WorkflowsStore
    ProposalBuilder --> OpenAI
    ProposalBuilder --> OpenRouter
    ProposalBuilder --> Gemini
    AssetsSearch --> Catalog
    AssetsGen3D --> Meshy
    CheckpointsAPI --> CheckpointsMgr
    CheckpointItem --> CheckpointsMgr
    CheckpointRestore --> CheckpointsMgr
    WorkflowsAPI --> WorkflowsStore
    WorkflowItem --> WorkflowsStore
    StreamPoll --> StreamStore
    StreamSSE --> StreamStore
    Layout --> ChatAPI
    Layout --> Page
  end

  %% Cross-tier communications
  UI -->|POST /api/chat| ChatAPI
  Renderer -->|POST /api/proposals/:id/apply| ProposalsApply
  Renderer -->|poll /api/stream| StreamPoll
  StreamSSE --> Renderer
  Executor -->|executes proposal| CHS

  %% Click Events
  click Entry "https://github.com/improdead/vector-roblox/blob/main/vector/plugin/src/main.server.lua"
  click HTTP "https://github.com/improdead/vector-roblox/blob/main/vector/plugin/src/net/http.lua"
  click Executor "https://github.com/improdead/vector-roblox/blob/main/vector/plugin/src/tools/*.lua"
  click ChatAPI "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/app/api/chat/route.ts"
  click ProposalsAPI "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/app/api/proposals/route.ts"
  click ProposalsItem "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/app/api/proposals/[id]/route.ts"
  click ProposalsApply "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/app/api/proposals/[id]/apply/route.ts"
  click StreamPoll "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/app/api/stream/route.ts"
  click StreamSSE "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/app/api/stream/sse/route.ts"
  click AssetsSearch "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/app/api/assets/search/route.ts"
  click AssetsGen3D "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/app/api/assets/generate3d/route.ts"
  click CheckpointsAPI "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/app/api/checkpoints/route.ts"
  click CheckpointItem "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/app/api/checkpoints/[id]/route.ts"
  click CheckpointRestore "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/app/api/checkpoints/[id]/restore/route.ts"
  click WorkflowsAPI "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/app/api/workflows/route.ts"
  click WorkflowItem "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/app/api/workflows/[id]/route.ts"
  click CoreLogic "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/lib/orchestrator/index.ts"
  click ContextMgr "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/lib/orchestrator/context.ts"
  click ProposalBuilder "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/lib/orchestrator/proposals.ts"
  click AutoApprove "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/lib/orchestrator/autoApprove.ts"
  click TaskState "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/lib/orchestrator/taskState.ts"
  click OpenAI "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/lib/orchestrator/providers/openai.ts"
  click OpenRouter "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/lib/orchestrator/providers/openrouter.ts"
  click Gemini "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/lib/orchestrator/providers/gemini.ts"
  click PersistUtil "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/lib/store/persist.ts"
  click ProposalsStore "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/lib/store/proposals.ts"
  click SessionsStore "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/lib/store/sessions.ts"
  click StreamStore "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/lib/store/stream.ts"
  click WorkflowsStore "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/lib/store/workflows.ts"
  click Diff3 "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/lib/diff/diff3.ts"
  click RangeEdits "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/lib/diff/rangeEdits.ts"
  click Catalog "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/lib/catalog/search.ts"
  click CheckpointsMgr "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/lib/checkpoints/manager.ts"
  click Schemas "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/lib/tools/schemas.ts"
  click Layout "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/app/layout.tsx"
  click Page "https://github.com/improdead/vector-roblox/blob/main/vector/apps/web/app/page.tsx"

  %% Style Definitions
  classDef plugin fill:#E0F7FA,stroke:#006064;
  classDef backend fill:#E8F5E9,stroke:#1B5E20;
  classDef external fill:#ECEFF1,stroke:#37474F,stroke-dasharray: 5 5;
  classDef store fill:#FFF9C4,stroke:#F57F17;
  class Entry,HTTP,UI,Renderer,Executor,CHS plugin;
  class ChatAPI,ProposalsAPI,ProposalsItem,ProposalsApply,StreamPoll,StreamSSE,AssetsSearch,AssetsGen3D,CheckpointsAPI,CheckpointItem,CheckpointRestore,WorkflowsAPI,WorkflowItem,CoreLogic,ContextMgr,ProposalBuilder,AutoApprove,TaskState,Schemas,Diff3,RangeEdits,CheckpointsMgr,Layout,Page backend;
  class OpenAI,OpenRouter,Gemini,Catalog,Meshy external;
  class PersistUtil,ProposalsStore,SessionsStore,StreamStore,WorkflowsStore store;
```
