How veer0p/supabase-manager-v3 works
1. Repo shape: This is a monorepo with four meaningful areas: a deployment/ops layer at the root, a Node.js backend under backend/, a primary React/Vite frontend under frontend/, and a second standalone vps-dashboard/ app with its own agent/API pieces.
2. Primary runtime path: The main user flow is browser SPA → backend API → Postgres/Supabase. The frontend has an API client (src/lib/api.js) and a Supabase client (src/lib/supabase.js), so it likely combines direct Supabase interactions with backend-served data.
3. Frontend subsystem: frontend/ is the main dashboard UI. Its pages (Overview, Instances, Nodes, Files, Visitors, Settings, Login) suggest a single-page control panel for infrastructure and telemetry, with shared UI components for modals, selectors, skeletons, logs, and notifications.
4. Backend subsystem: backend/server.js is the runtime service, apparently an Express-based API. Surrounding files (init_db.js, setup_db.js, seed_system_data.js, remote_init.js, deploy_master_db.js) indicate the backend is also responsible for bootstrapping data, initializing remote environments, and coordinating deployment-related setup.
5. Database layer: The migrations/ directory is a standalone schema-management boundary for PostgreSQL/Supabase. 001_init_schema.sql and 002_vps_metrics.sql indicate the data model includes both core dashboard entities and metrics tables, with migrate.js applying schema changes outside the app runtime.
6. Seed/bootstrap data: backend/data/ plus files like config.json, instances.json, and nodes.json are likely local fixtures or bootstrap state used by the initialization scripts. This suggests a controlled provisioning flow: schema migration first, then seeded system records.
7. Telemetry collection: There are two metric-related implementations: backend/metrics.py and vps-dashboard/agent/metrics_agent.py. That points to mixed-runtime collection where a Python helper/agent gathers host stats and feeds them into the dashboard system rather than the browser reading metrics directly.
8. Secondary vps-dashboard subsystem: This directory is a separate app with its own Vite frontend, API (api/setup.js, api/stats.js), agent installer, and mock-vps.js. Architecturally, it looks like an auxiliary VPS monitoring/demo environment that can run independently from the main APEX DASH UI.
9. Infrastructure and deployment: Root scripts (deploy.sh, deploy_to_vps.js, sync_keys.js, check_env.js) plus .github/workflows/deploy.yml form the release pipeline. backend/ecosystem.config.js shows PM2 is the process manager on the target VPS, so deployment is centered on SSH-driven updates and supervised Node processes.
10. Operational boundaries: The repo separates concerns cleanly: UI rendering in React, API/business logic in Node, schema management in SQL migrations, and host telemetry in Python/agent code. For an architecture diagram, the main trust boundary is between the browser and backend/API, and the infrastructure boundary is between the backend/agents and the remote VPS or Supabase database.
Main entry points: src/App.jsx UI shell · server.js API server · api.js API clients · src/App.jsx VPS app
Components 19
Root ops
Deployment, environment checks, and release automation at the repository root.
- Deploy pipeline · SSH-driven release and environment synchronization scripts for the main system.
- PM2 config · Process manager definition for running the backend on the VPS.
backend/ecosystem.config.js
Backend
Node.js service plus initialization, seeding, and telemetry helpers.
- API server · Primary Node.js runtime service for dashboard and infrastructure operations.
backend/server.js - Bootstrap flow · Database and remote-environment initialization, seeding, and master DB setup.
- Metrics helper · Backend-side Python helper for collecting or preparing host metrics.
backend/metrics.py - Seed data · Local JSON state used by initialization and provisioning scripts.
backend/data/config.json
Frontend
Primary React/Vite dashboard UI and shared client-side utilities.
- UI shell · Main SPA entry and global app wiring for the dashboard.
frontend/src/App.jsx - Dashboard pages · Primary control-panel pages for overview, instances, nodes, files, visitors, settings, and login.
frontend/src/pages/Overview.jsx - API clients · Browser clients for backend API calls and direct Supabase access.
frontend/src/lib/api.js - Shared widgets · Reusable UI pieces such as modals, selectors, loaders, logs, and skeletons.
frontend/src/components/ConfirmModal.jsx - Notifications · Cross-app notification and modal coordination for user feedback.
frontend/src/NotificationContext.jsx
Migrations
Standalone PostgreSQL/Supabase schema management boundary.
- Migration runner · Script that applies schema changes outside the application runtime.
migrations/migrate.js - Schema SQL · Core schema and VPS metrics migrations for the dashboard data model.
migrations/001_init_schema.sql
VPS dashboard
Secondary standalone VPS monitoring/demo app with its own API and agent.
- VPS app · Standalone VPS monitoring/demo application shell.
vps-dashboard/src/App.jsx - VPS API · Auxiliary setup and stats endpoints for the standalone VPS dashboard.
vps-dashboard/api/setup.js - VPS agent · Host-side metrics agent and installer for the secondary VPS environment.
vps-dashboard/agent/metrics_agent.py - Mock VPS · Local mock host used for development and offline testing of the VPS dashboard.
vps-dashboard/mock-vps.js
Other components
- Supabase DB · Primary PostgreSQL/Supabase data store used by the main dashboard.
- Remote VPS · Target host environment for deployment, runtime processes, and agent collection.
Connections 22
- Deploy pipeline → API server: deploys · Release pipeline updates and restarts the backend service on the target host.
- Deploy pipeline → UI shell: deploys · Release pipeline ships the frontend build as part of the main system.
- Deploy pipeline → Remote VPS: syncs · Scripts synchronize keys, environment state, and remote deployment targets.
- PM2 config → API server: runs · PM2 supervises the Node.js API process in production.
- API server → Supabase DB: reads/writes · Backend API persists dashboard state and serves data from the database.
- Bootstrap flow → Supabase DB: initializes · Bootstrap scripts create schema, seed system records, and prepare remote data.
- Bootstrap flow → Remote VPS: prepares · Remote initialization and master DB deployment target the VPS environment.
- Metrics helper → Supabase DB: writes metrics · Python telemetry helper contributes host statistics into the shared data store.
- Seed data → Bootstrap flow: feeds · JSON fixtures provide controlled initial state for provisioning flows.
- UI shell → Dashboard pages: renders · The SPA shell hosts the dashboard views.
- UI shell → Shared widgets: composes · The app assembles shared UI widgets across pages.
- UI shell → Notifications: uses · Global notification context coordinates user-facing alerts and dialogs.
- UI shell → API clients: fetches via · The UI reads backend and Supabase data through client libraries.
- API clients → API server: calls API · Primary browser flow goes through the backend service.
- API clients → Supabase DB: direct access · Some browser flows connect directly to Supabase.
- Migration runner → Schema SQL: applies · Migration runner executes the repository's SQL schema changes.
- Schema SQL → Supabase DB: defines · Schema files describe the structure of the main database.
- VPS app → VPS API: calls · Standalone VPS UI talks to its local setup/stats API.
- VPS app → Mock VPS: can use · Development mode can swap in a mock VPS backend.
- VPS API → VPS agent: coordinates · API endpoints work with the host agent and installer for telemetry setup.
- VPS agent → Remote VPS: collects from · Agent gathers machine stats from the remote VPS host.
- API server → Metrics helper: integrates · The main service incorporates telemetry processing paths.