# vishwanathhatti/visualli-ai architecture

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

- Interactive diagram: https://gitdiagram.com/vishwanathhatti/visualli-ai
- Repository: https://github.com/vishwanathhatti/visualli-ai

## Overview

#### Purpose and Entry Points
Visualli is a full-stack 2D spatial canvas for browsing and moving up to 10,000 coordinate-based objects. The browser starts at `frontend/src/main.jsx`, composes the application in `frontend/src/App.jsx`, and renders the interactive scene through `frontend/src/canvas/PixiCanvas.jsx`. The API server starts in `backend/src/server.js`.

#### Frontend Application Shell
React provides the UI shell and overlays around the canvas: toolbar, coordinate/status HUD, zoom controls, and selected-object detail panel. These components coordinate viewport-oriented interaction rather than rendering individual objects as DOM nodes.
- `frontend/src/App.jsx`
- `frontend/src/components/Toolbar.jsx`
- `frontend/src/components/ObjectInfoPanel.jsx`

#### GPU Canvas and Viewport Stage
PixiJS/WebGL is the primary rendering runtime, chosen to keep large object counts performant. `PixiCanvas` owns canvas lifecycle and connects camera movement, object drawing, pointer interactions, and selection. Grid rendering is separated from object rendering, while viewport logic translates screen/camera state into world-coordinate bounds.
- `frontend/src/canvas/PixiCanvas.jsx`
- `frontend/src/canvas/gridRenderer.js`
- `frontend/src/canvas/viewport.js`

#### Viewport-Scoped Object Loading
The frontend fetches only objects inside the current visible bounding box, rather than loading the full dataset. `fetchObjects` calls the backend spatial query endpoint; `objectCache` retains/reuses object state across viewport changes and supports responsive interaction.
- `frontend/src/canvas/fetchObjects.js`
- `frontend/src/canvas/objectCache.js`
- `frontend/src/canvas/PixiCanvas.jsx`

#### Drag Update Control Flow
Dragging is intended to be optimistic: the canvas updates an object's displayed coordinates immediately, then sends `PATCH /api/objects/:id` with the final coordinates. The server persists the update and returns the canonical object. This establishes a boundary between transient canvas/cache state and database-backed state.
- `frontend/src/canvas/PixiCanvas.jsx`
- `frontend/src/canvas/fetchObjects.js`
- `backend/src/routes/objects.js`

#### API and Spatial Query Layer
Express exposes spatial-object routes, including bounding-box retrieval, coordinate patching, and dataset stats. The viewport query accepts `minX`, `maxX`, `minY`, `maxY`, and a limit; this is the main backend read path and the contract joining camera state to storage queries.
- `backend/src/server.js`
- `backend/src/routes/objects.js`

#### Persistence and Cache Boundary
PostgreSQL/Neon is the authoritative object store, accessed through the database module and indexed for `(x, y)` spatial-range reads. Redis/Upstash sits in front of viewport queries as a read-through cache, with responses marked by `X-Cache`. Object coordinate writes must invalidate or bypass affected cached query regions to prevent stale canvas data.
- `backend/src/db.js`
- `backend/src/redis.js`
- `backend/src/routes/objects.js`

#### Deployment and Data Initialization
The backend is Node.js/Express and is designed to remain compatible with Vercel serverless deployment. Local development uses environment-provided Neon PostgreSQL and Upstash Redis URLs; the seed script populates the spatial dataset. A local SQLite-related file set exists (`backend/spatial.db*`), but the documented production architecture identifies Neon PostgreSQL as the primary datastore.
- `backend/scripts/seed.js`
- `backend/.env.example`
- `backend/package.json`

