# ziro-os/pkgs architecture

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

- Interactive diagram: https://gitdiagram.com/ziro-os/pkgs
- Repository: https://github.com/ziro-os/pkgs

## Overview

This repository is Ziro OS’s official plugin catalog and a separately published WAF ruleset. The user workflow is to use `ziroctl` to discover and enable a plugin, or update gateway WAF rules; the README documents signed catalogs and host-side verification. The graph shows the documented capabilities and trust/distribution boundary. No source excerpts were available, so relationships rely on the README; implementation-level calls and internal runtime layers cannot be established.

Main entry points: [`catalog.pub`](https://github.com/ziro-os/pkgs/blob/main/catalog.pub) (Catalog public key), [`modules/s3-ziro/manifest.json`](https://github.com/ziro-os/pkgs/blob/main/modules/s3-ziro/manifest.json) (S3 storage), [`modules/rclone-ziro/manifest.json`](https://github.com/ziro-os/pkgs/blob/main/modules/rclone-ziro/manifest.json) (rclone), [`waf/zirogate-crs/rules.json`](https://github.com/ziro-os/pkgs/blob/main/waf/zirogate-crs/rules.json) (WAF rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_plugins["Plugins"]
  node_plugin_catalog["Plugin catalog"]
  node_s3["S3 storage<br/>[manifest.json]"]
  node_cloudflared["Cloudflare Tunnel<br/>[manifest.json]"]
  node_tailscale["Tailscale<br/>[manifest.json]"]
  node_rclone["rclone<br/>[manifest.json]"]
end

subgraph group_trust["Catalog trust"]
  node_catalog_key["Catalog public key<br/>[catalog.pub]"]
  node_published_plugins["Published plugin catalog"]
end

subgraph group_waf["WAF rules"]
  node_gateway["Ziro gateway"]
  node_waf_rules["WAF rules<br/>[rules.json]"]
  node_published_waf["Published WAF catalog"]
end

node_operator(("Operator"))
node_ziroctl["ziroctl"]
node_garage["Garage service"]
node_backup["Backup operation"]

node_operator -->|"runs commands"| node_ziroctl
node_ziroctl -->|"searches and fetches"| node_published_plugins
node_published_plugins -->|"serves signed index"| node_ziroctl
node_catalog_key -->|"signing key"| node_published_plugins
node_ziroctl -->|"enables plugin"| node_s3
node_ziroctl -->|"enables plugin"| node_cloudflared
node_ziroctl -->|"enables plugin"| node_tailscale
node_ziroctl -->|"enables plugin"| node_rclone
node_s3 -->|"runs as"| node_garage
node_operator -->|"creates backup"| node_backup
node_backup -->|"uses remote"| node_rclone
node_operator -->|"requests WAF update"| node_ziroctl
node_ziroctl -->|"fetches rules"| node_published_waf
node_published_waf -->|"publishes rules"| node_waf_rules
node_catalog_key -->|"signing key"| node_published_waf
node_gateway -->|"checks for updates"| node_published_waf
node_gateway -->|"validates and installs"| node_waf_rules

click node_plugin_catalog "https://github.com/ziro-os/pkgs/tree/main/modules"
click node_s3 "https://github.com/ziro-os/pkgs/blob/main/modules/s3-ziro/manifest.json"
click node_cloudflared "https://github.com/ziro-os/pkgs/blob/main/modules/cloudflared/manifest.json"
click node_tailscale "https://github.com/ziro-os/pkgs/blob/main/modules/tailscale/manifest.json"
click node_rclone "https://github.com/ziro-os/pkgs/blob/main/modules/rclone-ziro/manifest.json"
click node_catalog_key "https://github.com/ziro-os/pkgs/blob/main/catalog.pub"
click node_waf_rules "https://github.com/ziro-os/pkgs/blob/main/waf/zirogate-crs/rules.json"

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_plugin_catalog,node_s3,node_cloudflared,node_tailscale,node_rclone toneBlue
class node_catalog_key,node_published_plugins toneAmber
class node_gateway,node_waf_rules,node_published_waf toneMint
class node_operator,node_ziroctl,node_garage,node_backup toneIndigo
```

## Components

### Plugins

- [Plugin catalog](https://github.com/ziro-os/pkgs/tree/main/modules): `modules`
- [S3 storage](https://github.com/ziro-os/pkgs/blob/main/modules/s3-ziro/manifest.json): `modules/s3-ziro/manifest.json`
- [Cloudflare Tunnel](https://github.com/ziro-os/pkgs/blob/main/modules/cloudflared/manifest.json): `modules/cloudflared/manifest.json`
- [Tailscale](https://github.com/ziro-os/pkgs/blob/main/modules/tailscale/manifest.json): `modules/tailscale/manifest.json`
- [rclone](https://github.com/ziro-os/pkgs/blob/main/modules/rclone-ziro/manifest.json): `modules/rclone-ziro/manifest.json`

### Catalog trust

- [Catalog public key](https://github.com/ziro-os/pkgs/blob/main/catalog.pub): `catalog.pub`
- **Published plugin catalog**

### WAF rules

- **Ziro gateway**
- [WAF rules](https://github.com/ziro-os/pkgs/blob/main/waf/zirogate-crs/rules.json): `waf/zirogate-crs/rules.json`
- **Published WAF catalog**

### Other components

- **Operator**
- **ziroctl**
- **Garage service**
- **Backup operation**

## Connections

- Operator → ziroctl: runs commands (evidence: `README.md`)
- ziroctl → Published plugin catalog: searches and fetches (evidence: `README.md`)
- Published plugin catalog → ziroctl: serves signed index (evidence: `README.md`)
- Catalog public key → Published plugin catalog: signing key (evidence: `README.md`)
- ziroctl → S3 storage: enables plugin (evidence: `README.md`)
- ziroctl → Cloudflare Tunnel: enables plugin (evidence: `README.md`)
- ziroctl → Tailscale: enables plugin (evidence: `README.md`)
- ziroctl → rclone: enables plugin (evidence: `README.md`)
- S3 storage → Garage service: runs as (evidence: `README.md`)
- Operator → Backup operation: creates backup (evidence: `README.md`)
- Backup operation → rclone: uses remote (evidence: `README.md`)
- Operator → ziroctl: requests WAF update (evidence: `README.md`)
- ziroctl → Published WAF catalog: fetches rules (evidence: `README.md`)
- Published WAF catalog → WAF rules: publishes rules (evidence: `README.md`)
- Catalog public key → Published WAF catalog: signing key (evidence: `README.md`)
- Ziro gateway → Published WAF catalog: checks for updates (evidence: `README.md`)
- Ziro gateway → WAF rules: validates and installs (evidence: `README.md`)