# whtitefall/gweb architecture

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

- Interactive diagram: https://gitdiagram.com/whtitefall/gweb
- Repository: https://github.com/whtitefall/gweb

## Overview

1. **Top-level shape**
   - The repo is split into three runtime boundaries: a **React/Vite frontend**, a **Go backend API**, and an **optional Python AI bridge service**.
   - Persistent data lives in **Supabase Postgres**; authentication is handled by **Supabase Auth**. The backend is the main trust boundary for graph data.

2. **Frontend: interactive graph studio**
   - `frontend/` is a single-page app built with **React + TypeScript + Vite**.
   - The core experience is the **2D graph editor**: node/edge/group editing, drag/drop, context menus, list management, and drawers/modals for node details, tasks, settings, and SSH/chat-related panels.
   - There is also a **Quick Facts** view for static graph-theory content, plus some **3D/beta scaffolding** that exists in code but is not the default path.

3. **Frontend state and API boundary**
   - The frontend owns the immediate UI state for the graph canvas, but it delegates persistence and AI generation through `src/api.ts` and the graph state hook in `src/hooks/useGraphState.ts`.
   - Utility modules handle cross-cutting concerns like auth token handling, IDs, storage, rich text, theme, and graph/item transformations.
   - The frontend talks to the backend over HTTP using `VITE_API_URL`, and it uses the Supabase client for login flows.

4. **Graph domain model**
   - The central domain object is a **graph** containing **nodes, edges, groups, items, and notes**.
   - Import/export is JSON-based and includes the full graph payload, which means a graph can be moved without involving the database.
   - The UI components are organized around this model: graph list, graph editor, item/note drawers, and node-specific controls.

5. **Backend: REST API and business logic**
   - `backend/` is a **Go** service using **pgx** to talk to Postgres.
   - It exposes REST endpoints for graph CRUD and AI generation: health, list/create/fetch/update/delete graphs, and `POST /api/ai/graph`.
   - Backend files are split by concern: server/bootstrap, auth, CORS, migrations, schema, graph handlers, node/note logic, OpenAI/model-server integration, and shared types/utilities.

6. **Auth and tenancy**
   - Graphs are **scoped per authenticated user**.
   - The backend validates Supabase access tokens using the configured `SUPABASE_JWT_SECRET`, and the frontend acquires those tokens through Supabase Auth.
   - Supported sign-in paths include Google and GitHub, plus a test-login UI mentioned in the README.

7. **Persistence layer**
   - `backend/schema.sql` defines the database shape, and `backend/migrations.go` suggests startup or managed migration support.
   - The backend persists graph documents in Supabase Postgres rather than in the frontend or local filesystem.
   - This makes the database the source of truth for multi-device graph editing and list management.

8. **AI generation pipeline**
   - AI graph creation is triggered from the frontend chat/UI and handled by the backend endpoint `POST /api/ai/graph`.
   - The backend selects between two providers: **OpenAI** directly, or a **model_server** mode that forwards requests to the Python AI service.
   - The AI response is expected to come back as a graph object, which the frontend applies immediately to the current workspace.

9. **Optional Python AI bridge**
   - `ai-server/` is a lightweight **Python/FastAPI-style** service that bridges the Go backend to a local or private **vLLM/OpenAI-compatible endpoint**.
   - It is optional and only relevant when `AI_DEFAULT_PROVIDER=model_server`.
   - In that deployment, the backend calls the AI server, which in turn calls vLLM; this keeps the model endpoint private and separates app logic from inference.

10. **Important infrastructure boundaries**
   - The default deployment assumes public access only to the frontend and Go API, with **Supabase**, **OpenAI**, or a private **model server** acting as external dependencies.
   - The README explicitly treats the vLLM and AI bridge as private services, especially for EC2/GPU deployments.
   - CORS is controlled in the backend, which matters because the frontend runs on a different origin during development.

11. **What is not in the main path**
   - The codebase contains 3D-related dependencies and components, but they are **future/beta scaffolding** rather than the primary product path.
   - For an architecture diagram, these should be shown as optional or disabled capabilities, not as part of the critical request flow.

12. **Suggested diagram emphasis**
   - The clearest diagram would show: **user/browser → React frontend → Go API → Postgres/Supabase**, with a side path for **auth via Supabase Auth** and a separate AI path from the backend to either **OpenAI** or **ai-server → vLLM**.
   - The graph editor, drawers, and import/export features are all frontend concerns; persistence and authorization stay in the backend; inference is an isolated external branch.

