Initial commit

* architecture documents

Author: Alwin Mark

.github/workflows/render-plantuml.yml

@@ -0,0 +1,38 @@
+name: Render PlantUML Diagrams
+
+on:
+  push:
+    branches: [ "main" ]
+    paths:
+      - "docs/plantuml/src/*.puml"
+      - ".github/workflows/render-plantuml.yml"
+
+permissions:
+  contents: write
+
+jobs:
+  render:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Render PlantUML diagrams via Docker
+        run: |
+          docker run --rm \
+            -w /work \
+            -v "$PWD:/work" \
+            plantuml/plantuml \
+            -tsvg \
+            -o ../out \
+            doc/plantuml/src/*.puml
+
+      - name: Commit rendered diagrams
+        uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_message: "chore(docs): render PlantUML diagrams"
+          file_pattern: "doc/plantuml/out/*.svg"
+

LICENSE

@@ -0,0 +1,28 @@
+# Protopipe Frontend Platform
+
+Kubernetes-native frontend platform for SSR-based UI composition,
+artifact-driven experimentation, and contract-first development.
+
+## Architecture Documentation (arc42)
+
+This repository uses the **arc42 architecture documentation template**.
+The README serves as an index; detailed architecture documentation lives in
+dedicated chapters under `docs/arc42`.
+
+👉 **Start here:**
+- [Architecture Overview](doc/arc42/README.md)
+
+
+## Repository Structure
+
+- `services/` – runtime components (operator, composer, message bridge)
+- `packages/` – shared specs, ABIs, tooling
+- `docs/` – architecture, ADRs, diagrams
+- `deployments/` – Helm / Kustomize
+- `examples/` – reference implementations
+
+## License
+
+This project is licensed under **GPL-3.0-only**.  
+See [LICENSE](LICENSE) for details.
+

README.md

@@ -0,0 +1,39 @@
+# 0001 – Record Architecture Decisions
+
+Date: 2025-12-29
+
+## Status
+
+Accepted
+
+## Context
+
+The Protopipe Frontend Platform is a long-lived architectural system that
+must remain understandable, maintainable, and evolvable over time.
+
+Architecture decisions are frequently made implicitly during implementation
+or discussions, which leads to loss of rationale, repeated debates, and
+inconsistent implementation choices—especially in distributed and
+open-source-friendly environments.
+
+A lightweight but explicit mechanism is required to document and communicate
+architectural decisions and their consequences.
+
+## Decision
+
+We will record all significant architecture decisions using
+**Architecture Decision Records (ADRs)**.
+
+ADRs are maintained as Markdown files in the repository under `docs/adr/`
+and follow a standard structure including context, decision, and consequences.
+
+ADRs are created using the `adr-tools` workflow and are versioned together
+with the source code.
+
+## Consequences
+
+- Architecture decisions become explicit and reviewable.
+- Rationale behind decisions is preserved over time.
+- New contributors can understand architectural constraints faster.
+- Maintaining ADRs introduces a small but intentional documentation overhead.
+

doc/adr/0001-record-architecture-decisions.md

@@ -0,0 +1,35 @@
+# 0002 – Model Pages and Experiments as Kubernetes CRDs
+
+Date: 2025-12-29
+
+## Status
+
+Accepted
+
+## Context
+
+The frontend platform is Kubernetes-native and must integrate cleanly into
+cluster-level workflows, GitOps processes, and declarative configuration
+management.
+
+Pages and experiments are core architectural concepts that influence routing,
+rendering, and delivery behavior. Treating them as application-internal
+configuration would limit observability, automation, and governance.
+
+## Decision
+
+Pages and Experiments are modeled as **custom Kubernetes resources (CRDs)**.
+
+- A **Page** CRD represents the smallest deployable frontend unit.
+- An **Experiment** CRD defines assignment rules and artifact overrides.
+
+A Kubernetes Operator reconciles these resources and produces effective runtime
+configuration for the frontend composer.
+
+## Consequences
+
+- Frontend behavior becomes declarative and cluster-visible.
+- Pages and experiments integrate naturally with GitOps workflows.
+- Kubernetes becomes the single source of truth for delivery configuration.
+- Operator complexity increases and must be carefully managed and tested.
+

doc/adr/0002-model-pages-and-experiments-as-kubernetes-crds.md

@@ -0,0 +1,43 @@
+# 0003 – Introduce Render Function Artifacts as the Rendering Boundary
+
+Date: 2025-12-29
+
+## Status
+
+Accepted
+
+## Context
+
+Frontend teams must be able to work independently, using different technologies
+and release cycles, without introducing shared frontend baselines or tight
+coupling.
+
+Traditional frontend integration approaches often rely on shared runtimes,
+framework versions, or client-side composition, which does not scale well
+organizationally.
+
+A stable, testable rendering boundary is required.
+
+## Decision
+
+We introduce **Render Function Artifacts (RFAs)** as the primary rendering
+boundary.
+
+An RFA exposes a pure rendering contract:
+
+```
+render(data, context)->html(+meta)
+```
+
+RFAs are:
+- Technology-agnostic internally
+- Independently buildable and testable
+- Executed server-side by the frontend composer
+
+## Consequences
+
+- Teams can choose internal frontend technologies freely.
+- Rendering becomes deterministic and testable.
+- Shared frontend baselines are avoided.
+- Server-side execution requires isolation and resource control.
+

doc/adr/0003-introduce-render-function-artifacts-as-the-rendering-boundary.md

@@ -0,0 +1,31 @@
+# 0004 – Use Artifact-based Experiments Instead of Feature Toggles in Product Code
+
+Date: 2025-12-29
+
+## Status
+
+Accepted
+
+## Context
+
+Feature toggles embedded in product code often lead to long-lived conditional
+logic, increased complexity, and incomplete cleanup after experiments end.
+
+The platform is designed around experiments as first-class delivery mechanisms
+and supports routing at the artifact level.
+
+## Decision
+
+Experiments are implemented by **routing to different artifact implementations**
+rather than toggling behavior inside product code.
+
+Snapshot artifacts built from feature branches can be referenced directly by
+experiments and promoted or discarded without modifying merged code.
+
+## Consequences
+
+- Product code remains clean and toggle-free.
+- Definition of Done is reached at merge time.
+- Experiments become reproducible and auditable.
+- Artifact lifecycle management (retention, cleanup) becomes necessary.
+

doc/adr/0004-use-artifact-based-experiments-instead-of-feature-toggles-in-product-code.md

@@ -0,0 +1,33 @@
+# 0005 – Keep Metrics in Prometheus; Avoid Counters in CRD Status
+
+Date: 2025-12-29
+
+## Status
+
+Accepted
+
+## Context
+
+Kubernetes CRD status fields are designed to represent reconciliation state and
+conditions, not high-frequency or time-series metrics.
+
+Embedding counters or metrics into CRD status would increase API server load,
+complicate reconciliation logic, and blur responsibility boundaries.
+
+## Decision
+
+Operational metrics such as request counts, cache hits, and latencies are
+exported exclusively via **Prometheus metrics**.
+
+CRD status fields are limited to:
+- Effective configuration
+- Resolution results
+- Conditions and error states
+
+## Consequences
+
+- Clear separation between control-plane state and telemetry.
+- Better scalability and observability.
+- Metrics analysis relies on external tooling (Prometheus/Grafana).
+- CRD status remains stable and predictable.
+

doc/adr/0005-keep-metrics-in-prometheus-avoid-counters-in-crd-status.md

@@ -0,0 +1,34 @@
+# 0006 – Adopt Docs-as-Code with arc42 Chapters and PlantUML Diagrams
+
+Date: 2025-12-29
+
+## Status
+
+Accepted
+
+## Context
+
+Architecture documentation must remain accurate, reviewable, and closely aligned
+with the implemented system.
+
+External documentation systems or slide-based approaches tend to drift from
+reality and are rarely kept up to date.
+
+## Decision
+
+Architecture documentation is maintained as **docs-as-code** within the
+repository using:
+
+- arc42 chapter structure
+- Markdown files
+- PlantUML diagrams rendered via CI
+
+Documentation changes are reviewed and versioned together with code changes.
+
+## Consequences
+
+- Architecture documentation stays close to implementation.
+- Diagrams are reproducible and version-controlled.
+- Contributors can review documentation changes like code.
+- Requires CI support and disciplined maintenance.
+

doc/adr/0006-adopt-docs-as-code-with-arc42-chapters-and-plantuml-diagrams.md

@@ -0,0 +1,78 @@
+# Architecture Decision Records (ADR)
+
+This directory contains the **Architecture Decision Records (ADRs)** for the
+**Protopipe Frontend Platform**.
+
+ADRs document significant architectural decisions, including their context,
+the decision taken, and the resulting consequences. They serve as a durable,
+reviewable record of architectural intent and rationale.
+
+The ADRs in this repository are maintained using the
+[`adr-tools`](https://github.com/npryce/adr-tools) workflow and are versioned
+together with the source code.
+
+---
+
+## Accepted Decisions
+
+- [ADR-0001: Record Architecture Decisions](0001-record-architecture-decisions.md)
+- [ADR-0002: Model Pages and Experiments as Kubernetes CRDs](0002-model-pages-and-experiments-as-kubernetes-crds.md)
+- [ADR-0003: Introduce Render Function Artifacts as the Rendering Boundary](0003-introduce-render-function-artifacts-as-the-rendering-boundary.md)
+- [ADR-0004: Use Artifact-based Experiments Instead of Feature Toggles in Product Code](0004-use-artifact-based-experiments-instead-of-feature-toggles-in-product-code.md)
+- [ADR-0005: Keep Metrics in Prometheus; Avoid Counters in CRD Status](0005-keep-metrics-in-prometheus-avoid-counters-in-crd-status.md)
+- [ADR-0006: Adopt Docs-as-Code with arc42 Chapters and PlantUML Diagrams](0006-adopt-docs-as-code-with-arc42-chapters-and-plantuml-diagrams.md)
+- [ADR-0007: Establish ADR Governance and Lifecycle](0007-establish-adr-governance-and-lifecycle.md)
+
+---
+
+## Proposed Decisions
+
+_(none at this time)_
+
+---
+
+## Superseded Decisions
+
+_(none at this time)_
+
+---
+
+## ADR Lifecycle
+
+Each ADR follows a simple lifecycle:
+
+1. **Proposed**  
+   The decision is under discussion and not yet binding.
+
+2. **Accepted**  
+   The decision is agreed upon and considered architectural guidance.
+
+3. **Superseded**  
+   The decision has been replaced by a newer ADR, which must explicitly
+   reference the superseded decision.
+
+---
+
+## Contribution Guidelines
+
+- Architectural changes of structural relevance **require an ADR**.
+- ADRs must follow the standard template:
+  - Context
+  - Decision
+  - Consequences
+- ADRs are reviewed by the core maintainers.
+- Once accepted, ADRs should not be modified retroactively; changes require
+  a new ADR that supersedes the previous one.
+
+---
+
+## Relationship to arc42
+
+The arc42 chapter  
+**09 – Architecture Decisions**  
+references this directory as the authoritative source for architectural
+decisions.
+
+See:  
+`docs/arc42/09-architecture-decisions.md`
+