Skip to content

Commit 313969c

Browse files
kkorotkovkkorotkov
committed
Add glossary with auto-update logic
1 parent 08f19d6 commit 313969c

7 files changed

Lines changed: 787 additions & 0 deletions

File tree

‎.github/workflows/glossary-monitor.yml‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
name: Glossary Monitor
2+
3+
# Runs every Monday at 09:00 UTC and can be triggered manually.
4+
# On each run it scans all labs64.io-* repositories for documentation,
5+
# uses an LLM via OpenRouter to propose glossary updates, and opens a PR
6+
# only when the glossary content actually changes.
7+
8+
on:
9+
schedule:
10+
- cron: '0 9 * * 1' # Every Monday 09:00 UTC
11+
workflow_dispatch: # Manual trigger from the Actions tab
12+
13+
permissions:
14+
contents: write
15+
pull-requests: write
16+
17+
jobs:
18+
update-glossary:
19+
name: Scan repos and update GLOSSARY.md
20+
runs-on: ubuntu-latest
21+
timeout-minutes: 15
22+
23+
steps:
24+
- name: Checkout labs64.io-docs
25+
uses: actions/checkout@v4
26+
27+
- name: Set up Python 3.12
28+
uses: actions/setup-python@v5
29+
with:
30+
python-version: '3.12'
31+
cache: pip
32+
cache-dependency-path: scripts/requirements.txt
33+
34+
- name: Install dependencies
35+
run: pip install -r scripts/requirements.txt
36+
37+
- name: Run glossary monitor
38+
id: monitor
39+
env:
40+
# GH_TOKEN must have read access to all labs64.io-* repos (public + private).
41+
# Use a classic PAT or a fine-grained token with "Contents: Read" on all target repos.
42+
# Store it as a repository secret named GH_TOKEN.
43+
GH_TOKEN: ${{ secrets.GH_TOKEN }}
44+
OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
45+
run: python scripts/glossary_monitor.py
46+
47+
# Commit the state file when at least one repo had new commits since the
48+
# last run. This advances the SHA baseline so the next run does not
49+
# re-examine commits that were already evaluated — even if those commits
50+
# produced no glossary change. Skipped entirely when nothing changed.
51+
- name: Commit state file
52+
if: steps.monitor.outputs.state_changed == 'true'
53+
run: |
54+
git config user.name "github-actions[bot]"
55+
git config user.email "github-actions[bot]@users.noreply.github.com"
56+
git add scripts/.glossary-state.json
57+
git commit -m "chore: update glossary monitor state [skip ci]"
58+
git push
59+
60+
# Open (or update) a PR only when the glossary content actually changed.
61+
- name: Open Pull Request
62+
if: steps.monitor.outputs.glossary_changed == 'true'
63+
uses: peter-evans/create-pull-request@v6
64+
with:
65+
token: ${{ secrets.GH_TOKEN }}
66+
branch: glossary/auto-update
67+
base: main
68+
title: "docs: glossary update from weekly repository scan"
69+
body: |
70+
This PR was opened automatically by the **Glossary Monitor** workflow.
71+
72+
### What changed
73+
The job scanned all `labs64.io-*` repositories and used an LLM via OpenRouter to:
74+
- Add terms present in documentation but missing from the glossary
75+
- Improve definitions that were incomplete or outdated
76+
- Expand the *Context* column for terms that appear in additional modules
77+
78+
### Review checklist
79+
- [ ] New terms are accurate and belong in a human-readable glossary
80+
- [ ] Definitions are concise and free of code symbols
81+
- [ ] Context column lists the correct module(s)
82+
- [ ] Alphabetical order is preserved
83+
84+
> Generated by [`scripts/glossary_monitor.py`](../blob/main/scripts/glossary_monitor.py)
85+
commit-message: "docs: auto-update GLOSSARY.md via glossary-monitor"
86+
labels: |
87+
documentation
88+
automated
89+
# Re-use the same branch so repeated runs update the existing PR
90+
# instead of opening a new one each time.
91+
delete-branch: false
92+
add-paths: |
93+
GLOSSARY.md
94+
scripts/.glossary-auto.md

