# mahadi-rsio/pagex architecture

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

- Interactive diagram: https://gitdiagram.com/mahadi-rsio/pagex
- Repository: https://github.com/mahadi-rsio/pagex

## Overview

PageX is a multi-tenant static-site hosting platform. The main workflow is a developer using the CLI to authenticate, initialize a project, build and validate site files, then prepare a deployment, upload blobs, and commit it. The console exposes project, deployment, and account operations; the blob server delivers hosted content, while worker code supports background cleanup and provisioning. CLI deployment calls are excerpted; several server-side connections are inferred from the product structure and are shown as unverified. The README excerpt describes publishing the blob server, not the full runtime architecture.

Main entry points: [`cli/src/utils/deployHandler.ts`](https://github.com/mahadi-rsio/pagex/blob/master/cli/src/utils/deployHandler.ts) (Deploy handler), [`cli/src/api/deployApi.ts`](https://github.com/mahadi-rsio/pagex/blob/master/cli/src/api/deployApi.ts) (Deploy API client), [`services/worker/internal/worker/consumer.go`](https://github.com/mahadi-rsio/pagex/blob/master/services/worker/internal/worker/consumer.go) (Worker runtime), [`services/console/src/components/console/views/ProjectDetailView.tsx`](https://github.com/mahadi-rsio/pagex/blob/master/services/console/src/components/console/views/ProjectDetailView.tsx) (Console UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and deployment"]
  node_cli_entry["CLI entry<br/>[index.ts]"]
  node_cli_commands["Commands<br/>[index.ts]"]
  node_cli_auth["Device login<br/>[deviceAuth.ts]"]
  node_cli_session[("Session store<br/>[session.ts]")]
  node_cli_build["Build runner<br/>[buildHandler.ts]"]
  node_cli_deploy["Deploy handler<br/>[deployHandler.ts]"]
  node_cli_manifest["Manifest validation"]
  node_cli_deploy_api["Deploy API client<br/>[deployApi.ts]"]
  node_api_client["Authenticated API client<br/>[client.ts]"]
end

subgraph group_console["Console and API"]
  node_auth_service["Auth service"]
  node_console_ui["Console UI"]
  node_deploy_routes["Deploy endpoints<br/>[route.ts]"]
  node_deploy_service["Deployment service<br/>[deploy.service.ts]"]
  node_project_routes["Project endpoints<br/>[route.ts]"]
  node_project_service["Project service<br/>[page.service.ts]"]
  node_usage_service["Usage services<br/>[usage.service.ts]"]
  node_usage_ingest["Usage ingestion"]
  node_database[("Application database<br/>[schema.ts]")]
end

subgraph group_delivery["Hosting and delivery"]
  node_blob_server["Blob server<br/>[handler.go]"]
  node_blob_storage[("Object storage<br/>[minio.ts]")]
end

subgraph group_operations["Background operations"]
  node_worker["Worker runtime<br/>[consumer.go]"]
  node_cleanup["Deployment cleanup<br/>[deployment_gc.go]"]
  node_provision["Cloud provisioning<br/>[provision.go]"]
  node_queue["Job queue<br/>[queue.go]"]
end

node_developer(("Developer"))
node_site_visitor(("Site visitor"))

node_developer -->|"runs commands"| node_cli_entry
node_cli_entry -->|"registers"| node_cli_commands
node_cli_auth -->|"requests authorization"| node_auth_service
node_cli_auth -->|"saves token"| node_cli_session
node_cli_session -->|"checks session"| node_auth_service
node_cli_deploy -->|"validates files"| node_cli_manifest
node_cli_deploy -->|"prepares deployment"| node_cli_deploy_api
node_cli_deploy -->|"requests upload URLs"| node_cli_deploy_api
node_cli_deploy -->|"uploads blobs"| node_cli_deploy_api
node_cli_deploy -->|"commits deployment"| node_cli_deploy_api
node_cli_deploy_api -->|"sends API requests"| node_api_client
node_api_client -->|"reads token"| node_cli_session
node_cli_deploy -.->|"runs project build"| node_cli_build
node_developer -.->|"manages projects"| node_console_ui
node_console_ui -.->|"requests project data"| node_project_routes
node_console_ui -.->|"requests deployments"| node_deploy_routes
node_project_routes -.->|"delegates project work"| node_project_service
node_deploy_routes -.->|"delegates deployment work"| node_deploy_service
node_deploy_service -.->|"stores deployment blobs"| node_blob_storage
node_project_service -.->|"persists project data"| node_database
node_usage_ingest -.->|"records usage"| node_usage_service
node_site_visitor -.->|"requests site content"| node_blob_server
node_blob_server -.->|"fetches blobs"| node_blob_storage
node_worker -.->|"consumes jobs"| node_queue
node_worker -.->|"runs cleanup"| node_cleanup
node_worker -.->|"provisions hosting"| node_provision

click node_cli_entry "https://github.com/mahadi-rsio/pagex/blob/master/cli/src/index.ts"
click node_cli_commands "https://github.com/mahadi-rsio/pagex/blob/master/cli/src/commands/index.ts"
click node_cli_auth "https://github.com/mahadi-rsio/pagex/blob/master/cli/src/auth/deviceAuth.ts"
click node_cli_session "https://github.com/mahadi-rsio/pagex/blob/master/cli/src/utils/session.ts"
click node_cli_build "https://github.com/mahadi-rsio/pagex/blob/master/cli/src/utils/buildHandler.ts"
click node_cli_deploy "https://github.com/mahadi-rsio/pagex/blob/master/cli/src/utils/deployHandler.ts"
click node_cli_manifest "https://github.com/mahadi-rsio/pagex/blob/master/cli/src/utils/validateManifest.ts"
click node_cli_deploy_api "https://github.com/mahadi-rsio/pagex/blob/master/cli/src/api/deployApi.ts"
click node_api_client "https://github.com/mahadi-rsio/pagex/blob/master/cli/src/api/client.ts"
click node_console_ui "https://github.com/mahadi-rsio/pagex/blob/master/services/console/src/components/console/views/ProjectDetailView.tsx"
click node_deploy_routes "https://github.com/mahadi-rsio/pagex/blob/master/services/console/src/app/api/deploy/prepare/route.ts"
click node_deploy_service "https://github.com/mahadi-rsio/pagex/blob/master/services/console/src/features/deployments/deploy.service.ts"
click node_project_routes "https://github.com/mahadi-rsio/pagex/blob/master/services/console/src/app/api/pages/route.ts"
click node_project_service "https://github.com/mahadi-rsio/pagex/blob/master/services/console/src/features/projects/page.service.ts"
click node_usage_service "https://github.com/mahadi-rsio/pagex/blob/master/services/console/src/features/usage/usage.service.ts"
click node_usage_ingest "https://github.com/mahadi-rsio/pagex/blob/master/services/console/src/features/usage/usage-ingest.service.ts"
click node_database "https://github.com/mahadi-rsio/pagex/blob/master/services/console/src/db/schema.ts"
click node_blob_server "https://github.com/mahadi-rsio/pagex/blob/master/services/blob-server/src/handler.go"
click node_blob_storage "https://github.com/mahadi-rsio/pagex/blob/master/services/console/src/server/api/infrastructure/storage/minio.ts"
click node_worker "https://github.com/mahadi-rsio/pagex/blob/master/services/worker/internal/worker/consumer.go"
click node_cleanup "https://github.com/mahadi-rsio/pagex/blob/master/services/worker/internal/cleanup/deployment_gc.go"
click node_provision "https://github.com/mahadi-rsio/pagex/blob/master/services/worker/internal/cloudflare/provision.go"
click node_queue "https://github.com/mahadi-rsio/pagex/blob/master/services/worker/internal/cloudflare/queue.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_cli_entry,node_cli_commands,node_cli_auth,node_cli_session,node_cli_build,node_cli_deploy,node_cli_manifest,node_cli_deploy_api,node_api_client toneBlue
class node_auth_service,node_console_ui,node_deploy_routes,node_deploy_service,node_project_routes,node_project_service,node_usage_service,node_usage_ingest,node_database toneAmber
class node_blob_server,node_blob_storage toneMint
class node_worker,node_cleanup,node_provision,node_queue toneRose
class node_developer,node_site_visitor toneIndigo
```

## Components

### CLI and deployment

- [CLI entry](https://github.com/mahadi-rsio/pagex/blob/master/cli/src/index.ts): `cli/src/index.ts`
- [Commands](https://github.com/mahadi-rsio/pagex/blob/master/cli/src/commands/index.ts): `cli/src/commands/index.ts`
- [Device login](https://github.com/mahadi-rsio/pagex/blob/master/cli/src/auth/deviceAuth.ts): `cli/src/auth/deviceAuth.ts`
- [Session store](https://github.com/mahadi-rsio/pagex/blob/master/cli/src/utils/session.ts): `cli/src/utils/session.ts`
- [Build runner](https://github.com/mahadi-rsio/pagex/blob/master/cli/src/utils/buildHandler.ts): `cli/src/utils/buildHandler.ts`
- [Deploy handler](https://github.com/mahadi-rsio/pagex/blob/master/cli/src/utils/deployHandler.ts): `cli/src/utils/deployHandler.ts`
- [Manifest validation](https://github.com/mahadi-rsio/pagex/blob/master/cli/src/utils/validateManifest.ts): `cli/src/utils/validateManifest.ts`
- [Deploy API client](https://github.com/mahadi-rsio/pagex/blob/master/cli/src/api/deployApi.ts): `cli/src/api/deployApi.ts`
- [Authenticated API client](https://github.com/mahadi-rsio/pagex/blob/master/cli/src/api/client.ts): `cli/src/api/client.ts`

### Console and API

- **Auth service**
- [Console UI](https://github.com/mahadi-rsio/pagex/blob/master/services/console/src/components/console/views/ProjectDetailView.tsx): `services/console/src/components/console/views/ProjectDetailView.tsx`
- [Deploy endpoints](https://github.com/mahadi-rsio/pagex/blob/master/services/console/src/app/api/deploy/prepare/route.ts): `services/console/src/app/api/deploy/prepare/route.ts`
- [Deployment service](https://github.com/mahadi-rsio/pagex/blob/master/services/console/src/features/deployments/deploy.service.ts): `services/console/src/features/deployments/deploy.service.ts`
- [Project endpoints](https://github.com/mahadi-rsio/pagex/blob/master/services/console/src/app/api/pages/route.ts): `services/console/src/app/api/pages/route.ts`
- [Project service](https://github.com/mahadi-rsio/pagex/blob/master/services/console/src/features/projects/page.service.ts): `services/console/src/features/projects/page.service.ts`
- [Usage services](https://github.com/mahadi-rsio/pagex/blob/master/services/console/src/features/usage/usage.service.ts): `services/console/src/features/usage/usage.service.ts`
- [Usage ingestion](https://github.com/mahadi-rsio/pagex/blob/master/services/console/src/features/usage/usage-ingest.service.ts): `services/console/src/features/usage/usage-ingest.service.ts`
- [Application database](https://github.com/mahadi-rsio/pagex/blob/master/services/console/src/db/schema.ts): `services/console/src/db/schema.ts`

### Hosting and delivery

- [Blob server](https://github.com/mahadi-rsio/pagex/blob/master/services/blob-server/src/handler.go): `services/blob-server/src/handler.go`
- [Object storage](https://github.com/mahadi-rsio/pagex/blob/master/services/console/src/server/api/infrastructure/storage/minio.ts): `services/console/src/server/api/infrastructure/storage/minio.ts`

### Background operations

- [Worker runtime](https://github.com/mahadi-rsio/pagex/blob/master/services/worker/internal/worker/consumer.go): `services/worker/internal/worker/consumer.go`
- [Deployment cleanup](https://github.com/mahadi-rsio/pagex/blob/master/services/worker/internal/cleanup/deployment_gc.go): `services/worker/internal/cleanup/deployment_gc.go`
- [Cloud provisioning](https://github.com/mahadi-rsio/pagex/blob/master/services/worker/internal/cloudflare/provision.go): `services/worker/internal/cloudflare/provision.go`
- [Job queue](https://github.com/mahadi-rsio/pagex/blob/master/services/worker/internal/cloudflare/queue.go): `services/worker/internal/cloudflare/queue.go`

### Other components

- **Developer**
- **Site visitor**

## Connections

- Developer → CLI entry: runs commands (evidence: `cli/src/index.ts`)
- CLI entry → Commands: registers (evidence: `cli/src/index.ts`)
- Device login → Auth service: requests authorization (evidence: `cli/src/auth/deviceAuth.ts`)
- Device login → Session store: saves token (evidence: `cli/src/auth/deviceAuth.ts`)
- Session store → Auth service: checks session (evidence: `cli/src/utils/session.ts`)
- Deploy handler → Manifest validation: validates files (evidence: `cli/src/utils/deployHandler.ts`)
- Deploy handler → Deploy API client: prepares deployment (evidence: `cli/src/utils/deployHandler.ts`)
- Deploy handler → Deploy API client: requests upload URLs (evidence: `cli/src/utils/deployHandler.ts`)
- Deploy handler → Deploy API client: uploads blobs (evidence: `cli/src/utils/deployHandler.ts`)
- Deploy handler → Deploy API client: commits deployment (evidence: `cli/src/utils/deployHandler.ts`)
- Deploy API client → Authenticated API client: sends API requests (evidence: `cli/src/api/deployApi.ts`)
- Authenticated API client → Session store: reads token (evidence: `cli/src/api/client.ts`)
- Deploy handler → Build runner: runs project build
- Developer → Console UI: manages projects
- Console UI → Project endpoints: requests project data
- Console UI → Deploy endpoints: requests deployments
- Project endpoints → Project service: delegates project work
- Deploy endpoints → Deployment service: delegates deployment work
- Deployment service → Object storage: stores deployment blobs
- Project service → Application database: persists project data
- Usage ingestion → Usage services: records usage
- Site visitor → Blob server: requests site content
- Blob server → Object storage: fetches blobs
- Worker runtime → Job queue: consumes jobs
- Worker runtime → Deployment cleanup: runs cleanup
- Worker runtime → Cloud provisioning: provisions hosting
