# syu-cloud/su-cloud-portal-phase-1 architecture

> Architecture diagram of the GitHub repository syu-cloud/su-cloud-portal-phase-1, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/syu-cloud/su-cloud-portal-phase-1
- Repository: https://github.com/syu-cloud/su-cloud-portal-phase-1

## Overview

This repository implements a web portal for authenticated users to browse images and request, monitor, and reclaim virtual machines. The frontend calls a Django REST API; its application service validates requests and delegates catalog queries and VM reservation/reclaim policy to backend services. A worker claims queued VM records and provisions or deprovisions OpenStack resources, including Warpgate access. The README is empty, so capability coverage is based on the supplied source and index; backend URL routing and some frontend components were not sampled, and those links are omitted or marked unverified.

Main entry points: [`frontend/src/components/VmDashboard.tsx`](https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/frontend/src/components/VmDashboard.tsx) (VM dashboard), [`frontend/src/App.tsx`](https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/frontend/src/App.tsx) (App and session), [`api/services.py`](https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/api/services.py) (API application service), [`provisioning/services.py`](https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/provisioning/services.py) (Reservation and lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portal["Portal UI"]
  node_app["App and session<br/>[App.tsx]"]
  node_login["Login form<br/>[LoginForm.tsx]"]
  node_header["Portal header<br/>[PortalHeader.tsx]"]
  node_dashboard["VM dashboard<br/>[VmDashboard.tsx]"]
  node_create["VM creation panel<br/>[VmCreatePanel.tsx]"]
  node_list["VM list<br/>[VmList.tsx]"]
  node_reclaim_dialog["Reclaim confirmation"]
  node_modal["Modal dialog<br/>[ModalDialog.tsx]"]
  node_progress["Progress strip"]
  node_status["Status badge<br/>[VmStatusBadge.tsx]"]
end

subgraph group_api["API and Catalog"]
  node_auth_api["Session API client<br/>[auth.ts]"]
  node_vm_api["VM API client<br/>[vms.ts]"]
  node_catalog_api["Catalog API client<br/>[catalog.ts]"]
  node_http_client["HTTP client<br/>[client.ts]"]
  node_rest["REST views<br/>[views.py]"]
  node_app_service["API application service<br/>[services.py]"]
  node_catalog_service["Image and flavor catalog<br/>[services.py]"]
end

subgraph group_lifecycle["VM Lifecycle"]
  node_worker["Lifecycle worker<br/>[worker.py]"]
  node_provisioning["Reservation and lifecycle<br/>[services.py]"]
  node_failure_policy["Failure descriptions<br/>[failures.py]"]
end

subgraph group_integrations["Infrastructure Integrations"]
  node_os_vm["VM operations<br/>[vm.py]"]
  node_os_catalog["OpenStack catalog adapters"]
  node_warpgate["Warpgate client<br/>[__init__.py]"]
end

subgraph group_state["Lifecycle State"]
  node_records[("VM and slot records<br/>[models.py]")]
end

node_user(("Portal user"))
node_openstack{{"OpenStack"}}
node_warpgate_service{{"Warpgate service"}}

node_user -->|"uses"| node_app
node_app -->|"checks session"| node_auth_api
node_app -->|"renders"| node_login
node_app -->|"renders"| node_header
node_app -->|"renders"| node_dashboard
node_dashboard -->|"loads and updates"| node_vm_api
node_dashboard -->|"loads catalog"| node_catalog_api
node_dashboard -->|"renders"| node_create
node_dashboard -->|"renders"| node_list
node_dashboard -->|"renders"| node_progress
node_create -->|"creates VMs"| node_vm_api
node_create -->|"loads choices"| node_catalog_api
node_create -->|"uses"| node_modal
node_list -->|"loads and reclaims"| node_vm_api
node_list -->|"renders"| node_reclaim_dialog
node_list -->|"renders"| node_status
node_reclaim_dialog -->|"uses"| node_modal
node_auth_api -->|"requests"| node_http_client
node_vm_api -->|"requests"| node_http_client
node_vm_api -.->|"calls REST endpoints"| node_rest
node_catalog_api -.->|"calls REST endpoints"| node_rest
node_rest -->|"delegates"| node_app_service
node_app_service -->|"validates image; lists catalog"| node_catalog_service
node_app_service -->|"reserves; reclaims; lists"| node_provisioning
node_app_service -->|"formats VM data"| node_os_vm
node_app_service -->|"formats failures"| node_failure_policy
node_catalog_service -->|"queries images and flavor"| node_os_catalog
node_worker -->|"claims and dispatches"| node_provisioning
node_provisioning -->|"reads and updates"| node_records
node_provisioning -->|"creates and deletes VMs"| node_os_vm
node_provisioning -->|"provisions access"| node_warpgate
node_os_vm -->|"manages compute and networking"| node_openstack
node_os_catalog -.->|"queries catalog"| node_openstack
node_warpgate -->|"administers access"| node_warpgate_service

click node_app "https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/frontend/src/App.tsx"
click node_login "https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/frontend/src/components/LoginForm.tsx"
click node_header "https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/frontend/src/components/PortalHeader.tsx"
click node_dashboard "https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/frontend/src/components/VmDashboard.tsx"
click node_create "https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/frontend/src/components/VmCreatePanel.tsx"
click node_list "https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/frontend/src/components/VmList.tsx"
click node_reclaim_dialog "https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/frontend/src/components/ReclaimConfirmDialog.tsx"
click node_modal "https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/frontend/src/components/ModalDialog.tsx"
click node_progress "https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/frontend/src/components/VmProgressStrip.tsx"
click node_status "https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/frontend/src/components/VmStatusBadge.tsx"
click node_auth_api "https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/frontend/src/api/auth.ts"
click node_vm_api "https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/frontend/src/api/vms.ts"
click node_catalog_api "https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/frontend/src/api/catalog.ts"
click node_http_client "https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/frontend/src/api/client.ts"
click node_rest "https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/api/views.py"
click node_app_service "https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/api/services.py"
click node_catalog_service "https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/catalog/services.py"
click node_worker "https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/provisioning/management/commands/worker.py"
click node_provisioning "https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/provisioning/services.py"
click node_failure_policy "https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/provisioning/failures.py"
click node_os_vm "https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/osclient/vm.py"
click node_os_catalog "https://github.com/syu-cloud/su-cloud-portal-phase-1/tree/master/osclient"
click node_warpgate "https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/wgclient/__init__.py"
click node_records "https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/provisioning/models.py"

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_app,node_login,node_header,node_dashboard,node_create,node_list,node_reclaim_dialog,node_modal,node_progress,node_status,node_user toneBlue
class node_auth_api,node_vm_api,node_catalog_api,node_http_client,node_rest,node_app_service,node_catalog_service toneAmber
class node_worker,node_provisioning,node_failure_policy toneMint
class node_os_vm,node_os_catalog,node_warpgate toneRose
class node_records,node_openstack,node_warpgate_service toneIndigo
```

## Components

### Portal UI

- [App and session](https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Login form](https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/frontend/src/components/LoginForm.tsx): `frontend/src/components/LoginForm.tsx`
- [Portal header](https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/frontend/src/components/PortalHeader.tsx): `frontend/src/components/PortalHeader.tsx`
- [VM dashboard](https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/frontend/src/components/VmDashboard.tsx): `frontend/src/components/VmDashboard.tsx`
- [VM creation panel](https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/frontend/src/components/VmCreatePanel.tsx): `frontend/src/components/VmCreatePanel.tsx`
- [VM list](https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/frontend/src/components/VmList.tsx): `frontend/src/components/VmList.tsx`
- [Reclaim confirmation](https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/frontend/src/components/ReclaimConfirmDialog.tsx): `frontend/src/components/ReclaimConfirmDialog.tsx`
- [Modal dialog](https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/frontend/src/components/ModalDialog.tsx): `frontend/src/components/ModalDialog.tsx`
- [Progress strip](https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/frontend/src/components/VmProgressStrip.tsx): `frontend/src/components/VmProgressStrip.tsx`
- [Status badge](https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/frontend/src/components/VmStatusBadge.tsx): `frontend/src/components/VmStatusBadge.tsx`

### API and Catalog

- [Session API client](https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/frontend/src/api/auth.ts): `frontend/src/api/auth.ts`
- [VM API client](https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/frontend/src/api/vms.ts): `frontend/src/api/vms.ts`
- [Catalog API client](https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/frontend/src/api/catalog.ts): `frontend/src/api/catalog.ts`
- [HTTP client](https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [REST views](https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/api/views.py): `api/views.py`
- [API application service](https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/api/services.py): `api/services.py`
- [Image and flavor catalog](https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/catalog/services.py): `catalog/services.py`

### VM Lifecycle

- [Lifecycle worker](https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/provisioning/management/commands/worker.py): `provisioning/management/commands/worker.py`
- [Reservation and lifecycle](https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/provisioning/services.py): `provisioning/services.py`
- [Failure descriptions](https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/provisioning/failures.py): `provisioning/failures.py`

### Infrastructure Integrations

- [VM operations](https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/osclient/vm.py): `osclient/vm.py`
- [OpenStack catalog adapters](https://github.com/syu-cloud/su-cloud-portal-phase-1/tree/master/osclient): `osclient`
- [Warpgate client](https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/wgclient/__init__.py): `wgclient/__init__.py`

### Lifecycle State

- [VM and slot records](https://github.com/syu-cloud/su-cloud-portal-phase-1/blob/master/provisioning/models.py): `provisioning/models.py`

### Other components

- **Portal user**
- **OpenStack**
- **Warpgate service**

## Connections

- Portal user → App and session: uses
- App and session → Session API client: checks session (evidence: `frontend/src/App.tsx`)
- App and session → Login form: renders (evidence: `frontend/src/App.tsx`)
- App and session → Portal header: renders (evidence: `frontend/src/App.tsx`)
- App and session → VM dashboard: renders (evidence: `frontend/src/App.tsx`)
- VM dashboard → VM API client: loads and updates (evidence: `frontend/src/components/VmDashboard.tsx`)
- VM dashboard → Catalog API client: loads catalog (evidence: `frontend/src/components/VmDashboard.tsx`)
- VM dashboard → VM creation panel: renders (evidence: `frontend/src/components/VmDashboard.tsx`)
- VM dashboard → VM list: renders (evidence: `frontend/src/components/VmDashboard.tsx`)
- VM dashboard → Progress strip: renders (evidence: `frontend/src/components/VmDashboard.tsx`)
- VM creation panel → VM API client: creates VMs (evidence: `frontend/src/components/VmCreatePanel.tsx`)
- VM creation panel → Catalog API client: loads choices (evidence: `frontend/src/components/VmCreatePanel.tsx`)
- VM creation panel → Modal dialog: uses (evidence: `frontend/src/components/VmCreatePanel.tsx`)
- VM list → VM API client: loads and reclaims (evidence: `frontend/src/components/VmList.tsx`)
- VM list → Reclaim confirmation: renders (evidence: `frontend/src/components/VmList.tsx`)
- VM list → Status badge: renders (evidence: `frontend/src/components/VmList.tsx`)
- Reclaim confirmation → Modal dialog: uses (evidence: `frontend/src/components/ReclaimConfirmDialog.tsx`)
- Session API client → HTTP client: requests (evidence: `frontend/src/api/auth.ts`)
- VM API client → HTTP client: requests (evidence: `frontend/src/api/vms.ts`)
- VM API client → REST views: calls REST endpoints
- Catalog API client → REST views: calls REST endpoints
- REST views → API application service: delegates (evidence: `api/views.py`)
- API application service → Image and flavor catalog: validates image; lists catalog (evidence: `api/services.py`)
- API application service → Reservation and lifecycle: reserves; reclaims; lists (evidence: `api/services.py`)
- API application service → VM operations: formats VM data (evidence: `api/services.py`)
- API application service → Failure descriptions: formats failures (evidence: `api/services.py`)
- Image and flavor catalog → OpenStack catalog adapters: queries images and flavor (evidence: `catalog/services.py`)
- Lifecycle worker → Reservation and lifecycle: claims and dispatches (evidence: `provisioning/management/commands/worker.py`)
- Reservation and lifecycle → VM and slot records: reads and updates (evidence: `provisioning/services.py`)
- Reservation and lifecycle → VM operations: creates and deletes VMs (evidence: `provisioning/services.py`)
- Reservation and lifecycle → Warpgate client: provisions access (evidence: `provisioning/services.py`)
- VM operations → OpenStack: manages compute and networking (evidence: `osclient/vm.py`)
- OpenStack catalog adapters → OpenStack: queries catalog
- Warpgate client → Warpgate service: administers access (evidence: `wgclient/__init__.py`)