vishwanathhatti/visualli-ai

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