architecture-example

A living architecture repo that auto-generates documentation from your services' own /help endpoints. Each service exposes a canonical, machine-readable /help response describing its fields, actions, response shapes, and errors. A GitHub Action fetches every registered /help, validates it against the canonical envelope, and regenerates Mermaid diagrams and JSON payload samples automatically.

The idea: your API docs never drift from reality because the APIs describe themselves, and this repo is the flattener that renders them into one place.

Based on the /help endpoint convention by Chris Kluis.

How it works

1. services.jsonc — a registry listing each service and its /help endpoint URLs.
2. scripts/regenerate.mjs — a zero-dependency Node 20 script that fetches every URL, strict-checks the response against the canonical /help envelope, and pipes the result through three renderers.
3. Renderers write three kinds of output:
   • diagrams/ — per-service Mermaid docs (sequence diagrams, state machines, field tables)
   • payloads/ — .jsonc request/response/error samples per endpoint
   • This README's generated section (between the GENERATED markers below)
4. GitHub Action — triggers on repository_dispatch (fired by source repos after a successful deploy), workflow_dispatch (manual), and a daily cron as a safety net.

Non-conforming /help responses don't fail the run — they render a drift warning page so you can see what needs fixing.

The canonical /help envelope

Every conforming /help response returns:

{
  "endpoint": "POST /api/audit",
  "description": "What this endpoint does...",
  "fields": [
    { "name": "url", "type": "url", "required": true, "validation": "...", "example": "https://example.com" }
  ],
  "actions": [
    { "action": "audit", "method": "POST", "href": "/api/audit", "example_body": { "url": "https://example.com" } },
    { "action": "show", "method": "GET", "href_template": "/api/audit/{id}" }
  ],
  "response": {
    "accepted": { "status": 202, "fields": [...] },
    "result": { "statuses": [{ "status": "pending", "fields": [...] }, { "status": "completed", "fields": [...] }] },
    "errors": [{ "status": 422, "description": "..." }]
  },
  "relations": [],
  "_links": { "self": "/api/audit/help", "endpoint": "/api/audit" }
}

Errors carry _hint (a plain-language recovery instruction) and _links.help (a pointer back to the help endpoint) so LLM agents can recover from failures without documentation:

{
  "error": "Validation failed.",
  "_hint": "The url field is required. See the help link for field requirements.",
  "_links": { "help": "/api/audit/help" }
}

For the full spec including the security model (auth-gated /help, role-filtered actions, rate limiting), see the canonical articles.

Running locally

node scripts/regenerate.mjs            # live run
node scripts/regenerate.mjs --dry-run  # fetch + parse but don't write

The script auto-loads .env.local and .env files. Bearer tokens for auth-gated /help endpoints are read from HELP_BEARER_<SERVICE_NAME_UPPERCASE> env vars. Missing tokens skip that endpoint with a warning — they never fail the run.

Wiring up source repos

Each source repo needs a workflow that fires a repository_dispatch to this repo after a successful deploy. Use workflow_run to chain off your deploy workflow:

# .github/workflows/notify-architecture.yml
name: Notify architecture
on:
  workflow_run:
    workflows: ["Deploy"]  # must match your deploy workflow's name
    types: [completed]
    branches: [main]
jobs:
  dispatch:
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    runs-on: ubuntu-latest
    steps:
      - name: Fire repository_dispatch
        run: |
          curl -X POST \
            -H "Authorization: Bearer ${{ secrets.ARCH_DISPATCH_TOKEN }}" \
            -H "Accept: application/vnd.github+json" \
            https://api.github.com/repos/your-org/architecture-example/dispatches \
            -d '{"event_type":"service-updated","client_payload":{"repo":"${{ github.repository }}","sha":"${{ github.event.workflow_run.head_sha }}"}}'

For Vercel-deployed services, use deployment_status instead of workflow_run — Vercel posts deployment statuses to GitHub natively:

on:
  deployment_status:
jobs:
  dispatch:
    if: >-
      github.event.deployment_status.state == 'success' &&
      github.event.deployment.environment == 'Production'
    # ... same curl step

Adapting this for your own projects

1. Fork or clone this repo.
2. Edit services.jsonc — replace the example services with your own.
3. Add /help endpoints to your services following the canonical envelope.
4. Set bearer tokens as GitHub Actions secrets if any /help endpoints are auth-gated.
5. Add the notify workflow to each source repo.
6. Push — the Action regenerates everything.

The scripts are generic and require no modification. The registry is the only file you edit.

Regenerated: example output

System overview

flowchart LR
  renderer_service["✅ renderer-service<br/><small>Node/Express on Fly.io</small>"]
  audit_api["✅ audit-api<br/><small>PHP Laravel</small>"]
  dashboard["— dashboard<br/><small>Next.js on Vercel</small>"]

  renderer_service --> audit_api
  audit_api --> dashboard

Loading

Services

Service	Runtime	Status	/help endpoints	Diagram
renderer-service	Node/Express on Fly.io	✅ conforming	2	diagram
audit-api	PHP Laravel	✅ conforming	1	diagram
dashboard	Next.js on Vercel	— frontend	N/A	diagram

See services.jsonc to add or edit the registry, and scripts/regenerate.mjs for the rebuild entry point.