# laboffuture/admin-dash architecture

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

- Interactive diagram: https://gitdiagram.com/laboffuture/admin-dash
- Repository: https://github.com/laboffuture/admin-dash

## Overview

#### Purpose and entry points
ADMIN-LINK is a password-gated central operations portal for LOF projects. It renders a registered project catalog, reports live reachability, embeds a selected project’s existing admin page, and provides an agent chat surface. Backend startup is `server/index.js`; HTTP composition is in `server/app.js`. The browser starts at `client/src/main.jsx` and mounts the application in `client/src/App.jsx`.

#### Project registry and module boundary
`projects.json` is the runtime registry and primary extensibility boundary: each project is added as data rather than a client rebuild. `server/registry.js` loads and validates/exposes registry content to API consumers. Registry entries drive the sidebar/catalog, selected-project view, status checks, and iframe destination; remote modules remain independently deployed systems rather than code imported into this repository.

#### Authentication and API boundary
The server exposes the hub’s `/api` surface through `server/app.js`. `server/auth.js` implements the single-password authentication flow backed by `ADMIN_PASSWORD` from environment configuration. The client’s API contract is centralized in `client/src/api.js`, while `client/src/components/Login.jsx` gates access to hub functionality. This separates browser session/UI handling from server-side password verification and protected operations.

#### Project status polling
`server/poller.js` performs server-side health/reachability polling for registered module URLs, avoiding browser-side cross-origin checks and presenting status through the hub API. `server/registry.js` supplies project targets; `server/app.js` exposes resulting state. The frontend consumes updates through `client/src/hooks/useHubMessages.js`, allowing status and hub events to update independently of iframe content.

#### Hub workspace UI
`client/src/components/Dashboard.jsx` is the authenticated shell coordinating navigation and workspace state. `client/src/components/Sidebar.jsx` presents the project list/navigation; `client/src/components/Viewport.jsx` hosts the selected project admin page, expected to accept `?embed=1`. `client/src/components/Overview.jsx` provides the no-selection or hub-level view. The iframe is an explicit isolation boundary: ADMIN-LINK does not own embedded module UI or its internals.

#### Agent and operational data
`server/agent.js` provides the backend agent integration used by `client/src/components/AgentChat.jsx`. `server/rates.js` supplies related rate/usage or request-control data for that service. Agent interaction remains server-mediated, protecting credentials and external-provider calls from the browser. The agent-specific architecture is further documented in `agent/ARCHITECTURE.md`.

#### Runtime and deployment shape
The frontend is a Vite/React application (`client/package.json`, `client/vite.config.js`); the backend is a Node.js service (`server/package.json`, `server/index.js`). In development, Vite proxies `/api` to the API service. Production process orchestration is represented by `ecosystem.config.js`; reverse-proxy integration is documented/configured through `docs/nginx-admin-link.conf`. Environment secrets belong outside the repository, with `.env.example` defining expected inputs.

