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](./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