‎GLOSSARY-MANUAL.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Glossary — Manual Entries
2+
3+
Maintain this file by hand. Add, edit, or remove rows directly.
4+
5+
The monitor script (`scripts/glossary_monitor.py`) merges these entries with
6+
AI-generated ones and writes the combined, alphabetically sorted result to
7+
`GLOSSARY.md`. Do not edit `GLOSSARY.md` directly — it is regenerated on every run.
8+
9+
If a term exists in both this file and the AI-generated source, this file wins.
10+
11+
**Context column:** use plain module names (e.g. `Checkout, Payment Gateway`).
12+
The build script resolves them to links automatically.
13+
14+
| Term | Context | Definition |
15+
|------|---------|------------|
16+
| **JWT (JSON Web Token)** | Checkout, Payment Gateway | A signed token used to authenticate and authorize API requests. The tenant identity is derived from the JWT payload. |

‎GLOSSARY.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
<!-- Generated by scripts/glossary_monitor.py — do not edit directly.
2+
To add or change terms manually, edit GLOSSARY-MANUAL.md instead. -->
3+
4+
# Glossary
5+
6+
| Term | Context | Definition |
7+
|------|---------|------------|
8+
| **Apache Kafka** | [AuditFlow](https://github.com/Labs64/labs64.io/blob/main/_posts/2025-05-26-labs64io-ecosystem-under-the-hood.md), Message Broker | A distributed event streaming platform used for high-throughput, fault-tolerant asynchronous messaging between microservices. |
9+
| **API Gateway** | [API Gateway](https://github.com/Labs64/labs64.io/blob/main/_posts/2025-05-26-labs64io-ecosystem-under-the-hood.md), [AuditFlow](https://github.com/Labs64/labs64.io-auditflow), [Payment Gateway](https://github.com/Labs64/labs64.io-docs/blob/main/payment-gateway/readme.md#general-architecture) | A reverse proxy that routes client requests to appropriate microservices, handling cross-cutting concerns like authentication, SSL termination, and rate limiting. |
10+
| **API-first approach** | [Payment Gateway](https://github.com/Labs64/labs64.io-docs/blob/main/payment-gateway/readme.md#integration-messaging) | Design methodology where the OpenAPI specification is written first and server stubs are generated from it, ensuring the contract drives implementation. |
11+
| **Auth Proxy** | [API Gateway](https://github.com/Labs64/labs64.io/blob/main/_posts/2025-08-07-securing-microservices-with-keycloak-and-traefik-authproxy.md), [AuditFlow](https://github.com/Labs64/labs64.io-auditflow) | A specialized service that centralizes authentication and authorization for multiple microservices using Traefik's forwardAuth middleware. |
12+
| **BI (Billing Info)** | [Checkout](https://github.com/Labs64/labs64.io-docs/blob/main/checkout/checkout-service-spec-en.md#11-core-domain-entities) | Buyer information required for invoicing and legal compliance (name, address, email, VAT ID, etc.). Captured at checkout time and stored as part of the CTX. |
13+
| **Business Telemetry** | [AuditFlow](https://github.com/Labs64/labs64.io-auditflow) | An abstraction layer for emitting business-level metrics and events, decoupled from OpenTelemetry implementation details. |
14+
| **Buyer** | [Checkout](https://github.com/Labs64/labs64.io-docs/blob/main/checkout/checkout-service-spec-en.md#12-actors) | The end customer who interacts with the Checkout UI and completes the payment process. May be anonymous from the Checkout service perspective. |
15+
| **CDN (Content Delivery Network)** | [API Gateway](https://github.com/Labs64/labs64.io/blob/main/_posts/2025-05-29-labs64io-ecosystem-architecture.md) | A geographically distributed cache that serves static assets from edge locations to reduce latency. |
16+
| **Condition Evaluator** | [AuditFlow](https://github.com/Labs64/labs64.io-auditflow) | A component that evaluates pipeline conditions against audit events using operators like equals, contains, regex, and range comparisons. |
17+
| **CTX (Checkout Transaction)** | [Checkout](https://github.com/Labs64/labs64.io-docs/blob/main/checkout/checkout-service-spec-en.md#11-core-domain-entities) | A financial object created when the buyer initiates payment. Stores a reference to the originating PO, BI, SI, selected payment method, and current status (PENDING / FAILED / CANCELED / COMPLETED). |
18+
| **Custom Resource (CR)** | [API Gateway](https://github.com/Labs64/labs64.io/blob/main/_posts/2025-08-01-configuring-traefik-middleware-for-kubernetes.md), Traefik | A Kubernetes API extension that allows users to define custom resource types; Traefik uses CRs like Middleware and IngressRoute for traffic management. |
19+
| **Custom Resource Definition (CRD)** | [API Gateway](https://github.com/Labs64/labs64.io/blob/main/_posts/2025-08-01-configuring-traefik-middleware-for-kubernetes.md), Traefik | A Kubernetes resource that defines a new custom resource type, enabling the Kubernetes API to recognize and validate custom resources like Traefik's Middleware. |
20+
| **Dead-Letter Queue (DLQ)** | [AuditFlow](https://github.com/Labs64/labs64.io-auditflow) | A RabbitMQ queue that captures messages failing repeated processing attempts for later inspection. |
21+
| **Distributed Tracing** | [API Gateway](https://github.com/Labs64/labs64.io/blob/main/_posts/2025-05-26-labs64io-ecosystem-under-the-hood.md), [AuditFlow](https://github.com/Labs64/labs64.io-auditflow), [Payment Gateway](https://github.com/Labs64/labs64.io-docs/blob/main/payment-gateway/readme.md) | A method for tracking requests as they flow through multiple microservices, enabling latency analysis and debugging across service boundaries. |
22+
| **Dynamic PO Flow** | [Checkout](https://github.com/Labs64/labs64.io-docs/blob/main/checkout/checkout-service-spec-en.md#2-dynamic-po-flow-cart-driven) | A checkout scenario where the Purchase Order is created on-the-fly by an external shop or cart at the moment the buyer clicks "Checkout", and the buyer is then redirected to the Checkout UI. |
23+
| **FastAPI** | [AuditFlow](https://github.com/Labs64/labs64.io-auditflow/blob/main/AGENTS.md) | A modern, fast Python web framework used to build the AuditFlow transformer and sink services with automatic OpenAPI documentation. |
24+
| **forwardAuth** | [API Gateway](https://github.com/Labs64/labs64.io/blob/main/_posts/2025-08-01-configuring-traefik-middleware-for-kubernetes.md), [AuditFlow](https://github.com/Labs64/labs64.io-auditflow) | A Traefik middleware that delegates authentication decisions to an external service by forwarding request headers. |
25+
| **Grafana** | [API Gateway](https://github.com/Labs64/labs64.io/blob/main/_posts/2025-07-07-pod-metrics-in-kubernetes.md), [AuditFlow](https://github.com/Labs64/labs64.io-auditflow), [Payment Gateway](https://github.com/Labs64/labs64.io-docs/blob/main/payment-gateway/readme.md) | An open-source platform for creating dashboards and visualizing metrics, logs, and traces from Prometheus, Loki, and Tempo. |
26+
| **Grafana Alloy** | [AuditFlow](https://github.com/Labs64/labs64.io-auditflow/blob/main/AGENTS.md) | A vendor-neutral observability collector that gathers metrics, logs, and traces for forwarding to backends like Prometheus, Loki, and Tempo. |
27+
| **Grafana Tempo** | [AuditFlow](https://github.com/Labs64/labs64.io-auditflow/blob/main/AGENTS.md) | A distributed tracing backend that stores and queries traces, integrated with Grafana for visualization. |
28+
| **Helm Chart** | [Payment Gateway](https://github.com/Labs64/labs64.io/blob/main/_posts/2025-06-11-helm-chart-repository.md), [AuditFlow](https://github.com/Labs64/labs64.io-auditflow) | A package of pre-configured Kubernetes manifests that defines how a service and its dependencies are deployed. |
29+
| **Helm Library Chart (chart-libs)** | [Payment Gateway](https://github.com/Labs64/labs64.io-docs/blob/main/payment-gateway/readme.md), [AuditFlow](https://github.com/Labs64/labs64.io-auditflow) | A reusable Helm chart containing shared templates and helper functions used by service charts to eliminate duplication. |
30+
| **Helm Override Strategy** | [Payment Gateway](https://github.com/Labs64/labs64.io/blob/main/_posts/2025-06-24-helm-charts-override-strategy.md), [AuditFlow](https://github.com/Labs64/labs64.io-auditflow) | A configuration pattern that separates environment-specific values into a dedicated overrides directory mirroring the charts structure. |
31+
| **helm-docs** | [Payment Gateway](https://github.com/Labs64/labs64.io/blob/main/_posts/2025-06-16-helm-chart-documentation.md), [AuditFlow](https://github.com/Labs64/labs64.io-auditflow) | A tool that automatically generates README.md documentation from a Helm chart's values.yaml and Chart.yaml. |
32+
| **helm-schema** | [Payment Gateway](https://github.com/Labs64/labs64.io/blob/main/_posts/2025-06-16-helm-chart-documentation.md), [AuditFlow](https://github.com/Labs64/labs64.io-auditflow) | A Helm plugin that generates JSON Schema from values.yaml for IDE validation and auto-completion. |
33+
| **Horizontal Pod Autoscaler (HPA)** | [Payment Gateway](https://github.com/Labs64/labs64.io/blob/main/_posts/2025-07-07-pod-metrics-in-kubernetes.md), [AuditFlow](https://github.com/Labs64/labs64.io-auditflow) | A Kubernetes controller that automatically scales the number of pod replicas based on observed CPU utilization or custom metrics from the Metrics Server. |
34+
| **Identity Provider** | [API Gateway](https://github.com/Labs64/labs64.io/blob/main/_posts/2025-05-29-labs64io-ecosystem-architecture.md), [AuditFlow](https://github.com/Labs64/labs64.io-auditflow) | A dedicated service that handles user authentication, token issuance, and identity management (e.g., Keycloak). |
35+
| **Ingress** | [API Gateway](https://github.com/Labs64/labs64.io/blob/main/_posts/2025-06-07-kubernetes-cheatsheet.md) | A Kubernetes resource that manages external HTTP/HTTPS access to services within the cluster, typically via an ingress controller like Traefik. |
36+
| **IngressRoute** | [API Gateway](https://github.com/Labs64/labs64.io/blob/main/_posts/2025-08-01-configuring-traefik-middleware-for-kubernetes.md), [AuditFlow](https://github.com/Labs64/labs64.io-auditflow) | A Traefik custom resource that defines routing rules and middleware chains for incoming HTTP traffic. |
37+
| **ISO-4217** | [Checkout](https://github.com/Labs64/labs64.io-docs/blob/main/checkout/checkout-service-spec-en.md#14-money-rules) | The international standard defining three-letter currency codes (e.g. USD, EUR) used to express the currency of a Purchase Order. |
38+
| **justfile / just** | [Payment Gateway](https://github.com/Labs64/labs64.io-docs/blob/main/payment-gateway/readme.md), [AuditFlow](https://github.com/Labs64/labs64.io-auditflow) | A command runner that defines project tasks in a cross-platform, self-documenting justfile. |
39+
| **JWKS (JSON Web Key Set)** | [API Gateway](https://github.com/Labs64/labs64.io/blob/main/_posts/2025-08-07-securing-microservices-with-keycloak-and-traefik-authproxy.md), [AuditFlow](https://github.com/Labs64/labs64.io-auditflow) | A set of public keys published by an identity provider (e.g., Keycloak) used to verify JWT signatures. |
40+
| **JWT (JSON Web Token)** | [Checkout](https://github.com/Labs64/labs64.io-docs/blob/main/checkout/checkout-service-spec-en.md), [Payment Gateway](https://github.com/Labs64/labs64.io-docs/blob/main/payment-gateway/readme.md) | A signed token used to authenticate and authorize API requests. The tenant identity is derived from the JWT payload. |
41+
| **Keycloak** | [API Gateway](https://github.com/Labs64/labs64.io/blob/main/_posts/2025-08-07-securing-microservices-with-keycloak-and-traefik-authproxy.md), [AuditFlow](https://github.com/Labs64/labs64.io-auditflow) | An open-source identity and access management server used for authentication, authorization, and token management. |
42+
| **KeyResolver** | API Gateway | A Spring Cloud Gateway component that extracts a unique identifier (e.g., IP address, user ID) from requests for rate limiting. |

0 commit comments

Comments
 (0)