Architecture¶

Overview¶

docs.example.com (hub — single Cloudflare Pages project)
  |
  +-- /                     landing page
  +-- /project-a/           project-a docs
  +-- /project-b/           project-b docs
  +-- /project-c/           project-c docs

Protected by Cloudflare Access (email allowlist)
Hub repo builds and deploys all docs in one Pages project
Per-repo CI triggers a hub rebuild via repository_dispatch

The repository_dispatch pattern keeps source-repo workflows small: they notify the hub, and the hub performs the consolidated build and deploy.

Resource Graph¶

The Terraform configuration creates the following resources:

1. Hub Pages Project — Cloudflare Pages project with a custom domain, serving the landing page and all repo docs as subdirectories
2. DNS CNAME Record — Points the custom domain to the *.pages.dev subdomain
3. Zero Trust Access Group — Defines allowed users by email address
4. Access Application + Policy — Single application protecting the hub domain, enforcing the access group
5. CI API Token — Scoped to Cloudflare Pages Write for GitHub Actions deployments

Module: docs-site¶

The modules/docs-site module encapsulates the Pages project pattern:

• cloudflare_pages_project — Creates the Pages project
• cloudflare_pages_domain — Attaches the custom domain
• cloudflare_dns_record — Creates the CNAME record

Currently used only for the hub project.

Consolidated Build¶

The scripts/build-all-docs.sh script assembles all documentation:

1. Builds the hub landing page with Zensical
2. Clones (or copies locally) each repo listed in var.sites
3. Builds each repo's docs with Zensical
4. Copies built output into hub/site/<name>/
5. The resulting hub/site/ directory is deployed as a single unit

State Management¶

Terraform state is stored locally (terraform.tfstate). The state file and terraform.tfvars are gitignored to prevent secret leakage. For team use, migrate to a remote backend (S3, Terraform Cloud, etc.).

Authentication Flow¶

terraform.tfvars
  -> cloudflare_api_token
    -> Provider authentication
      -> Resource CRUD operations

CI token (output)
  -> GitHub Actions secret (hub repo)
    -> wrangler pages deploy

DOCS_DISPATCH_TOKEN (source repos)
  -> repository_dispatch to hub repo
    -> consolidated hub build