# paglaai/paglaspace architecture

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

- Interactive diagram: https://gitdiagram.com/paglaai/paglaspace
- Repository: https://github.com/paglaai/paglaspace

## Overview

PaglaAI.space is both a public static site for its local-first AI ecosystem and an operational system that monitors the site and dispatches maintenance jobs. The main user flow is visitor → Pages-hosted site content; separate API and scheduled-worker flows support health checks and job dispatch. The graph includes the documented site and operations capabilities, while limiting implementation-level links to relationships visible in excerpts or README. Unsampled pages, job definitions, and workflow wiring are represented only at supported directory or registry paths.

Main entry points: [`worker/index.js`](https://github.com/paglaai/paglaspace/blob/main/worker/index.js) (Operations Worker), [`ops/jobs.json`](https://github.com/paglaai/paglaspace/blob/main/ops/jobs.json) (Job registry), [`functions/api/jobs/[name]/run.js`](https://github.com/paglaai/paglaspace/blob/main/functions/api/jobs/%5Bname%5D/run.js) (Run-job endpoint), [`ops/run-job.mjs`](https://github.com/paglaai/paglaspace/blob/main/ops/run-job.mjs) (Job runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_site["Public site"]
  node_home["Home page<br/>[index.html]"]
  node_site_sections["Site sections"]
  node_shared_assets["Shared assets"]
  node_site_runtime["Site interactions<br/>[main.js]"]
end

subgraph group_pages_api["Pages API"]
  node_middleware["Request middleware<br/>[_middleware.js]"]
  node_api_utils["API utilities<br/>[_utils.mjs]"]
  node_health_api["Health endpoint<br/>[health.js]"]
  node_jobs_api["Jobs endpoint<br/>[jobs.js]"]
  node_run_api["Run-job endpoint<br/>[run.js]"]
end

subgraph group_ops["Operations jobs"]
  node_registry["Job registry<br/>[jobs.json]"]
  node_job_runner["Job runner<br/>[run-job.mjs]"]
  node_job_listing["Job listing<br/>[list-jobs.mjs]"]
  node_job_scripts["Operations scripts"]
  node_url_helper["URL formatter<br/>[urls.mjs]"]
  node_sitemap_generator["Sitemap generator<br/>[sitemap-gen.mjs]"]
end

subgraph group_worker["Worker services"]
  node_ops_worker["Operations Worker<br/>[index.js]"]
end

node_visitor(("Visitor"))
node_site_origin(("Deployed site"))
node_github_actions(("GitHub Actions"))
node_search_engines(("Search engines"))

node_visitor -->|"requests"| node_home
node_visitor -->|"browses"| node_site_sections
node_home -.->|"uses"| node_shared_assets
node_site_sections -.->|"uses"| node_shared_assets
node_site_runtime -.->|"enhances"| node_shared_assets
node_middleware -.->|"wraps requests"| node_health_api
node_health_api -->|"uses helpers"| node_api_utils
node_jobs_api -->|"uses helpers"| node_api_utils
node_run_api -->|"uses helpers"| node_api_utils
node_jobs_api -->|"reads jobs"| node_registry
node_run_api -->|"selects job"| node_registry
node_run_api -->|"dispatches job"| node_github_actions
node_job_listing -->|"loads registry"| node_job_runner
node_job_runner -->|"reads jobs"| node_registry
node_job_runner -.->|"runs commands"| node_job_scripts
node_sitemap_generator -->|"formats URLs"| node_url_helper
node_ops_worker -->|"loads jobs"| node_registry
node_ops_worker -->|"probes site"| node_site_origin
node_ops_worker -->|"dispatches jobs"| node_github_actions
node_ops_worker -->|"pings sitemap"| node_search_engines

click node_home "https://github.com/paglaai/paglaspace/blob/main/index.html"
click node_site_sections "https://github.com/paglaai/paglaspace/tree/main/products"
click node_shared_assets "https://github.com/paglaai/paglaspace/tree/main/assets"
click node_site_runtime "https://github.com/paglaai/paglaspace/blob/main/assets/js/main.js"
click node_middleware "https://github.com/paglaai/paglaspace/blob/main/functions/_middleware.js"
click node_api_utils "https://github.com/paglaai/paglaspace/blob/main/functions/_utils.mjs"
click node_health_api "https://github.com/paglaai/paglaspace/blob/main/functions/api/health.js"
click node_jobs_api "https://github.com/paglaai/paglaspace/blob/main/functions/api/jobs.js"
click node_run_api "https://github.com/paglaai/paglaspace/blob/main/functions/api/jobs/%5Bname%5D/run.js"
click node_registry "https://github.com/paglaai/paglaspace/blob/main/ops/jobs.json"
click node_job_runner "https://github.com/paglaai/paglaspace/blob/main/ops/run-job.mjs"
click node_job_listing "https://github.com/paglaai/paglaspace/blob/main/ops/list-jobs.mjs"
click node_job_scripts "https://github.com/paglaai/paglaspace/tree/main/ops/scripts"
click node_url_helper "https://github.com/paglaai/paglaspace/blob/main/ops/lib/urls.mjs"
click node_sitemap_generator "https://github.com/paglaai/paglaspace/blob/main/ops/scripts/sitemap-gen.mjs"
click node_ops_worker "https://github.com/paglaai/paglaspace/blob/main/worker/index.js"

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_home,node_site_sections,node_shared_assets,node_site_runtime toneBlue
class node_middleware,node_api_utils,node_health_api,node_jobs_api,node_run_api toneAmber
class node_registry,node_job_runner,node_job_listing,node_job_scripts,node_url_helper,node_sitemap_generator toneMint
class node_ops_worker toneRose
class node_visitor,node_site_origin,node_github_actions,node_search_engines toneIndigo
```

## Components

### Public site

- [Home page](https://github.com/paglaai/paglaspace/blob/main/index.html): `index.html`
- [Site sections](https://github.com/paglaai/paglaspace/tree/main/products): `products`
- [Shared assets](https://github.com/paglaai/paglaspace/tree/main/assets): `assets`
- [Site interactions](https://github.com/paglaai/paglaspace/blob/main/assets/js/main.js): `assets/js/main.js`

### Pages API

- [Request middleware](https://github.com/paglaai/paglaspace/blob/main/functions/_middleware.js): `functions/_middleware.js`
- [API utilities](https://github.com/paglaai/paglaspace/blob/main/functions/_utils.mjs): `functions/_utils.mjs`
- [Health endpoint](https://github.com/paglaai/paglaspace/blob/main/functions/api/health.js): `functions/api/health.js`
- [Jobs endpoint](https://github.com/paglaai/paglaspace/blob/main/functions/api/jobs.js): `functions/api/jobs.js`
- [Run-job endpoint](https://github.com/paglaai/paglaspace/blob/main/functions/api/jobs/%5Bname%5D/run.js): `functions/api/jobs/[name]/run.js`

### Operations jobs

- [Job registry](https://github.com/paglaai/paglaspace/blob/main/ops/jobs.json): `ops/jobs.json`
- [Job runner](https://github.com/paglaai/paglaspace/blob/main/ops/run-job.mjs): `ops/run-job.mjs`
- [Job listing](https://github.com/paglaai/paglaspace/blob/main/ops/list-jobs.mjs): `ops/list-jobs.mjs`
- [Operations scripts](https://github.com/paglaai/paglaspace/tree/main/ops/scripts): `ops/scripts`
- [URL formatter](https://github.com/paglaai/paglaspace/blob/main/ops/lib/urls.mjs): `ops/lib/urls.mjs`
- [Sitemap generator](https://github.com/paglaai/paglaspace/blob/main/ops/scripts/sitemap-gen.mjs): `ops/scripts/sitemap-gen.mjs`

### Worker services

- [Operations Worker](https://github.com/paglaai/paglaspace/blob/main/worker/index.js): `worker/index.js`

### Other components

- **Visitor**
- **Deployed site**
- **GitHub Actions**
- **Search engines**

## Connections

- Visitor → Home page: requests (evidence: `README.md`)
- Visitor → Site sections: browses (evidence: `README.md`)
- Home page → Shared assets: uses
- Site sections → Shared assets: uses
- Site interactions → Shared assets: enhances
- Request middleware → Health endpoint: wraps requests
- Health endpoint → API utilities: uses helpers (evidence: `functions/api/health.js`)
- Jobs endpoint → API utilities: uses helpers (evidence: `functions/api/jobs.js`)
- Run-job endpoint → API utilities: uses helpers (evidence: `functions/api/jobs/[name]/run.js`)
- Jobs endpoint → Job registry: reads jobs (evidence: `functions/api/jobs.js`)
- Run-job endpoint → Job registry: selects job (evidence: `functions/api/jobs/[name]/run.js`)
- Run-job endpoint → GitHub Actions: dispatches job (evidence: `functions/api/jobs/[name]/run.js`)
- Job listing → Job runner: loads registry (evidence: `ops/list-jobs.mjs`)
- Job runner → Job registry: reads jobs (evidence: `README.md`)
- Job runner → Operations scripts: runs commands
- Sitemap generator → URL formatter: formats URLs (evidence: `ops/scripts/sitemap-gen.mjs`)
- Operations Worker → Job registry: loads jobs (evidence: `worker/index.js`)
- Operations Worker → Deployed site: probes site (evidence: `worker/index.js`)
- Operations Worker → GitHub Actions: dispatches jobs (evidence: `worker/index.js`)
- Operations Worker → Search engines: pings sitemap (evidence: `worker/index.js`)
