- Add 5 standalone ADRs in infra/matrix/docs/adr/ - Add EXECUTION_ARCHITECTURE_KT.md: exact path from DNS decision to fleet ops - Architecture proof and continuity preserved
This commit is contained in:
Ezra (Archivist)
39
infra/matrix/docs/adr/ADR-001-conduit-selection.md
Normal file
39
infra/matrix/docs/adr/ADR-001-conduit-selection.md
Normal file
@@ -0,0 +1,39 @@
|
||||
# ADR-001: Homeserver Selection — Conduit
|
||||
|
||||
**Status**: Accepted
|
||||
**Date**: 2026-04-05
|
||||
**Deciders**: Ezra (architect), Timmy Foundation
|
||||
**Scope**: Matrix homeserver for human-to-fleet encrypted communication (#166, #183)
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
We need a Matrix homeserver to serve as the sovereign operator surface. Options:
|
||||
- **Synapse** (Python, mature, resource-heavy)
|
||||
- **Dendrite** (Go, lighter, beta federation)
|
||||
- **Conduit** (Rust, lightweight, SQLite support)
|
||||
|
||||
## Decision
|
||||
|
||||
Use **Conduit** as the Matrix homeserver.
|
||||
|
||||
## Consequences
|
||||
|
||||
| Positive | Negative |
|
||||
|----------|----------|
|
||||
| Low RAM/CPU footprint (~200 MB) | Smaller ecosystem than Synapse |
|
||||
| SQLite option eliminates Postgres ops | Some edge-case federation bugs |
|
||||
| Single binary, simple systemd service | Admin tooling less mature |
|
||||
| Full federation support | |
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
- **Synapse**: Rejected due to Python overhead and mandatory Postgres complexity.
|
||||
- **Dendrite**: Rejected due to beta federation status; we need reliable federation from day one.
|
||||
|
||||
## References
|
||||
|
||||
- Issue: [#166](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/166)
|
||||
- Issue: [#183](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/183)
|
||||
- Conduit docs: https://conduit.rs/
|
||||
37
infra/matrix/docs/adr/ADR-002-hermes-vps-host.md
Normal file
37
infra/matrix/docs/adr/ADR-002-hermes-vps-host.md
Normal file
@@ -0,0 +1,37 @@
|
||||
# ADR-002: Host Selection — Hermes VPS
|
||||
|
||||
**Status**: Accepted
|
||||
**Date**: 2026-04-05
|
||||
**Deciders**: Ezra (architect), Timmy Foundation
|
||||
**Scope**: Initial deployment host for Matrix/Conduit (#166, #183, #187)
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
We need a target host for the Conduit homeserver. Options:
|
||||
- Existing Hermes VPS (`143.198.27.163`)
|
||||
- Timmy-Home bare metal
|
||||
- New cloud droplet (DigitalOcean, Hetzner, etc.)
|
||||
|
||||
## Decision
|
||||
|
||||
Use the **existing Hermes VPS** as the initial host, with a future option to migrate to a dedicated Matrix VPS if load demands.
|
||||
|
||||
## Consequences
|
||||
|
||||
| Positive | Negative |
|
||||
|----------|----------|
|
||||
| Zero additional hosting cost | Shared resource pool with Gitea + wizard gateways |
|
||||
| Known operational state (backups, monitoring) | Single point of failure for multiple services |
|
||||
| Simplified network posture | May need to upgrade VPS if federation traffic grows |
|
||||
|
||||
## Migration Trigger
|
||||
|
||||
If Matrix active users exceed ~50 or federation traffic causes >60% sustained CPU, migrate to a dedicated VPS. The Docker Compose scaffold makes this a data-directory copy.
|
||||
|
||||
## References
|
||||
|
||||
- Issue: [#166](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/166)
|
||||
- Issue: [#187](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/187)
|
||||
- Decision Framework: [`docs/DECISION_FRAMEWORK_187.md`](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/src/branch/main/docs/DECISION_FRAMEWORK_187.md)
|
||||
35
infra/matrix/docs/adr/ADR-003-full-federation.md
Normal file
35
infra/matrix/docs/adr/ADR-003-full-federation.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# ADR-003: Federation Strategy — Full Federation Enabled
|
||||
|
||||
**Status**: Accepted
|
||||
**Date**: 2026-04-05
|
||||
**Deciders**: Ezra (architect), Timmy Foundation
|
||||
**Scope**: Federation behavior for Conduit homeserver (#166, #183)
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Matrix servers can operate in isolated mode (no federation) or federated mode (interoperate with matrix.org and other homeservers).
|
||||
|
||||
## Decision
|
||||
|
||||
Enable **full federation from day one**.
|
||||
|
||||
## Consequences
|
||||
|
||||
| Positive | Negative |
|
||||
|----------|----------|
|
||||
| Alexander can use any Matrix client/ID | Requires public DNS + TLS + port 8448 |
|
||||
| Fleet bots can bridge to other networks | Slightly larger attack surface |
|
||||
| Aligns with sovereign, open protocol ethos | Must monitor for abuse/spam |
|
||||
|
||||
## Prerequisites Introduced
|
||||
|
||||
- Valid TLS certificate (Let's Encrypt via Caddy)
|
||||
- Public DNS A record + SRV record
|
||||
- Firewall open on TCP 8448 inbound
|
||||
|
||||
## References
|
||||
|
||||
- Issue: [#166](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/166)
|
||||
- Runbook: [`infra/matrix/docs/RUNBOOK.md`](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/src/branch/main/infra/matrix/docs/RUNBOOK.md)
|
||||
38
infra/matrix/docs/adr/ADR-004-caddy-reverse-proxy.md
Normal file
38
infra/matrix/docs/adr/ADR-004-caddy-reverse-proxy.md
Normal file
@@ -0,0 +1,38 @@
|
||||
# ADR-004: Reverse Proxy Selection — Caddy
|
||||
|
||||
**Status**: Accepted
|
||||
**Date**: 2026-04-05
|
||||
**Deciders**: Ezra (architect), Timmy Foundation
|
||||
**Scope**: TLS termination and reverse proxy for Matrix/Conduit (#166, #183)
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Options for reverse proxy + TLS:
|
||||
- **Caddy** (auto-TLS, simple config)
|
||||
- **Traefik** (Docker-native, label-based)
|
||||
- **Nginx** (ubiquitous, more manual)
|
||||
|
||||
## Decision
|
||||
|
||||
Use **Caddy** as the dedicated reverse proxy for Matrix services.
|
||||
|
||||
## Consequences
|
||||
|
||||
| Positive | Negative |
|
||||
|----------|----------|
|
||||
| Automatic ACME/Let's Encrypt | Less community Matrix-specific examples |
|
||||
| Native `.well-known` + SRV support | New config language for ops team |
|
||||
| No Docker label magic required | |
|
||||
| Clean separation from existing Traefik | |
|
||||
|
||||
## Implementation
|
||||
|
||||
See:
|
||||
- `infra/matrix/caddy/Caddyfile`
|
||||
- `deploy/matrix/Caddyfile`
|
||||
|
||||
## References
|
||||
|
||||
- Issue: [#183](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/183)
|
||||
35
infra/matrix/docs/adr/ADR-005-sqlite-phase1.md
Normal file
35
infra/matrix/docs/adr/ADR-005-sqlite-phase1.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# ADR-005: Database Selection — SQLite for Phase 1
|
||||
|
||||
**Status**: Accepted
|
||||
**Date**: 2026-04-05
|
||||
**Deciders**: Ezra (architect), Timmy Foundation
|
||||
**Scope**: Persistence layer for Conduit (#166, #183)
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Conduit supports SQLite and PostgreSQL. Synapse requires Postgres.
|
||||
|
||||
## Decision
|
||||
|
||||
Use **SQLite** for the initial deployment (Phase 1). Migrate to PostgreSQL only if user count or performance metrics trigger it.
|
||||
|
||||
## Consequences
|
||||
|
||||
| Positive | Negative |
|
||||
|----------|----------|
|
||||
| Zero additional container/service | Harder to scale horizontally |
|
||||
| Single file backup/restore | Performance ceiling under heavy load |
|
||||
| Conduit optimized for SQLite | |
|
||||
|
||||
## Migration Trigger
|
||||
|
||||
- Concurrent active users > 50
|
||||
- Database file > 10 GB
|
||||
- Noticeable query latency on room sync
|
||||
|
||||
## References
|
||||
|
||||
- Issue: [#166](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/166)
|
||||
- Config: `infra/matrix/conduit.toml`
|
||||
26
infra/matrix/docs/adr/README.md
Normal file
26
infra/matrix/docs/adr/README.md
Normal file
@@ -0,0 +1,26 @@
|
||||
# Architecture Decision Records — Matrix/Conduit Fleet Communications
|
||||
|
||||
**Issue**: [#183](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/183)
|
||||
**Parent**: [#166](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/166)
|
||||
|
||||
---
|
||||
|
||||
## Index
|
||||
|
||||
| ADR | Decision | File |
|
||||
|-----|----------|------|
|
||||
| ADR-001 | Homeserver: Conduit | `ADR-001-conduit-selection.md` |
|
||||
| ADR-002 | Host: Hermes VPS | `ADR-002-hermes-vps-host.md` |
|
||||
| ADR-003 | Federation: Full enable | `ADR-003-full-federation.md` |
|
||||
| ADR-004 | Reverse Proxy: Caddy | `ADR-004-caddy-reverse-proxy.md` |
|
||||
| ADR-005 | Database: SQLite (Phase 1) | `ADR-005-sqlite-phase1.md` |
|
||||
|
||||
## Purpose
|
||||
|
||||
These ADRs make the #183 scaffold auditable and portable. Any future agent or operator can understand *why* the architecture is shaped this way without re-litigating decisions.
|
||||
|
||||
## Continuity
|
||||
|
||||
- Canonical scaffold index: [`docs/CANONICAL_INDEX_MATRIX.md`](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/src/branch/main/docs/CANONICAL_INDEX_MATRIX.md)
|
||||
- Decision framework for #187: [`docs/DECISION_FRAMEWORK_187.md`](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/src/branch/main/docs/DECISION_FRAMEWORK_187.md)
|
||||
- Operational runbook: [`infra/matrix/docs/RUNBOOK.md`](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/src/branch/main/infra/matrix/docs/RUNBOOK.md)
|
||||
Reference in New Issue
Block a user