Main entry points: [`client/src/components/Dashboard.jsx`](https://github.com/laboffuture/admin-dash/blob/main/client/src/components/Dashboard.jsx) (Workspace shell), [`server/app.js`](https://github.com/laboffuture/admin-dash/blob/main/server/app.js) (API composition), [`client/src/App.jsx`](https://github.com/laboffuture/admin-dash/blob/main/client/src/App.jsx) (Hub app), [`server/poller.js`](https://github.com/laboffuture/admin-dash/blob/main/server/poller.js) (Reachability poller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser client"]
  node_client_entry["React entry<br/>Vite bootstrap<br/>[main.jsx]"]
  node_client_app["Hub app<br/>React root<br/>[App.jsx]"]
  node_login["Login gate<br/>React component<br/>[Login.jsx]"]
  node_api_client["API contract<br/>client API<br/>[api.js]"]
  node_dashboard["Workspace shell<br/>React component<br/>[Dashboard.jsx]"]
  node_sidebar["Project navigation<br/>React component<br/>[Sidebar.jsx]"]
  node_overview["Hub overview<br/>React component<br/>[Overview.jsx]"]
  node_viewport["Embedded viewport<br/>iframe host<br/>[Viewport.jsx]"]
  node_hub_messages["Status event hook<br/>React hook<br/>[useHubMessages.js]"]
  node_agent_chat["Agent chat<br/>React component<br/>[AgentChat.jsx]"]
end

subgraph group_api["Node API service"]
  node_server_entry["Server startup<br/>Node entry<br/>[index.js]"]
  node_api_app["API composition<br/>HTTP app<br/>[app.js]"]
  node_auth["Password auth<br/>auth service<br/>[auth.js]"]
  node_registry["Project registry<br/>registry service<br/>[registry.js]"]
  node_poller["Reachability poller<br/>health service<br/>[poller.js]"]
  node_agent["Agent integration<br/>backend integration<br/>[agent.js]"]
  node_rates["Rate and usage data<br/>service data<br/>[rates.js]"]
end

subgraph group_external["Independent systems"]
  node_remote_modules{{"Remote project admin pages<br/>independent deployments"}}
  node_agent_provider{{"Agent provider<br/>external service"}}
end

node_project_data["Registered projects<br/>runtime registry<br/>[projects.json]"]

node_client_entry -->|"mounts"| node_client_app
node_client_app -->|"gates access"| node_login
node_client_app -->|"authenticated workspace"| node_dashboard
node_login -->|"auth request"| node_api_client
node_dashboard -->|"renders"| node_sidebar
node_dashboard -->|"renders"| node_overview
node_dashboard -->|"selects project"| node_viewport
node_dashboard -->|"subscribes"| node_hub_messages
node_dashboard -->|"renders"| node_agent_chat
node_api_client -->|"/api"| node_api_app
node_server_entry -->|"starts"| node_api_app
node_api_app -->|"authenticates"| node_auth
node_api_app -->|"serves catalog"| node_registry
node_api_app -->|"serves status"| node_poller
node_api_app -->|"mediates chat"| node_agent
node_registry -->|"loads"| node_project_data
node_poller -->|"gets targets"| node_registry
node_poller -.->|"checks reachability"| node_remote_modules
node_viewport -->|"iframe ?embed=1"| node_remote_modules
node_agent -->|"uses"| node_rates
node_agent -.->|"server-side calls"| node_agent_provider

click node_client_entry "https://github.com/laboffuture/admin-dash/blob/main/client/src/main.jsx"
click node_client_app "https://github.com/laboffuture/admin-dash/blob/main/client/src/App.jsx"
click node_login "https://github.com/laboffuture/admin-dash/blob/main/client/src/components/Login.jsx"
click node_api_client "https://github.com/laboffuture/admin-dash/blob/main/client/src/api.js"
click node_dashboard "https://github.com/laboffuture/admin-dash/blob/main/client/src/components/Dashboard.jsx"
click node_sidebar "https://github.com/laboffuture/admin-dash/blob/main/client/src/components/Sidebar.jsx"
click node_overview "https://github.com/laboffuture/admin-dash/blob/main/client/src/components/Overview.jsx"
click node_viewport "https://github.com/laboffuture/admin-dash/blob/main/client/src/components/Viewport.jsx"
click node_hub_messages "https://github.com/laboffuture/admin-dash/blob/main/client/src/hooks/useHubMessages.js"
click node_agent_chat "https://github.com/laboffuture/admin-dash/blob/main/client/src/components/AgentChat.jsx"
click node_server_entry "https://github.com/laboffuture/admin-dash/blob/main/server/index.js"
click node_api_app "https://github.com/laboffuture/admin-dash/blob/main/server/app.js"
click node_auth "https://github.com/laboffuture/admin-dash/blob/main/server/auth.js"
click node_registry "https://github.com/laboffuture/admin-dash/blob/main/server/registry.js"
click node_poller "https://github.com/laboffuture/admin-dash/blob/main/server/poller.js"
click node_agent "https://github.com/laboffuture/admin-dash/blob/main/server/agent.js"
click node_rates "https://github.com/laboffuture/admin-dash/blob/main/server/rates.js"
click node_project_data "https://github.com/laboffuture/admin-dash/blob/main/projects.json"

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_client_entry,node_client_app,node_login,node_api_client,node_dashboard,node_sidebar,node_overview,node_viewport,node_hub_messages,node_agent_chat toneBlue
class node_server_entry,node_api_app,node_auth,node_registry,node_poller,node_agent,node_rates toneAmber
class node_remote_modules,node_agent_provider toneMint
class node_project_data toneNeutral
```

## Components

### Browser client

- [React entry](https://github.com/laboffuture/admin-dash/blob/main/client/src/main.jsx): Vite bootstrap · `client/src/main.jsx`
- [Hub app](https://github.com/laboffuture/admin-dash/blob/main/client/src/App.jsx): React root · `client/src/App.jsx`
- [Login gate](https://github.com/laboffuture/admin-dash/blob/main/client/src/components/Login.jsx): React component · `client/src/components/Login.jsx`
- [API contract](https://github.com/laboffuture/admin-dash/blob/main/client/src/api.js): client API · `client/src/api.js`
- [Workspace shell](https://github.com/laboffuture/admin-dash/blob/main/client/src/components/Dashboard.jsx): React component · `client/src/components/Dashboard.jsx`
- [Project navigation](https://github.com/laboffuture/admin-dash/blob/main/client/src/components/Sidebar.jsx): React component · `client/src/components/Sidebar.jsx`
- [Hub overview](https://github.com/laboffuture/admin-dash/blob/main/client/src/components/Overview.jsx): React component · `client/src/components/Overview.jsx`
- [Embedded viewport](https://github.com/laboffuture/admin-dash/blob/main/client/src/components/Viewport.jsx): iframe host · Hosts the selected project admin page with embed mode. · `client/src/components/Viewport.jsx`
- [Status event hook](https://github.com/laboffuture/admin-dash/blob/main/client/src/hooks/useHubMessages.js): React hook · `client/src/hooks/useHubMessages.js`
- [Agent chat](https://github.com/laboffuture/admin-dash/blob/main/client/src/components/AgentChat.jsx): React component · `client/src/components/AgentChat.jsx`

### Node API service

- [Server startup](https://github.com/laboffuture/admin-dash/blob/main/server/index.js): Node entry · `server/index.js`
- [API composition](https://github.com/laboffuture/admin-dash/blob/main/server/app.js): HTTP app · Exposes the protected /api surface. · `server/app.js`
- [Password auth](https://github.com/laboffuture/admin-dash/blob/main/server/auth.js): auth service · Verifies the single ADMIN_PASSWORD credential. · `server/auth.js`
- [Project registry](https://github.com/laboffuture/admin-dash/blob/main/server/registry.js): registry service · Loads and validates registered project targets. · `server/registry.js`
- [Reachability poller](https://github.com/laboffuture/admin-dash/blob/main/server/poller.js): health service · Checks module URLs server-side to avoid browser cross-origin checks. · `server/poller.js`
- [Agent integration](https://github.com/laboffuture/admin-dash/blob/main/server/agent.js): backend integration · Mediates provider calls and protects credentials. · `server/agent.js`
- [Rate and usage data](https://github.com/laboffuture/admin-dash/blob/main/server/rates.js): service data · `server/rates.js`

### Independent systems

- **Remote project admin pages**: independent deployments · Externally deployed modules, not imported hub code.
- **Agent provider**: external service

### Other components

- [Registered projects](https://github.com/laboffuture/admin-dash/blob/main/projects.json): runtime registry · Primary data-driven extension boundary for projects. · `projects.json`

## Connections

- React entry → Hub app: mounts
- Hub app → Login gate: gates access
- Hub app → Workspace shell: authenticated workspace
- Login gate → API contract: auth request
- Workspace shell → Project navigation: renders
- Workspace shell → Hub overview: renders
- Workspace shell → Embedded viewport: selects project
- Workspace shell → Status event hook: subscribes
- Workspace shell → Agent chat: renders
- API contract → API composition: /api
- Server startup → API composition: starts
- API composition → Password auth: authenticates
- API composition → Project registry: serves catalog
- API composition → Reachability poller: serves status
- API composition → Agent integration: mediates chat
- Project registry → Registered projects: loads
- Reachability poller → Project registry: gets targets
- Reachability poller → Remote project admin pages: checks reachability
- Embedded viewport → Remote project admin pages: iframe ?embed=1
- Agent integration → Rate and usage data: uses
- Agent integration → Agent provider: server-side calls