# r0073d-l053r/proxmate architecture

> Architecture diagram of the GitHub repository r0073d-l053r/proxmate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/r0073d-l053r/proxmate
- Repository: https://github.com/r0073d-l053r/proxmate

## Overview

ProxMate is an invite-only, multi-tenant Proxmox cloud dashboard. Tenants redeem invites, authenticate, provision and manage isolated VMs or containers, then access them through browser consoles; admins configure the cluster and operate tenants, placement, backups, and monitoring. The graph follows the documented product capabilities and sampled route/service calls; several unsampled subsystems are represented only at their existing directory paths, so uncertain internal wiring is omitted.

Main entry points: [`frontend/src/app/(dashboard)`](https://github.com/r0073d-l053r/proxmate/tree/main/frontend/src/app/(dashboard)) (Dashboard UI), [`backend/src/routes/admin.routes.ts`](https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/routes/admin.routes.ts) (Admin routes), [`backend/src/services/proxmox.service.ts`](https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/services/proxmox.service.ts) (Proxmox adapter), [`backend/src/routes/auth.routes.ts`](https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/routes/auth.routes.ts) (Auth routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Tenant experience"]
  node_web["Dashboard UI"]
  node_api["Frontend API client<br/>[api.ts]"]
end

subgraph group_identity["Identity and access"]
  node_invites["Invites and quotas<br/>[invite.service.ts]"]
  node_authroutes["Auth routes<br/>[auth.routes.ts]"]
  node_authsvc["Authentication<br/>[auth.service.ts]"]
  node_mfa["MFA and SSO"]
  node_access["Access windows<br/>[access.service.ts]"]
end

subgraph group_compute["Compute lifecycle"]
  node_vms["VM routes<br/>[vm.routes.ts]"]
  node_vmservice["VM lifecycle<br/>[vm.service.ts]"]
  node_templates["Templates and images"]
  node_scheduler["Placement scheduler"]
  node_console["Browser consoles<br/>[console.routes.ts]"]
  node_ide["Browser IDE<br/>[ide.service.ts]"]
  node_shares["VM sharing"]
  node_backup["MateStates backups"]
end

subgraph group_operations["Cluster operations"]
  node_prox["Proxmox adapter<br/>[proxmox.service.ts]"]
  node_cluster["Cluster operations"]
  node_admin["Admin routes<br/>[admin.routes.ts]"]
  node_monitor["Monitoring and kiosk"]
  node_audit["Audit trail<br/>[audit.service.ts]"]
end

subgraph group_platform["Backend platform"]
  node_app["Express application<br/>[app.ts]"]
  node_db[("Application database<br/>[prisma.ts]")]
end

node_tenant(("Tenant"))
node_pve["Proxmox cluster"]
node_mail["Mail service"]

node_tenant -->|"uses"| node_web
node_web -->|"requests"| node_api
node_api -->|"calls API"| node_app
node_app -->|"mounts routes"| node_authroutes
node_app -->|"mounts routes"| node_vms
node_app -->|"mounts routes"| node_admin
node_authroutes -->|"creates sessions"| node_authsvc
node_authroutes -->|"redeems invites"| node_invites
node_authroutes -->|"checks factors"| node_mfa
node_authsvc -->|"checks expiry"| node_access
node_authsvc -->|"reads/writes sessions"| node_db
node_invites -->|"stores quotas"| node_db
node_vms -->|"manages guests"| node_vmservice
node_vms -->|"creates backups"| node_backup
node_vms -->|"records actions"| node_audit
node_templates -->|"deploys guests"| node_vmservice
node_vmservice -->|"places guests"| node_scheduler
node_vmservice -->|"operates guests"| node_prox
node_scheduler -->|"queries capacity"| node_prox
node_prox -->|"calls Proxmox API"| node_pve
node_web -->|"opens console"| node_console
node_console -->|"proxies console"| node_pve
node_web -->|"opens IDE"| node_ide
node_ide -->|"provisions IDE"| node_pve
node_web -->|"manages sharing"| node_shares
node_web -->|"selects templates"| node_templates
node_admin -->|"configures balancer"| node_cluster
node_admin -->|"configures cluster"| node_prox
node_admin -->|"records changes"| node_audit
node_admin -->|"views status"| node_monitor
node_backup -->|"backs up guests"| node_prox
node_access -.->|"sends expiry notices"| node_mail

click node_web "https://github.com/r0073d-l053r/proxmate/tree/main/frontend/src/app/(dashboard)"
click node_api "https://github.com/r0073d-l053r/proxmate/blob/main/frontend/src/lib/api.ts"
click node_invites "https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/services/invite.service.ts"
click node_authroutes "https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/routes/auth.routes.ts"
click node_authsvc "https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/services/auth.service.ts"
click node_mfa "https://github.com/r0073d-l053r/proxmate/tree/main/backend/src/services"
click node_access "https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/services/access.service.ts"
click node_vms "https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/routes/vm.routes.ts"
click node_vmservice "https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/services/vm.service.ts"
click node_templates "https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/services/template.service.ts"
click node_scheduler "https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/services/scheduler.service.ts"
click node_console "https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/routes/console.routes.ts"
click node_ide "https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/services/ide.service.ts"
click node_shares "https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/services/vm-share.service.ts"
click node_backup "https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/services/matestate.service.ts"
click node_prox "https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/services/proxmox.service.ts"
click node_cluster "https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/services/cluster-balancer.service.ts"
click node_admin "https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/routes/admin.routes.ts"
click node_monitor "https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/services/live-stats.service.ts"
click node_audit "https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/services/audit.service.ts"
click node_app "https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/app.ts"
click node_db "https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/lib/prisma.ts"

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_web,node_api toneBlue
class node_invites,node_authroutes,node_authsvc,node_mfa,node_access toneAmber
class node_vms,node_vmservice,node_templates,node_scheduler,node_console,node_ide,node_shares,node_backup toneMint
class node_prox,node_cluster,node_admin,node_monitor,node_audit toneRose
class node_app,node_db,node_tenant,node_pve,node_mail toneIndigo
```

## Components

### Tenant experience

- [Dashboard UI](https://github.com/r0073d-l053r/proxmate/tree/main/frontend/src/app/(dashboard)): `frontend/src/app/(dashboard)`
- [Frontend API client](https://github.com/r0073d-l053r/proxmate/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### Identity and access

- [Invites and quotas](https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/services/invite.service.ts): `backend/src/services/invite.service.ts`
- [Auth routes](https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/routes/auth.routes.ts): `backend/src/routes/auth.routes.ts`
- [Authentication](https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/services/auth.service.ts): `backend/src/services/auth.service.ts`
- [MFA and SSO](https://github.com/r0073d-l053r/proxmate/tree/main/backend/src/services): `backend/src/services`
- [Access windows](https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/services/access.service.ts): `backend/src/services/access.service.ts`

### Compute lifecycle

- [VM routes](https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/routes/vm.routes.ts): `backend/src/routes/vm.routes.ts`
- [VM lifecycle](https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/services/vm.service.ts): `backend/src/services/vm.service.ts`
- [Templates and images](https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/services/template.service.ts): `backend/src/services/template.service.ts`
- [Placement scheduler](https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/services/scheduler.service.ts): `backend/src/services/scheduler.service.ts`
- [Browser consoles](https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/routes/console.routes.ts): `backend/src/routes/console.routes.ts`
- [Browser IDE](https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/services/ide.service.ts): `backend/src/services/ide.service.ts`
- [VM sharing](https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/services/vm-share.service.ts): `backend/src/services/vm-share.service.ts`
- [MateStates backups](https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/services/matestate.service.ts): `backend/src/services/matestate.service.ts`

### Cluster operations

- [Proxmox adapter](https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/services/proxmox.service.ts): `backend/src/services/proxmox.service.ts`
- [Cluster operations](https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/services/cluster-balancer.service.ts): `backend/src/services/cluster-balancer.service.ts`
- [Admin routes](https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/routes/admin.routes.ts): `backend/src/routes/admin.routes.ts`
- [Monitoring and kiosk](https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/services/live-stats.service.ts): `backend/src/services/live-stats.service.ts`
- [Audit trail](https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/services/audit.service.ts): `backend/src/services/audit.service.ts`

### Backend platform

- [Express application](https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/app.ts): `backend/src/app.ts`
- [Application database](https://github.com/r0073d-l053r/proxmate/blob/main/backend/src/lib/prisma.ts): `backend/src/lib/prisma.ts`

### Other components

- **Tenant**
- **Proxmox cluster**
- **Mail service**

## Connections

- Tenant → Dashboard UI: uses
- Dashboard UI → Frontend API client: requests
- Frontend API client → Express application: calls API
- Express application → Auth routes: mounts routes
- Express application → VM routes: mounts routes
- Express application → Admin routes: mounts routes
- Auth routes → Authentication: creates sessions
- Auth routes → Invites and quotas: redeems invites
- Auth routes → MFA and SSO: checks factors
- Authentication → Access windows: checks expiry
- Authentication → Application database: reads/writes sessions
- Invites and quotas → Application database: stores quotas
- VM routes → VM lifecycle: manages guests
- VM routes → MateStates backups: creates backups
- VM routes → Audit trail: records actions
- Templates and images → VM lifecycle: deploys guests
- VM lifecycle → Placement scheduler: places guests
- VM lifecycle → Proxmox adapter: operates guests
- Placement scheduler → Proxmox adapter: queries capacity
- Proxmox adapter → Proxmox cluster: calls Proxmox API
- Dashboard UI → Browser consoles: opens console
- Browser consoles → Proxmox cluster: proxies console
- Dashboard UI → Browser IDE: opens IDE
- Browser IDE → Proxmox cluster: provisions IDE
- Dashboard UI → VM sharing: manages sharing
- Dashboard UI → Templates and images: selects templates
- Admin routes → Cluster operations: configures balancer
- Admin routes → Proxmox adapter: configures cluster
- Admin routes → Audit trail: records changes
- Admin routes → Monitoring and kiosk: views status
- MateStates backups → Proxmox adapter: backs up guests
- Access windows → Mail service: sends expiry notices