Main entry points: [`frontend/src/App.tsx`](https://github.com/whtitefall/gweb/blob/main/frontend/src/App.tsx) (Graph Studio), [`backend/openai.go`](https://github.com/whtitefall/gweb/blob/main/backend/openai.go) (AI Endpoint), [`frontend/src/api.ts`](https://github.com/whtitefall/gweb/blob/main/frontend/src/api.ts) (API Client), [`backend/server.go`](https://github.com/whtitefall/gweb/blob/main/backend/server.go) (Go API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Frontend"]
  node_frontend_app["Graph Studio<br/>React SPA<br/>[App.tsx]"]
  node_graph_state["Graph State<br/>state hook<br/>[useGraphState.ts]"]
  node_api_client["API Client<br/>HTTP boundary<br/>[api.ts]"]
  node_auth_ui["Auth UI<br/>login flow<br/>[AuthModal.tsx]"]
  node_graph_ui["Graph Editor<br/>canvas UI"]
  node_graph_models["Graph Model<br/>domain types<br/>[graphTypes.ts]"]
  node_import_export["Import/Export<br/>json payloads<br/>[graph.ts]"]
  node_supabase_client["Supabase Client<br/>auth client<br/>[supabaseClient.ts]"]
end

subgraph group_api["Backend"]
  node_backend_api["Go API<br/>REST service<br/>[server.go]"]
  node_graph_handlers["Graph CRUD<br/>handlers<br/>[handlers_graph.go]"]
  node_auth_layer["Auth Layer<br/>jwt validation<br/>[auth.go]"]
  node_db_layer[("Postgres Store<br/>pgx persistence<br/>[schema.sql]")]
  node_node_notes["Node/Notes<br/>domain logic<br/>[node_notes.go]"]
  node_ai_endpoint["AI Endpoint<br/>generation api<br/>[openai.go]"]
end

subgraph group_ai["AI Services"]
  node_openai(("OpenAI<br/>external model"))
  node_ai_bridge["AI Bridge<br/>FastAPI service<br/>[main.py]"]
  node_vllm(("vLLM<br/>private model server"))
end

node_browser(("Browser<br/>user client"))
node_supabase_auth(("Supabase Auth<br/>identity service"))
node_supabase_db[("Supabase Postgres<br/>database")]

node_browser -->|"uses"| node_frontend_app
node_frontend_app -->|"renders"| node_graph_ui
node_frontend_app -->|"state"| node_graph_state
node_graph_state -->|"uses"| node_graph_models
node_graph_ui -->|"imports/exports"| node_import_export
node_frontend_app -->|"calls"| node_api_client
node_frontend_app -->|"auth"| node_supabase_client
node_supabase_client -->|"signin"| node_supabase_auth
node_api_client -->|"http"| node_backend_api
node_backend_api -->|"checks"| node_auth_layer
node_auth_layer -->|"verifies"| node_supabase_auth
node_backend_api -->|"routes"| node_graph_handlers
node_graph_handlers -->|"delegates"| node_node_notes
node_graph_handlers -->|"reads/writes"| node_db_layer
node_db_layer -->|"stores"| node_supabase_db
node_api_client -->|"requests"| node_ai_endpoint
node_ai_endpoint -->|"provider"| node_openai
node_ai_endpoint -->|"provider"| node_ai_bridge
node_ai_bridge -->|"forwards"| node_vllm
node_ai_endpoint -->|"returns graph"| node_graph_state

click node_frontend_app "https://github.com/whtitefall/gweb/blob/main/frontend/src/App.tsx"
click node_graph_state "https://github.com/whtitefall/gweb/blob/main/frontend/src/hooks/useGraphState.ts"
click node_api_client "https://github.com/whtitefall/gweb/blob/main/frontend/src/api.ts"
click node_auth_ui "https://github.com/whtitefall/gweb/blob/main/frontend/src/components/AuthModal.tsx"
click node_graph_ui "https://github.com/whtitefall/gweb/blob/main/frontend/src/components/GraphContextMenu.tsx"
click node_graph_models "https://github.com/whtitefall/gweb/blob/main/frontend/src/graphTypes.ts"
click node_import_export "https://github.com/whtitefall/gweb/blob/main/frontend/src/utils/graph.ts"
click node_supabase_client "https://github.com/whtitefall/gweb/blob/main/frontend/src/supabaseClient.ts"
click node_backend_api "https://github.com/whtitefall/gweb/blob/main/backend/server.go"
click node_graph_handlers "https://github.com/whtitefall/gweb/blob/main/backend/handlers_graph.go"
click node_auth_layer "https://github.com/whtitefall/gweb/blob/main/backend/auth.go"
click node_db_layer "https://github.com/whtitefall/gweb/blob/main/backend/schema.sql"
click node_node_notes "https://github.com/whtitefall/gweb/blob/main/backend/node_notes.go"
click node_ai_endpoint "https://github.com/whtitefall/gweb/blob/main/backend/openai.go"
click node_ai_bridge "https://github.com/whtitefall/gweb/blob/main/ai-server/main.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_app,node_graph_state,node_api_client,node_auth_ui,node_graph_ui,node_graph_models,node_import_export,node_supabase_client toneBlue
class node_backend_api,node_graph_handlers,node_auth_layer,node_db_layer,node_node_notes,node_ai_endpoint toneAmber
class node_openai,node_ai_bridge,node_vllm toneMint
class node_browser,node_supabase_auth,node_supabase_db toneNeutral
```

## Components

### Frontend

React/Vite graph studio

- [Graph Studio](https://github.com/whtitefall/gweb/blob/main/frontend/src/App.tsx): React SPA · Main browser application · `frontend/src/App.tsx`
- [Graph State](https://github.com/whtitefall/gweb/blob/main/frontend/src/hooks/useGraphState.ts): state hook · Canvas state, edits, and sync · `frontend/src/hooks/useGraphState.ts`
- [API Client](https://github.com/whtitefall/gweb/blob/main/frontend/src/api.ts): HTTP boundary · Frontend persistence and AI requests · `frontend/src/api.ts`
- [Auth UI](https://github.com/whtitefall/gweb/blob/main/frontend/src/components/AuthModal.tsx): login flow · Supabase sign-in and session handling · `frontend/src/components/AuthModal.tsx`
- [Graph Editor](https://github.com/whtitefall/gweb/blob/main/frontend/src/components/GraphContextMenu.tsx): canvas UI · Nodes, edges, groups, menus, and drawers · `frontend/src/components/GraphContextMenu.tsx`
- [Graph Model](https://github.com/whtitefall/gweb/blob/main/frontend/src/graphTypes.ts): domain types · Graph, node, edge, group, item, note shapes · `frontend/src/graphTypes.ts`
- [Import/Export](https://github.com/whtitefall/gweb/blob/main/frontend/src/utils/graph.ts): json payloads · Move full graph documents in and out · `frontend/src/utils/graph.ts`
- [Supabase Client](https://github.com/whtitefall/gweb/blob/main/frontend/src/supabaseClient.ts): auth client · Browser login and token acquisition · `frontend/src/supabaseClient.ts`

### Backend

Go API and persistence

- [Go API](https://github.com/whtitefall/gweb/blob/main/backend/server.go): REST service · Main trust boundary for graph data · `backend/server.go`
- [Graph CRUD](https://github.com/whtitefall/gweb/blob/main/backend/handlers_graph.go): handlers · List, create, fetch, update, delete graphs · `backend/handlers_graph.go`
- [Auth Layer](https://github.com/whtitefall/gweb/blob/main/backend/auth.go): jwt validation · Verifies Supabase access tokens · `backend/auth.go`
- [Postgres Store](https://github.com/whtitefall/gweb/blob/main/backend/schema.sql): pgx persistence · Supabase Postgres graph storage · `backend/schema.sql`
- [Node/Notes](https://github.com/whtitefall/gweb/blob/main/backend/node_notes.go): domain logic · Item and note operations around graphs · `backend/node_notes.go`
- [AI Endpoint](https://github.com/whtitefall/gweb/blob/main/backend/openai.go): generation api · POST /api/ai/graph · `backend/openai.go`

### AI Services

Direct and bridged inference providers

- **OpenAI**: external model · Direct inference provider
- [AI Bridge](https://github.com/whtitefall/gweb/blob/main/ai-server/main.py): FastAPI service · Optional provider proxy · `ai-server/main.py`
- **vLLM**: private model server · OpenAI-compatible inference endpoint

### Other components

- **Browser**: user client · End-user entry point
- **Supabase Auth**: identity service · Hosted authentication provider
- **Supabase Postgres**: database · Managed persistence backend

## Connections

- Browser → Graph Studio: uses · User interacts with the app
- Graph Studio → Graph Editor: renders · Editor, drawers, and panels
- Graph Studio → Graph State: state · UI state and workspace coordination
- Graph State → Graph Model: uses · Shared graph domain shape
- Graph Editor → Import/Export: imports/exports · JSON graph transfer
- Graph Studio → API Client: calls · Persistence and AI requests
- Graph Studio → Supabase Client: auth · Login flows and tokens
- Supabase Client → Supabase Auth: signin · Google, GitHub, and test login flows
- API Client → Go API: http · Frontend talks to Go service
- Go API → Auth Layer: checks · Validates user identity
- Auth Layer → Supabase Auth: verifies · Supabase JWT validation
- Go API → Graph CRUD: routes · Graph REST endpoints
- Graph CRUD → Node/Notes: delegates · Node and note-specific logic
- Graph CRUD → Postgres Store: reads/writes · Graph documents per user
- Postgres Store → Supabase Postgres: stores · Managed Postgres persistence
- API Client → AI Endpoint: requests · Graph generation trigger
- AI Endpoint → OpenAI: provider · Direct OpenAI mode
- AI Endpoint → AI Bridge: provider · Model-server mode
- AI Bridge → vLLM: forwards · Private inference backend
- AI Endpoint → Graph State: returns graph · Generated graph applied to workspace