Ekklesia
Ekklesia is the assembly of the called-out — where distinct capabilities are gathered into a unified body, deliberating and acting in concert toward shared platform purpose. This is that assembly.
Ekklesia operates as the platform's inner-source documentation hub: a single centralized documentation site where any team member can contribute, rather than maintaining scattered per-repo READMEs or per-team wikis. See the documentation hub ADR for the rationale.
- Documentation: Docusaurus site structure, contribution model, and authoring conventions for the platform documentation hub
This page includes Architecture Decision Records documenting the key design decisions.
Repositories
- pt-ekklesia-docs: Platform documentation site powered by Docusaurus, published at docs.osinfra.io — see Documentation
AI Context
- pt-ekklesia-ai-context: Team-level Copilot instructions for
pt-ekklesia-*repositories
Context
Ekklesia is a shared service used by all platform teams — every team contributes documentation here and consumes it as the canonical reference for platform knowledge. Because documentation lives in version control and goes through the same PR process as code, it is subject to the same quality standards. Every team owns their section; Ekklesia owns the structure and tooling that makes contribution frictionless.
Glossary
| Term | Meaning in this context |
|---|---|
| Architecture decision record | A structured record of a significant design decision — context, decision, alternatives considered, and consequences |
Team Topologies
Cognitive Load
Ekklesia carries the lightest operational load of any platform team — its context is documentation tooling, which is low inherent complexity. The real challenge is breadth of knowledge: contributing meaningfully to platform docs requires understanding every other team's work.
| Working Domains | High Intrinsic Domains |
|---|---|
| 🟢 1 / 4 | 🟢 0 / 3 |
Cognitive load by domain:
| Domain | Intrinsic | Extraneous Reduced By | Germane Expertise |
|---|---|---|---|
| Documentation | 🟢 Low | Docusaurus + GitHub Pages | Technical writing, platform-wide context |
Capacity: 0 high-complexity domains (Team Topologies guideline: 2–3); team members hold 1 active domain — well within the ~4 working-knowledge limit.
Extraneous load is minimized by:
- Docusaurus and GitHub Pages handle all build and hosting automatically
- All teams contribute via standard GitHub Flow — no separate wiki system or access model
- Documentation lives in version control alongside the code it describes
Germane load is built through:
- Technical writing: structuring complex infrastructure concepts for different audiences
- Information architecture: organizing platform knowledge so engineers can find what they need quickly
- Platform-wide context: Ekklesia contributors develop a uniquely broad understanding of how all platform teams fit together
Team Capacity
- Headcount: Inner source — no dedicated engineer
- Contribution model: Every team updates their section as part of their own PRs; Ekklesia owns the site structure and tooling, not the content
- Scale signal: No scaling expected — documentation is a distributed responsibility by design
Architecture Decision Records
Ekklesia as an Inner-Source Documentation Hub
| Status | Date | Deciders |
|---|---|---|
| Accepted ✅ | April 2026 | Ekklesia |
Context and Problem Statement
Platform knowledge — architecture decisions, module usage, deployment patterns, operational guides — is spread across multiple teams and repositories. Without a shared home, documentation lives in README files that are hard to navigate, per-team wikis that fall out of sync, or not at all. Engineers must hunt across repositories to understand how the platform fits together.
This follows a similar inner-source contribution model to Arche and Techne — the difference is artifact type. Arche shares OpenTofu modules; Techne shares GitHub Actions workflows and tooling; Ekklesia shares documentation.
Decision
Operate a single Docusaurus site (pt-ekklesia-docs) as the canonical platform documentation hub. All teams contribute their documentation here — architecture decisions, module references, operational guides — rather than maintaining it separately. The site is:
- Version-controlled alongside the code it documents
- Automatically built on pull requests and deployed to docs.osinfra.io on merge to
main - Open for contribution from any team member via GitHub Flow
Alternatives Considered
- Per-repo README files — Rejected. Scattered across dozens of repositories; no single place to understand how the platform fits together. Engineers must know which repo to look in before they can find anything.
- Per-team wikis (GitHub Wiki / Confluence) — Rejected. Edited outside of Git, bypassing the PR review process. Content drifts from reality with no mechanism to catch it.
Consequences
- Platform knowledge has a single discoverable home for engineers and stakeholders
- Documentation changes go through the same review process as code
- All teams share responsibility for keeping their sections accurate — no single team owns the whole site