Timmy_Foundation/timmy-config
15
0
Fork 0
Code Issues 204 Pull Requests 3 Actions Packages Projects Releases Wiki Activity
Files
df779609c49f1b21339f3c071cb25899468c709c
timmy-config/docs/matrix-fleet-comms/EXECUTION_ARCHITECTURE_KT.md
Ezra (Archivist) 1411fded99 [BURN] Matrix scaffold verification, room bootstrap automation, cutover plan 
- Verify #183 scaffold completeness (MATRIX_SCAFFOLD_VERIFICATION.md)
- Add bootstrap-fleet-rooms.py for automated Matrix room creation (#166)
- Add CUTOVER_PLAN.md for Telegram→Matrix migration (#166)
- Update EXECUTION_ARCHITECTURE_KT.md with new automation references

Progresses #166, verifies #183
2026-04-05 18:42:03 +00:00

244 lines
8.6 KiB
Markdown
Raw Blame History

# Execution Architecture KT — Matrix/Conduit Human-to-Fleet Comms
**Issue**: [#166](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/166)
**Blocker**: [#187](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/187) — Host/domain/proxy decisions
**Scaffold**: [#183](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/183)
**Created**: Ezra | 2026-04-05
**Purpose**: Turn the #166 fuzzy epic into an exact execution script. Once #187 closes, follow this KT verbatim.
---
## Executive Summary
This document is the **knowledge transfer** from architecture (#183) to execution (#166). It assumes the decision framework in `docs/DECISION_FRAMEWORK_187.md` has been accepted (recommended: **Option A — Hermes VPS + Caddy + matrix.timmytime.net**) and maps every step from "DNS record exists" to "Alexander sends an encrypted message to the fleet."
---
## Pre-Conditions (Close #187 First)
| # | Pre-Condition | Authority | Evidence |
|---|---------------|-----------|----------|
| 1 | Host chosen (IP known) | Alexander/admin | Written in #187 |
| 2 | Domain/subdomain chosen | Alexander/admin | DNS A record live |
| 3 | Reverse proxy chosen | Alexander/admin | Caddyfile committed |
| 4 | Ports 80/443/8448 open | Host admin | `host-readiness-check.sh` passes |
| 5 | TLS path confirmed | Architecture | Let's Encrypt viable |
> **If all 5 are true, #166 is unblocked and this KT is the runbook.**
---
## Phase 1: Host Prep (30 minutes)
### 1.1 Clone Repo on Target Host
```bash
ssh root@<HOST_IP>
git clone https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-config.git /opt/timmy-config
cd /opt/timmy-config/infra/matrix
```
### 1.2 Verify Host Readiness
```bash
./host-readiness-check.sh
```
Expected: all checks green (Docker, ports, disk, RAM).
### 1.3 Configure Environment
```bash
cp .env.example .env
# Edit .env:
# CONDUIT_SERVER_NAME=matrix.timmytime.net
# CONDUIT_ALLOW_REGISTRATION=true # ONLY for bootstrap
```
---
## Phase 2: Conduit Deployment (15 minutes)
### 2.1 One-Command Deploy
```bash
./deploy-matrix.sh
```
This starts:
- Conduit homeserver container
- Caddy reverse proxy container
- (Optional) Element web client
### 2.2 Verify Health
```bash
curl -s https://matrix.timmytime.net/_matrix/client/versions | jq .
```
Expected: JSON with `versions` array.
### 2.3 Verify Federation
```bash
curl -s https://matrix.timmytime.net/.well-known/matrix/server
```
Expected: `{"m.server": "matrix.timmytime.net:443"}`
---
## Phase 3: Fleet Bootstrap — Accounts & Rooms (30 minutes)
### 3.1 Create Admin Account
**Enable registration temporarily** in `.env`:
```
CONDUIT_ALLOW_REGISTRATION=true
CONDUIT_REGISTRATION_TOKEN=<random_secret>
```
Restart:
```bash
docker compose restart conduit
```
Register admin:
```bash
docker exec -it conduit register_new_matrix_user -c /var/lib/matrix-conduit -u admin -p '<STRONG_PASS>' -a
```
**Immediately disable registration** and restart.
### 3.2 Create Fleet Accounts
| Account | Purpose | Created By |
|---------|---------|------------|
| `@admin:matrix.timmytime.net` | Server administration | deploy script |
| `@alexander:matrix.timmytime.net` | Human operator | admin |
| `@timmy:matrix.timmytime.net` | Coordinator bot | admin |
| `@ezra:matrix.timmytime.net` | Archivist bot | admin |
| `@allegro:matrix.timmytime.net` | Dispatch bot | admin |
| `@bezalel:matrix.timmytime.net` | Dev bot | admin |
| `@gemini:matrix.timmytime.net` | Nexus architect bot | admin |
Use the Conduit admin API or `register_new_matrix_user` for each.
### 3.3 Create Fleet Rooms
| Room Alias | Purpose | Encryption |
|------------|---------|------------|
| `#fleet-ops:matrix.timmytime.net` | Operator commands | ✅ E2E |
| `#fleet-intel:matrix.timmytime.net` | Deep Dive briefings | ✅ E2E |
| `#fleet-social:matrix.timmytime.net` | General chat | ✅ E2E |
| `#fleet-alerts:matrix.timmytime.net` | Critical alerts | ✅ E2E |
**Create room via Element Web or curl:**
```bash
curl -X POST "https://matrix.timmytime.net/_matrix/client/v3/createRoom" -H "Authorization: Bearer <ADMIN_TOKEN>" -d '{
"name": "Fleet Ops",
"room_alias_name": "fleet-ops",
"preset": "private_chat",
"initial_state": [{
"type": "m.room.encryption",
"content": {"algorithm": "m.megolm.v1.aes-sha2"}
}]
}'
```
### 3.4 Invite Fleet Members
Invite each bot/user to the appropriate rooms. For `#fleet-ops`, restrict to `@alexander`, `@timmy`, `@ezra`, `@allegro`.
---
## Phase 4: Wizard Onboarding Procedure (30 minutes)
Each wizard house needs:
1. **Matrix credentials** (username + password + recovery key)
2. **Client recommendation** — Element Desktop or Fluffychat
3. **Room memberships** — invite to relevant fleet rooms
4. **Encryption verification** — verify keys with Alexander
### Onboarding Checklist per Wizard
- [ ] Account created and credentials stored in vault
- [ ] Client installed and signed in
- [ ] Joined `#fleet-ops` and `#fleet-intel`
- [ ] E2E verification completed with `@alexander`
- [ ] Test message sent and received
---
## Phase 5: Telegram → Matrix Cutover Architecture
### 5.1 Parallel Operations (Week 1-2)
- Telegram remains primary
- Matrix is shadow channel: duplicate critical messages to both
- Bots post to Matrix for habit formation
### 5.2 Bridge Option (Evaluative)
If immediate message parity is required, evaluate:
- **mautrix-telegram** bridge (self-hosted, complex)
- **Manual dual-post** (simple, temporary)
**Recommendation**: Skip the bridge for now. Dual-post via bot logic is lower risk.
### 5.3 Cutover Trigger
When:
- All wizards are active on Matrix
- Alexander confirms Matrix reliability for 7 consecutive days
- E2E encryption verified in `#fleet-ops`
**Action**: Declare Matrix the primary human-to-fleet surface. Telegram becomes fallback only.
---
## Operational Continuity
### Backup
```bash
# Daily cron on host
0 2 * * * /opt/timmy-config/infra/matrix/scripts/deploy-conduit.sh backup
```
### Monitoring
```bash
# Health check every 5 minutes
*/5 * * * * /opt/timmy-config/infra/matrix/scripts/deploy-conduit.sh status || alert
```
### Upgrade Path
1. Pull latest `timmy-config`
2. Run `./host-readiness-check.sh`
3. `docker compose pull && docker compose up -d`
---
## Acceptance Criteria Mapping
| #166 Criterion | How This KT Satisfies It | Phase |
|----------------|--------------------------|-------|
| Deploy Conduit homeserver | `deploy-matrix.sh` + health checks | 2 |
| Create fleet rooms/channels | Exact room aliases + creation curl | 3 |
| Verify encrypted operator messaging | E2E enabled + key verification step | 3-4 |
| Define Telegram→Matrix cutover plan | Section 5 explicit cutover trigger | 5 |
| Alexander can message fleet | `@alexander` account + `#fleet-ops` membership | 3 |
| Messages encrypted and persistent | `m.room.encryption` in room creation + Conduit persistence | 3 |
| Telegram no longer only surface | Cutover trigger + dual-post interim | 5 |
---
## Decision Authority for Execution
| Step | Owner | When |
|------|-------|------|
| DNS / #187 close | Alexander | T+0 |
| Run `deploy-matrix.sh` | Allegro or Ezra | T+0 (15 min) |
| Create accounts/rooms | Allegro or Ezra | T+15 (30 min) |
| Onboard wizards | Individual agents + Alexander | T+45 (ongoing) |
| Cutover declaration | Alexander | T+7 days (minimum) |
---
## References
- Scaffold: [`infra/matrix/`](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/src/branch/main/infra/matrix)
- ADRs: [`infra/matrix/docs/adr/`](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/src/branch/main/infra/matrix/docs/adr)
- 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)
- 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)
- **Room Bootstrap Automation**: [`infra/matrix/scripts/bootstrap-fleet-rooms.py`](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/src/branch/main/infra/matrix/scripts/bootstrap-fleet-rooms.py)
- **Telegram Cutover Plan**: [`docs/matrix-fleet-comms/CUTOVER_PLAN.md`](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/src/branch/main/docs/matrix-fleet-comms/CUTOVER_PLAN.md)
- **Scaffold Verification**: [`docs/matrix-fleet-comms/MATRIX_SCAFFOLD_VERIFICATION.md`](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/src/branch/main/docs/matrix-fleet-comms/MATRIX_SCAFFOLD_VERIFICATION.md)
---
**Ezra Sign-off**: This KT removes all ambiguity from #166. The only remaining work is executing these phases in order once #187 is closed. Room creation and Telegram cutover are now automated.
— Ezra, Archivist
2026-04-05
Reference in New Issue View Git Blame Copy Permalink