# veer0p/supabase-manager-v3 architecture

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

- Interactive diagram: https://gitdiagram.com/veer0p/supabase-manager-v3
- Repository: https://github.com/veer0p/supabase-manager-v3

## Overview

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: [`frontend/src/App.jsx`](https://github.com/veer0p/supabase-manager-v3/blob/master/frontend/src/App.jsx) (UI shell), [`backend/server.js`](https://github.com/veer0p/supabase-manager-v3/blob/master/backend/server.js) (API server), [`frontend/src/lib/api.js`](https://github.com/veer0p/supabase-manager-v3/blob/master/frontend/src/lib/api.js) (API clients), [`vps-dashboard/src/App.jsx`](https://github.com/veer0p/supabase-manager-v3/blob/master/vps-dashboard/src/App.jsx) (VPS app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ops["Root ops"]
  node_root_deploy["Deploy pipeline<br/>automation"]
  node_root_pm2["PM2 config<br/>runtime config"]
end

subgraph group_backend["Backend"]
  node_backend_server["API server<br/>express api<br/>[server.js]"]
  node_backend_bootstrap["Bootstrap flow<br/>init scripts"]
  node_backend_metrics["Metrics helper<br/>python telemetry<br/>[metrics.py]"]
  node_backend_data["Seed data<br/>fixtures<br/>[config.json]"]
end

subgraph group_frontend["Frontend"]
  node_frontend_shell["UI shell<br/>react app<br/>[App.jsx]"]
  node_frontend_pages["Dashboard pages<br/>views<br/>[Overview.jsx]"]
  node_frontend_clients["API clients<br/>data access<br/>[api.js]"]
  node_frontend_components["Shared widgets<br/>ui components<br/>[ConfirmModal.jsx]"]
  node_frontend_notifications["Notifications<br/>state/context"]
end

subgraph group_migrations["Migrations"]
  node_db_migrate["Migration runner<br/>sql tooling<br/>[migrate.js]"]
  node_db_schema["Schema SQL<br/>postgres ddl"]
end

subgraph group_vps["VPS dashboard"]
  node_vps_shell["VPS app<br/>react app<br/>[App.jsx]"]
  node_vps_api["VPS API<br/>node api<br/>[setup.js]"]
  node_vps_agent["VPS agent<br/>python agent<br/>[metrics_agent.py]"]
  node_vps_mock["Mock VPS<br/>simulation<br/>[mock-vps.js]"]
end

node_supabase_db[("Supabase DB<br/>database")]
node_remote_vps{{"Remote VPS<br/>infrastructure"}}

node_root_deploy -->|"deploys"| node_backend_server
node_root_deploy -->|"deploys"| node_frontend_shell
node_root_deploy -->|"syncs"| node_remote_vps
node_root_pm2 -->|"runs"| node_backend_server
node_backend_server -->|"reads/writes"| node_supabase_db
node_backend_bootstrap -->|"initializes"| node_supabase_db
node_backend_bootstrap -->|"prepares"| node_remote_vps
node_backend_metrics -->|"writes metrics"| node_supabase_db
node_backend_data -->|"feeds"| node_backend_bootstrap
node_frontend_shell -->|"renders"| node_frontend_pages
node_frontend_shell -->|"composes"| node_frontend_components
node_frontend_shell -->|"uses"| node_frontend_notifications
node_frontend_shell -->|"fetches via"| node_frontend_clients
node_frontend_clients -->|"calls API"| node_backend_server
node_frontend_clients -->|"direct access"| node_supabase_db
node_db_migrate -->|"applies"| node_db_schema
node_db_schema -->|"defines"| node_supabase_db
node_vps_shell -->|"calls"| node_vps_api
node_vps_shell -.->|"can use"| node_vps_mock
node_vps_api -->|"coordinates"| node_vps_agent
node_vps_agent -->|"collects from"| node_remote_vps
node_backend_server -.->|"integrates"| node_backend_metrics

click node_root_pm2 "https://github.com/veer0p/supabase-manager-v3/blob/master/backend/ecosystem.config.js"
click node_backend_server "https://github.com/veer0p/supabase-manager-v3/blob/master/backend/server.js"
click node_backend_metrics "https://github.com/veer0p/supabase-manager-v3/blob/master/backend/metrics.py"
click node_backend_data "https://github.com/veer0p/supabase-manager-v3/blob/master/backend/data/config.json"
click node_frontend_shell "https://github.com/veer0p/supabase-manager-v3/blob/master/frontend/src/App.jsx"
click node_frontend_pages "https://github.com/veer0p/supabase-manager-v3/blob/master/frontend/src/pages/Overview.jsx"
click node_frontend_clients "https://github.com/veer0p/supabase-manager-v3/blob/master/frontend/src/lib/api.js"
click node_frontend_components "https://github.com/veer0p/supabase-manager-v3/blob/master/frontend/src/components/ConfirmModal.jsx"
click node_frontend_notifications "https://github.com/veer0p/supabase-manager-v3/blob/master/frontend/src/NotificationContext.jsx"
click node_db_migrate "https://github.com/veer0p/supabase-manager-v3/blob/master/migrations/migrate.js"
click node_db_schema "https://github.com/veer0p/supabase-manager-v3/blob/master/migrations/001_init_schema.sql"
click node_vps_shell "https://github.com/veer0p/supabase-manager-v3/blob/master/vps-dashboard/src/App.jsx"
click node_vps_api "https://github.com/veer0p/supabase-manager-v3/blob/master/vps-dashboard/api/setup.js"
click node_vps_agent "https://github.com/veer0p/supabase-manager-v3/blob/master/vps-dashboard/agent/metrics_agent.py"
click node_vps_mock "https://github.com/veer0p/supabase-manager-v3/blob/master/vps-dashboard/mock-vps.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_root_deploy,node_root_pm2 toneBlue
class node_backend_server,node_backend_bootstrap,node_backend_metrics,node_backend_data toneAmber
class node_frontend_shell,node_frontend_pages,node_frontend_clients,node_frontend_components,node_frontend_notifications toneMint
class node_db_migrate,node_db_schema toneRose
class node_vps_shell,node_vps_api,node_vps_agent,node_vps_mock toneIndigo
class node_supabase_db,node_remote_vps toneNeutral
```

## Components

### Root ops

Deployment, environment checks, and release automation at the repository root.

- **Deploy pipeline**: automation · SSH-driven release and environment synchronization scripts for the main system.
- [PM2 config](https://github.com/veer0p/supabase-manager-v3/blob/master/backend/ecosystem.config.js): runtime 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](https://github.com/veer0p/supabase-manager-v3/blob/master/backend/server.js): express api · Primary Node.js runtime service for dashboard and infrastructure operations. · `backend/server.js`
- **Bootstrap flow**: init scripts · Database and remote-environment initialization, seeding, and master DB setup.
- [Metrics helper](https://github.com/veer0p/supabase-manager-v3/blob/master/backend/metrics.py): python telemetry · Backend-side Python helper for collecting or preparing host metrics. · `backend/metrics.py`
- [Seed data](https://github.com/veer0p/supabase-manager-v3/blob/master/backend/data/config.json): fixtures · 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](https://github.com/veer0p/supabase-manager-v3/blob/master/frontend/src/App.jsx): react app · Main SPA entry and global app wiring for the dashboard. · `frontend/src/App.jsx`
- [Dashboard pages](https://github.com/veer0p/supabase-manager-v3/blob/master/frontend/src/pages/Overview.jsx): views · Primary control-panel pages for overview, instances, nodes, files, visitors, settings, and login. · `frontend/src/pages/Overview.jsx`
- [API clients](https://github.com/veer0p/supabase-manager-v3/blob/master/frontend/src/lib/api.js): data access · Browser clients for backend API calls and direct Supabase access. · `frontend/src/lib/api.js`
- [Shared widgets](https://github.com/veer0p/supabase-manager-v3/blob/master/frontend/src/components/ConfirmModal.jsx): ui components · Reusable UI pieces such as modals, selectors, loaders, logs, and skeletons. · `frontend/src/components/ConfirmModal.jsx`
- [Notifications](https://github.com/veer0p/supabase-manager-v3/blob/master/frontend/src/NotificationContext.jsx): state/context · Cross-app notification and modal coordination for user feedback. · `frontend/src/NotificationContext.jsx`

### Migrations

Standalone PostgreSQL/Supabase schema management boundary.

- [Migration runner](https://github.com/veer0p/supabase-manager-v3/blob/master/migrations/migrate.js): sql tooling · Script that applies schema changes outside the application runtime. · `migrations/migrate.js`
- [Schema SQL](https://github.com/veer0p/supabase-manager-v3/blob/master/migrations/001_init_schema.sql): postgres ddl · 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](https://github.com/veer0p/supabase-manager-v3/blob/master/vps-dashboard/src/App.jsx): react app · Standalone VPS monitoring/demo application shell. · `vps-dashboard/src/App.jsx`
- [VPS API](https://github.com/veer0p/supabase-manager-v3/blob/master/vps-dashboard/api/setup.js): node api · Auxiliary setup and stats endpoints for the standalone VPS dashboard. · `vps-dashboard/api/setup.js`
- [VPS agent](https://github.com/veer0p/supabase-manager-v3/blob/master/vps-dashboard/agent/metrics_agent.py): python agent · Host-side metrics agent and installer for the secondary VPS environment. · `vps-dashboard/agent/metrics_agent.py`
- [Mock VPS](https://github.com/veer0p/supabase-manager-v3/blob/master/vps-dashboard/mock-vps.js): simulation · Local mock host used for development and offline testing of the VPS dashboard. · `vps-dashboard/mock-vps.js`

### Other components

- **Supabase DB**: database · Primary PostgreSQL/Supabase data store used by the main dashboard.
- **Remote VPS**: infrastructure · Target host environment for deployment, runtime processes, and agent collection.

## Connections

- 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.
