# aryan0dhankhar/containerlease architecture

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

- Interactive diagram: https://gitdiagram.com/aryan0dhankhar/containerlease
- Repository: https://github.com/aryan0dhankhar/containerlease

## Overview

ContainerLease is a web platform for authenticated, resource-limited Docker leases. Users sign in, configure an image and lease duration, provision a container, then inspect its status and logs; background cleanup enforces expiry. The map preserves the documented presets, snapshots, security, observability, and lifecycle capabilities. Several backend relationships are documented rather than shown in sampled implementation excerpts, so those edges cite the README; unsampled details are not inferred.

Main entry points: [`frontend/src/services/containerApi.ts`](https://github.com/aryan0dhankhar/containerlease/blob/main/frontend/src/services/containerApi.ts) (Container API client), [`backend/internal/handler`](https://github.com/aryan0dhankhar/containerlease/tree/main/backend/internal/handler) (HTTP handlers), [`frontend/src/App.tsx`](https://github.com/aryan0dhankhar/containerlease/blob/main/frontend/src/App.tsx) (App shell), [`backend/internal/worker/cleanup_worker.go`](https://github.com/aryan0dhankhar/containerlease/blob/main/backend/internal/worker/cleanup_worker.go) (Cleanup worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web interface"]
  node_react["React entry<br/>[main.tsx]"]
  node_app["App shell<br/>[App.tsx]"]
  node_home["Sign-in landing<br/>[HomePage.tsx]"]
  node_login["Login form<br/>[LoginForm.tsx]"]
  node_provisionform["Provision form"]
  node_dashboard["Command center<br/>[CommandCenter.tsx]"]
  node_logview["Log viewer<br/>[ContainerLogs.tsx]"]
  node_api["Container API client<br/>[containerApi.ts]"]
  node_types["Container types<br/>[container.ts]"]
end

subgraph group_http["HTTP and access"]
  node_server["Server bootstrap<br/>[main.go]"]
  node_handlers["HTTP handlers"]
  node_security["Auth and access control"]
end

subgraph group_services["Lease services"]
  node_authservice["Authentication service<br/>[auth_service.go]"]
  node_containerservice["Container service"]
  node_snapshots["Snapshot service"]
end

subgraph group_runtime["Runtime and state"]
  node_docker["Docker integration<br/>[client.go]"]
  node_leases["Lease repository"]
  node_containers["Container repository"]
  node_snaprepo["Snapshot repository"]
  node_redis["Redis client<br/>[client.go]"]
  node_db[("Database<br/>[db.go]")]
end

subgraph group_operations["Lifecycle and telemetry"]
  node_cleanup["Cleanup worker<br/>[cleanup_worker.go]"]
  node_observability["Metrics and tracing<br/>[metrics.go]"]
end

node_user(("Developer"))
node_dockerexternal["Docker Engine"]
node_redisexternal[("Redis")]

node_user -->|"opens"| node_home
node_react -->|"mounts"| node_app
node_app -->|"shows signed-out"| node_home
node_app -->|"shows provisioning"| node_provisionform
node_app -->|"shows dashboard"| node_dashboard
node_home -->|"renders"| node_login
node_login -->|"authenticates"| node_api
node_provisionform -->|"requests lease"| node_api
node_dashboard -->|"loads and manages"| node_api
node_logview -->|"subscribes to logs"| node_api
node_api -->|"uses types"| node_types
node_api -->|"calls HTTP API"| node_server
node_server -->|"routes requests"| node_handlers
node_server -->|"applies middleware"| node_security
node_handlers -->|"delegates provisioning"| node_containerservice
node_handlers -->|"handles snapshots"| node_snapshots
node_handlers -.->|"handles authentication"| node_authservice
node_authservice -.->|"uses user storage"| node_db
node_containerservice -->|"creates containers"| node_docker
node_containerservice -->|"stores lease"| node_leases
node_snapshots -.->|"persists snapshots"| node_snaprepo
node_leases -->|"uses Redis"| node_redis
node_docker -->|"controls"| node_dockerexternal
node_redis -->|"connects to"| node_redisexternal
node_cleanup -->|"finds expired leases"| node_leases
node_cleanup -->|"removes containers"| node_docker
node_cleanup -->|"clears lease state"| node_redis
node_handlers -.->|"emits telemetry"| node_observability

click node_react "https://github.com/aryan0dhankhar/containerlease/blob/main/frontend/src/main.tsx"
click node_app "https://github.com/aryan0dhankhar/containerlease/blob/main/frontend/src/App.tsx"
click node_home "https://github.com/aryan0dhankhar/containerlease/blob/main/frontend/src/components/HomePage.tsx"
click node_login "https://github.com/aryan0dhankhar/containerlease/blob/main/frontend/src/components/LoginForm.tsx"
click node_provisionform "https://github.com/aryan0dhankhar/containerlease/blob/main/frontend/src/components/ProvisionFormEnhanced.tsx"
click node_dashboard "https://github.com/aryan0dhankhar/containerlease/blob/main/frontend/src/components/CommandCenter.tsx"
click node_logview "https://github.com/aryan0dhankhar/containerlease/blob/main/frontend/src/components/ContainerLogs.tsx"
click node_api "https://github.com/aryan0dhankhar/containerlease/blob/main/frontend/src/services/containerApi.ts"
click node_types "https://github.com/aryan0dhankhar/containerlease/blob/main/frontend/src/types/container.ts"
click node_server "https://github.com/aryan0dhankhar/containerlease/blob/main/backend/cmd/server/main.go"
click node_handlers "https://github.com/aryan0dhankhar/containerlease/tree/main/backend/internal/handler"
click node_security "https://github.com/aryan0dhankhar/containerlease/tree/main/backend/internal/security"
click node_authservice "https://github.com/aryan0dhankhar/containerlease/blob/main/backend/internal/service/auth_service.go"
click node_containerservice "https://github.com/aryan0dhankhar/containerlease/blob/main/backend/internal/service/container_service.go"
click node_snapshots "https://github.com/aryan0dhankhar/containerlease/blob/main/backend/internal/service/snapshot_service.go"
click node_docker "https://github.com/aryan0dhankhar/containerlease/blob/main/backend/internal/infrastructure/docker/client.go"
click node_leases "https://github.com/aryan0dhankhar/containerlease/blob/main/backend/internal/repository/lease_repository.go"
click node_containers "https://github.com/aryan0dhankhar/containerlease/blob/main/backend/internal/repository/container_repository.go"
click node_snaprepo "https://github.com/aryan0dhankhar/containerlease/blob/main/backend/internal/repository/snapshot_repository.go"
click node_redis "https://github.com/aryan0dhankhar/containerlease/blob/main/backend/internal/infrastructure/redis/client.go"
click node_cleanup "https://github.com/aryan0dhankhar/containerlease/blob/main/backend/internal/worker/cleanup_worker.go"
click node_observability "https://github.com/aryan0dhankhar/containerlease/blob/main/backend/internal/observability/metrics/metrics.go"
click node_db "https://github.com/aryan0dhankhar/containerlease/blob/main/backend/pkg/database/db.go"

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_react,node_app,node_home,node_login,node_provisionform,node_dashboard,node_logview,node_api,node_types toneBlue
class node_server,node_handlers,node_security,node_redisexternal toneAmber
class node_authservice,node_containerservice,node_snapshots toneMint
class node_docker,node_leases,node_containers,node_snaprepo,node_redis,node_db toneRose
class node_cleanup,node_observability,node_user,node_dockerexternal toneIndigo
```

## Components

### Web interface

- [React entry](https://github.com/aryan0dhankhar/containerlease/blob/main/frontend/src/main.tsx): `frontend/src/main.tsx`
- [App shell](https://github.com/aryan0dhankhar/containerlease/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Sign-in landing](https://github.com/aryan0dhankhar/containerlease/blob/main/frontend/src/components/HomePage.tsx): `frontend/src/components/HomePage.tsx`
- [Login form](https://github.com/aryan0dhankhar/containerlease/blob/main/frontend/src/components/LoginForm.tsx): `frontend/src/components/LoginForm.tsx`
- [Provision form](https://github.com/aryan0dhankhar/containerlease/blob/main/frontend/src/components/ProvisionFormEnhanced.tsx): `frontend/src/components/ProvisionFormEnhanced.tsx`
- [Command center](https://github.com/aryan0dhankhar/containerlease/blob/main/frontend/src/components/CommandCenter.tsx): `frontend/src/components/CommandCenter.tsx`
- [Log viewer](https://github.com/aryan0dhankhar/containerlease/blob/main/frontend/src/components/ContainerLogs.tsx): `frontend/src/components/ContainerLogs.tsx`
- [Container API client](https://github.com/aryan0dhankhar/containerlease/blob/main/frontend/src/services/containerApi.ts): `frontend/src/services/containerApi.ts`
- [Container types](https://github.com/aryan0dhankhar/containerlease/blob/main/frontend/src/types/container.ts): `frontend/src/types/container.ts`

### HTTP and access

- [Server bootstrap](https://github.com/aryan0dhankhar/containerlease/blob/main/backend/cmd/server/main.go): `backend/cmd/server/main.go`
- [HTTP handlers](https://github.com/aryan0dhankhar/containerlease/tree/main/backend/internal/handler): `backend/internal/handler`
- [Auth and access control](https://github.com/aryan0dhankhar/containerlease/tree/main/backend/internal/security): `backend/internal/security`

### Lease services

- [Authentication service](https://github.com/aryan0dhankhar/containerlease/blob/main/backend/internal/service/auth_service.go): `backend/internal/service/auth_service.go`
- [Container service](https://github.com/aryan0dhankhar/containerlease/blob/main/backend/internal/service/container_service.go): `backend/internal/service/container_service.go`
- [Snapshot service](https://github.com/aryan0dhankhar/containerlease/blob/main/backend/internal/service/snapshot_service.go): `backend/internal/service/snapshot_service.go`

### Runtime and state

- [Docker integration](https://github.com/aryan0dhankhar/containerlease/blob/main/backend/internal/infrastructure/docker/client.go): `backend/internal/infrastructure/docker/client.go`
- [Lease repository](https://github.com/aryan0dhankhar/containerlease/blob/main/backend/internal/repository/lease_repository.go): `backend/internal/repository/lease_repository.go`
- [Container repository](https://github.com/aryan0dhankhar/containerlease/blob/main/backend/internal/repository/container_repository.go): `backend/internal/repository/container_repository.go`
- [Snapshot repository](https://github.com/aryan0dhankhar/containerlease/blob/main/backend/internal/repository/snapshot_repository.go): `backend/internal/repository/snapshot_repository.go`
- [Redis client](https://github.com/aryan0dhankhar/containerlease/blob/main/backend/internal/infrastructure/redis/client.go): `backend/internal/infrastructure/redis/client.go`
- [Database](https://github.com/aryan0dhankhar/containerlease/blob/main/backend/pkg/database/db.go): `backend/pkg/database/db.go`

### Lifecycle and telemetry

- [Cleanup worker](https://github.com/aryan0dhankhar/containerlease/blob/main/backend/internal/worker/cleanup_worker.go): `backend/internal/worker/cleanup_worker.go`
- [Metrics and tracing](https://github.com/aryan0dhankhar/containerlease/blob/main/backend/internal/observability/metrics/metrics.go): `backend/internal/observability/metrics/metrics.go`

### Other components

- **Developer**
- **Docker Engine**
- **Redis**

## Connections

- Developer → Sign-in landing: opens
- React entry → App shell: mounts (evidence: `frontend/src/main.tsx`)
- App shell → Sign-in landing: shows signed-out (evidence: `frontend/src/App.tsx`)
- App shell → Provision form: shows provisioning (evidence: `frontend/src/App.tsx`)
- App shell → Command center: shows dashboard (evidence: `frontend/src/App.tsx`)
- Sign-in landing → Login form: renders (evidence: `frontend/src/components/HomePage.tsx`)
- Login form → Container API client: authenticates (evidence: `frontend/src/components/LoginForm.tsx`)
- Provision form → Container API client: requests lease (evidence: `frontend/src/components/ProvisionFormEnhanced.tsx`)
- Command center → Container API client: loads and manages (evidence: `frontend/src/components/CommandCenter.tsx`)
- Log viewer → Container API client: subscribes to logs (evidence: `frontend/src/components/ContainerLogs.tsx`)
- Container API client → Container types: uses types (evidence: `frontend/src/services/containerApi.ts`)
- Container API client → Server bootstrap: calls HTTP API
- Server bootstrap → HTTP handlers: routes requests (evidence: `backend/cmd/server/main.go`)
- Server bootstrap → Auth and access control: applies middleware (evidence: `backend/cmd/server/main.go`)
- HTTP handlers → Container service: delegates provisioning
- HTTP handlers → Snapshot service: handles snapshots
- HTTP handlers → Authentication service: handles authentication
- Authentication service → Database: uses user storage
- Container service → Docker integration: creates containers
- Container service → Lease repository: stores lease
- Snapshot service → Snapshot repository: persists snapshots
- Lease repository → Redis client: uses Redis
- Docker integration → Docker Engine: controls
- Redis client → Redis: connects to
- Cleanup worker → Lease repository: finds expired leases
- Cleanup worker → Docker integration: removes containers
- Cleanup worker → Redis client: clears lease state
- HTTP handlers → Metrics and tracing: emits telemetry
