How whtitefall/gweb works
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: App.tsx Graph Studio · openai.go AI Endpoint · api.ts API Client · server.go Go API
Components 20
Frontend
React/Vite graph studio
- Graph Studio · Main browser application
frontend/src/App.tsx - Graph State · Canvas state, edits, and sync
frontend/src/hooks/useGraphState.ts - API Client · Frontend persistence and AI requests
frontend/src/api.ts - Auth UI · Supabase sign-in and session handling
frontend/src/components/AuthModal.tsx - Graph Editor · Nodes, edges, groups, menus, and drawers
frontend/src/components/GraphContextMenu.tsx - Graph Model · Graph, node, edge, group, item, note shapes
frontend/src/graphTypes.ts - Import/Export · Move full graph documents in and out
frontend/src/utils/graph.ts - Supabase Client · Browser login and token acquisition
frontend/src/supabaseClient.ts
Backend
Go API and persistence
- Go API · Main trust boundary for graph data
backend/server.go - Graph CRUD · List, create, fetch, update, delete graphs
backend/handlers_graph.go - Auth Layer · Verifies Supabase access tokens
backend/auth.go - Postgres Store · Supabase Postgres graph storage
backend/schema.sql - Node/Notes · Item and note operations around graphs
backend/node_notes.go - AI Endpoint · POST /api/ai/graph
backend/openai.go
AI Services
Direct and bridged inference providers
- OpenAI · Direct inference provider
- AI Bridge · Optional provider proxy
ai-server/main.py - vLLM · OpenAI-compatible inference endpoint
Other components
- Browser · End-user entry point
- Supabase Auth · Hosted authentication provider
- Supabase Postgres · Managed persistence backend
Connections 20
- 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