ops-jrz1/specs/001-extract-matrix-platform/plan.md

Implementation Plan: Extract Matrix Platform Modules for ops-jrz1 Server

Branch: 001-extract-matrix-platform | Date: 2025-10-11 | Spec: spec.md Input: Feature specification from /specs/001-extract-matrix-platform/spec.md

Summary

Extract production-tested NixOS modules for Matrix homeserver (Continuwuity), mautrix bridges (Slack, WhatsApp, Google Messages), and security hardening from ops-base repository. Sanitize personal information (domains, IPs, secrets, paths) and place in this repository to configure the ops-jrz1 dev/test server. Include deployment documentation and secrets management setup using sops-nix.

Note: This is a single-repository project. All extracted modules, configuration, and documentation live in ops-jrz1 repository. Public template sharing is deferred for future.

Technical Context

Language/Version: Nix 2.x, NixOS 24.05+, Bash 5.x (for scripts) Primary Dependencies:

• nixpkgs (pinned for reproducibility)
• sops-nix (secrets management)
• gitleaks (secret scanning via git hooks)
• age (encryption)
• pre-commit framework (git hooks orchestration)

Storage: Git repository (Forgejo for development, GitHub/tangl.sh for publication), filesystem-based (NixOS modules as .nix files) Testing & Validation:

• Git pre-commit hooks (block commits with syntax errors or secrets)
• Git pre-push hooks (validate builds before push)
• nix flake check (syntax and build validation)
• gitleaks (secret scanning via hooks)
• Integration testing (deploy to test VPS)
• Manual validation (sanitization review)

Target Platform: Linux (NixOS), x86_64-linux architecture Project Type: NixOS server configuration (modules + configuration + documentation) Performance Goals:

• Template clone to working deployment: <30 minutes
• Git pre-commit hook execution: <30 seconds
• Git pre-push hook validation (full build): <5 minutes
• nix flake check: <2 minutes

Constraints:

• Zero secrets in published repository (gitleaks must return 0 findings)
• All example configurations must build successfully
• Fresh git history (no ops-base history)
• Manual sync process (scripted helpers only)

Scale/Scope:

• 6+ core NixOS modules to extract (matrix-continuwuity, 3 bridges, 2 security)
• Core documentation (README, deployment guide, secrets-management)
• Configuration for ops-jrz1 dev/test server
• 29 functional requirements (some deferred for public sharing)
• 5 user stories (US3 deferred, US1/US2/US4/US5 active)

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

Status: No project constitution defined yet. This is an infrastructure extraction project with established RFC.

Key Constraints Derived from Feature Spec:

1. ✅ Security First: Zero tolerance for secret leakage (gitleaks validation mandatory)
2. ✅ Reproducibility: All builds must be deterministic (pinned nixpkgs)
3. ✅ Testability: All configurations must validate before publication
4. ✅ Documentation Quality: Extracted patterns must be comprehensive and sanitized
5. ✅ Community Governance: Clear contribution and security policies required

No violations identified - This is a one-time extraction project following established RFC guidelines.

Project Structure

Documentation (this feature)

specs/001-extract-matrix-platform/
├── spec.md              # Feature specification (completed)
├── plan.md              # This file (/speckit.plan command output)
├── research.md          # Phase 0 output (technical decisions & patterns)
├── data-model.md        # Phase 1 output (entities: modules, configs, secrets)
├── quickstart.md        # Phase 1 output (developer quick start)
├── contracts/           # Phase 1 output (sanitization rules, CI contracts)
│   ├── sanitization-rules.yaml
│   └── ci-validation.yaml
└── tasks.md             # Phase 2 output (/speckit.tasks command)

Source Code (repository root)

Single repository structure (ops-jrz1). Everything lives here:

# ops-jrz1 (this repo): Server config + planning + extracted modules
specs/001-extract-matrix-platform/   # Planning docs (speckit workflow)
  ├── spec.md, plan.md, tasks.md
  ├── research.md, data-model.md
  └── contracts/