Main entry points: [`frontend/src/canvas/PixiCanvas.jsx`](https://github.com/vishwanathhatti/visualli-ai/blob/main/frontend/src/canvas/PixiCanvas.jsx) (Interactive canvas), [`frontend/src/App.jsx`](https://github.com/vishwanathhatti/visualli-ai/blob/main/frontend/src/App.jsx) (Application shell), [`frontend/src/canvas/fetchObjects.js`](https://github.com/vishwanathhatti/visualli-ai/blob/main/frontend/src/canvas/fetchObjects.js) (Viewport fetcher), [`backend/src/routes/objects.js`](https://github.com/vishwanathhatti/visualli-ai/blob/main/backend/src/routes/objects.js) (Object routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser client"]
  node_main["React entry<br/>browser entry<br/>[main.jsx]"]
  node_app["Application shell<br/>React UI<br/>[App.jsx]"]
  node_toolbar["Toolbar<br/>UI overlay<br/>[Toolbar.jsx]"]
  node_object_panel["Object detail panel<br/>UI overlay"]
  node_pixi_canvas["Interactive canvas<br/>PixiJS/WebGL<br/>[PixiCanvas.jsx]"]
  node_viewport["Viewport bounds<br/>camera logic<br/>[viewport.js]"]
  node_grid["Grid renderer<br/>canvas renderer<br/>[gridRenderer.js]"]
  node_fetch_objects["Viewport fetcher<br/>API client<br/>[fetchObjects.js]"]
  node_object_cache["Object cache<br/>client cache<br/>[objectCache.js]"]
end

subgraph group_backend["API service"]
  node_server["Express server<br/>Node entry<br/>[server.js]"]
  node_object_routes["Object routes<br/>spatial API<br/>[objects.js]"]
  node_db_module["Database access<br/>PostgreSQL adapter<br/>[db.js]"]
  node_redis_module["Cache access<br/>Redis adapter<br/>[redis.js]"]
  node_seed["Dataset seed<br/>initialization script<br/>[seed.js]"]
end

subgraph group_data["Data services"]
  node_postgres[("Neon PostgreSQL<br/>authoritative store")]
  node_redis[("Upstash Redis<br/>read-through cache")]
end

node_main -->|"mounts"| node_app
node_app -->|"renders"| node_toolbar
node_app -->|"renders"| node_object_panel
node_app -->|"hosts"| node_pixi_canvas
node_pixi_canvas -->|"derives bounds"| node_viewport
node_pixi_canvas -->|"draws grid"| node_grid
node_viewport -->|"bounding box"| node_fetch_objects
node_fetch_objects -->|"stores results"| node_object_cache
node_object_cache -->|"supplies objects"| node_pixi_canvas
node_fetch_objects -->|"GET viewport query"| node_object_routes
node_pixi_canvas -->|"PATCH final drag coordinates"| node_fetch_objects
node_server -->|"serves"| node_object_routes
node_object_routes -->|"checks and invalidates"| node_redis_module
node_redis_module -->|"reads/writes"| node_redis
node_object_routes -->|"queries and updates"| node_db_module
node_db_module -->|"range reads and writes"| node_postgres
node_seed -->|"populates"| node_postgres

click node_main "https://github.com/vishwanathhatti/visualli-ai/blob/main/frontend/src/main.jsx"
click node_app "https://github.com/vishwanathhatti/visualli-ai/blob/main/frontend/src/App.jsx"
click node_toolbar "https://github.com/vishwanathhatti/visualli-ai/blob/main/frontend/src/components/Toolbar.jsx"
click node_object_panel "https://github.com/vishwanathhatti/visualli-ai/blob/main/frontend/src/components/ObjectInfoPanel.jsx"
click node_pixi_canvas "https://github.com/vishwanathhatti/visualli-ai/blob/main/frontend/src/canvas/PixiCanvas.jsx"
click node_viewport "https://github.com/vishwanathhatti/visualli-ai/blob/main/frontend/src/canvas/viewport.js"
click node_grid "https://github.com/vishwanathhatti/visualli-ai/blob/main/frontend/src/canvas/gridRenderer.js"
click node_fetch_objects "https://github.com/vishwanathhatti/visualli-ai/blob/main/frontend/src/canvas/fetchObjects.js"
click node_object_cache "https://github.com/vishwanathhatti/visualli-ai/blob/main/frontend/src/canvas/objectCache.js"
click node_server "https://github.com/vishwanathhatti/visualli-ai/blob/main/backend/src/server.js"
click node_object_routes "https://github.com/vishwanathhatti/visualli-ai/blob/main/backend/src/routes/objects.js"
click node_db_module "https://github.com/vishwanathhatti/visualli-ai/blob/main/backend/src/db.js"
click node_redis_module "https://github.com/vishwanathhatti/visualli-ai/blob/main/backend/src/redis.js"
click node_seed "https://github.com/vishwanathhatti/visualli-ai/blob/main/backend/scripts/seed.js"

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_main,node_app,node_toolbar,node_object_panel,node_pixi_canvas,node_viewport,node_grid,node_fetch_objects,node_object_cache toneBlue
class node_server,node_object_routes,node_db_module,node_redis_module,node_seed toneAmber
class node_postgres,node_redis toneMint
```

## Components

### Browser client

- [React entry](https://github.com/vishwanathhatti/visualli-ai/blob/main/frontend/src/main.jsx): browser entry · `frontend/src/main.jsx`
- [Application shell](https://github.com/vishwanathhatti/visualli-ai/blob/main/frontend/src/App.jsx): React UI · Hosts canvas controls, HUD, and selected-object details. · `frontend/src/App.jsx`
- [Toolbar](https://github.com/vishwanathhatti/visualli-ai/blob/main/frontend/src/components/Toolbar.jsx): UI overlay · `frontend/src/components/Toolbar.jsx`
- [Object detail panel](https://github.com/vishwanathhatti/visualli-ai/blob/main/frontend/src/components/ObjectInfoPanel.jsx): UI overlay · `frontend/src/components/ObjectInfoPanel.jsx`
- [Interactive canvas](https://github.com/vishwanathhatti/visualli-ai/blob/main/frontend/src/canvas/PixiCanvas.jsx): PixiJS/WebGL · Owns rendering, pointer interaction, selection, and optimistic dragging. · `frontend/src/canvas/PixiCanvas.jsx`
- [Viewport bounds](https://github.com/vishwanathhatti/visualli-ai/blob/main/frontend/src/canvas/viewport.js): camera logic · Converts screen and camera state into world-coordinate bounds. · `frontend/src/canvas/viewport.js`
- [Grid renderer](https://github.com/vishwanathhatti/visualli-ai/blob/main/frontend/src/canvas/gridRenderer.js): canvas renderer · `frontend/src/canvas/gridRenderer.js`
- [Viewport fetcher](https://github.com/vishwanathhatti/visualli-ai/blob/main/frontend/src/canvas/fetchObjects.js): API client · Requests objects within the visible bounding box. · `frontend/src/canvas/fetchObjects.js`
- [Object cache](https://github.com/vishwanathhatti/visualli-ai/blob/main/frontend/src/canvas/objectCache.js): client cache · Reuses loaded object state across viewport changes. · `frontend/src/canvas/objectCache.js`

### API service

- [Express server](https://github.com/vishwanathhatti/visualli-ai/blob/main/backend/src/server.js): Node entry · `backend/src/server.js`
- [Object routes](https://github.com/vishwanathhatti/visualli-ai/blob/main/backend/src/routes/objects.js): spatial API · Provides bounding-box reads, coordinate patches, and dataset stats. · `backend/src/routes/objects.js`
- [Database access](https://github.com/vishwanathhatti/visualli-ai/blob/main/backend/src/db.js): PostgreSQL adapter · `backend/src/db.js`
- [Cache access](https://github.com/vishwanathhatti/visualli-ai/blob/main/backend/src/redis.js): Redis adapter · `backend/src/redis.js`
- [Dataset seed](https://github.com/vishwanathhatti/visualli-ai/blob/main/backend/scripts/seed.js): initialization script · Populates the spatial dataset. · `backend/scripts/seed.js`

### Data services

- **Neon PostgreSQL**: authoritative store · Spatial objects are indexed for x/y range reads.
- **Upstash Redis**: read-through cache · Caches viewport-query responses.

## Connections

- React entry → Application shell: mounts
- Application shell → Toolbar: renders
- Application shell → Object detail panel: renders
- Application shell → Interactive canvas: hosts
- Interactive canvas → Viewport bounds: derives bounds
- Interactive canvas → Grid renderer: draws grid
- Viewport bounds → Viewport fetcher: bounding box
- Viewport fetcher → Object cache: stores results
- Object cache → Interactive canvas: supplies objects
- Viewport fetcher → Object routes: GET viewport query
- Interactive canvas → Viewport fetcher: PATCH final drag coordinates
- Express server → Object routes: serves
- Object routes → Cache access: checks and invalidates
- Cache access → Upstash Redis: reads/writes
- Object routes → Database access: queries and updates
- Database access → Neon PostgreSQL: range reads and writes
- Dataset seed → Neon PostgreSQL: populates