staging/                             # Temporary extraction workspace
  ├── modules/                       # Copied from ops-base (unsanitized)
  ├── configurations/
  └── docs/

modules/                             # Extracted & sanitized modules
  ├── matrix-continuwuity.nix
  ├── mautrix-slack.nix
  ├── mautrix-whatsapp.nix
  ├── mautrix-gmessages.nix
  ├── security/
  │   ├── fail2ban.nix
  │   └── ssh-hardening.nix
  └── matrix-secrets/
      └── default.nix

hosts/                               # Server-specific configs
  └── ops-jrz1.nix                   # ops-jrz1 server configuration

docs/                                # Deployment documentation
  ├── deployment.md
  ├── secrets-management.md
  └── bridges/                       # Optional bridge setup notes
      ├── slack-setup.md
      ├── whatsapp-setup.md
      └── gmessages-setup.md

secrets/                             # sops-nix encrypted secrets
  ├── secrets.yaml                   # Encrypted (gitignored)
  └── .sops.yaml                     # sops configuration

scripts/                             # Helper scripts
  ├── sanitize-files.sh              # Apply sanitization rules
  └── validate-config.sh             # Pre-deploy validation

flake.nix                            # Server flake configuration
flake.lock                           # Locked dependencies
configuration.nix                    # Main server configuration
README.md                            # Repository overview
LICENSE                              # MIT license (optional)

Structure Decision: Single-repository approach where ops-jrz1 contains planning docs, extracted modules, and server configuration. Public template sharing is deferred - focus is on getting ops-jrz1 server working.

Complexity Tracking

No constitution violations - this section not applicable

Phase 0: Research & Decision Points ✅ COMPLETE

Status: All research completed and documented in research.md

Decisions Made:

1. Sanitization Strategy: ✅ Hybrid approach (automated + manual validation)
2. Worklog Extraction: ✅ LLM-assisted selective extraction with manual review
3. Validation Strategy: ✅ Git hooks (pre-commit/pre-push) with gitleaks + nix flake check
4. Sync Workflow Design: ✅ Git tags + sync-log.md + quarterly calendar
5. Testing Strategy: ✅ Build validation + selective VPS integration testing

Artifacts Generated:

• ✅ research.md - 6 major decisions documented with rationale
• ✅ Technology stack defined (Nix, NixOS, sops-nix, gitleaks, pre-commit framework)
• ✅ Risk mitigations documented
• ✅ Success metrics defined

---

Phase 1: Design & Contracts ✅ COMPLETE

Status: All design artifacts created and validated

Artifacts Generated:

• ✅ data-model.md - 8 core entities with lifecycle states, relationships, validation rules
• ✅ contracts/sanitization-rules.yaml - 22 sanitization rules (critical, high, medium priority)
• ✅ contracts/ci-validation.yaml - CI/CD pipeline specification with job contracts
• ✅ quickstart.md - 4-week implementation guide with day-by-day breakdown
• ✅ CLAUDE.md - Agent context updated with Nix, NixOS, Git repository stack

Design Highlights:

• Data Model: Module, Configuration, Secret, Sanitization Rule, Pattern Document, Sync Checkpoint, Bridge Setup Guide, CI/CD Pipeline
• 22 Sanitization Rules: Domains (clarun.xyz→example.com), IPs (192.168.1.x→10.0.0.x), paths, secrets, personal references
• CI Contracts: nix flake check, gitleaks scan, build validation for example configs
• Validation Pipeline: 5-step process from automated replacement to manual review

---

Phase 2: Task Generation (Next Step)

Status: Ready for /speckit.tasks command

Use /speckit.tasks to generate actionable task breakdown from the design artifacts above. This will create tasks.md with dependency-ordered implementation tasks organized by:

• Repository setup and sanitization
• Documentation extraction
• Testing and validation
• Sync workflow and publication