# ops-jrz1 Development Guidelines

Auto-generated from all feature plans. Last updated: 2025-10-22

## Active Technologies
- Nix 2.x, NixOS 24.05+, Bash 5.x (for scripts) (001-extract-matrix-platform)
- mautrix-slack (Python 3.11), PostgreSQL 15.10, sops-nix (002-slack-bridge-integration)
- Matrix homeserver: conduwuit (clarun.xyz)
- Secrets management: sops-nix with age encryption

## Project Structure
```
.
├── hosts/                    # NixOS host configurations
│   └── ops-jrz1.nix         # VPS configuration (45.77.205.49)
├── modules/                  # NixOS modules
│   ├── dev-services.nix     # PostgreSQL, Forgejo, bridge coordination
│   ├── mautrix-slack.nix    # Slack bridge module
│   └── matrix-continuwuity.nix  # Matrix homeserver
├── secrets/                  # sops-encrypted secrets
│   └── secrets.yaml         # Encrypted credentials (age)
├── specs/                    # Feature specifications
│   ├── 001-extract-matrix-platform/
│   └── 002-slack-bridge-integration/
│       ├── spec.md          # Feature specification
│       ├── plan.md          # Implementation plan
│       ├── research.md      # Technical research findings
│       ├── data-model.md    # Data model & state machines
│       ├── quickstart.md    # Deployment runbook
│       └── contracts/       # Configuration schemas
├── docs/                     # Documentation
│   ├── platform-vision.md   # North star document
│   └── worklogs/            # Deployment logs
└── .specify/                 # Spec-kit framework files
```

## Commands

### Deployment
```bash
# Deploy configuration to VPS
nixos-rebuild switch --flake .#ops-jrz1 \
  --target-host root@45.77.205.49 \
  --build-host localhost

# Deploy to staging
nixos-rebuild switch --flake .#ops-jrz1-staging \
  --target-host root@45.77.205.49 \
  --build-host localhost
```

### Bridge Management
```bash
# Check bridge status
ssh root@45.77.205.49 'systemctl status mautrix-slack'

# View bridge logs
ssh root@45.77.205.49 'journalctl -u mautrix-slack -f'

# Check Socket Mode connection
ssh root@45.77.205.49 'journalctl -u mautrix-slack -n 20 | grep -i socket'

# Query bridge database
ssh root@45.77.205.49 'sudo -u mautrix_slack psql mautrix_slack -c "SELECT * FROM portal;"'
```

### Secrets Management
```bash
# Edit encrypted secrets
sops secrets/secrets.yaml

# View decrypted secrets (never commit output)
sops -d secrets/secrets.yaml

# Add new secret
sops secrets/secrets.yaml
# (Edit in your $EDITOR, auto-encrypts on save)
```

### Matrix Server
```bash
# Check Matrix homeserver
ssh root@45.77.205.49 'systemctl status matrix-continuwuity'

# Test federation
ssh root@45.77.205.49 'curl -s http://localhost:8008/_matrix/client/versions | jq .'
```

### Database
```bash
# List databases
ssh root@45.77.205.49 'sudo -u postgres psql -l'

# Check bridge database
ssh root@45.77.205.49 'sudo -u postgres psql mautrix_slack -c "\dt"'

# Backup bridge database
ssh root@45.77.205.49 'sudo -u postgres pg_dump mautrix_slack' > backup.sql
```

## Code Style
- Nix 2.x, NixOS 24.05+, Bash 5.x: Follow standard conventions
- NixOS modules: Use nixpkgs module pattern (options, config, mkIf)
- Configuration: Declarative over imperative
- Secrets: Never hardcode, use sops-nix or interactive login
- Logging: Use appropriate levels (debug for troubleshooting, info for production)

## Development Patterns

### Slack Bridge (002-slack-bridge-integration)
- **Authentication**: Interactive login via Matrix chat (`login app` command)
- **Socket Mode**: WebSocket connection, no public endpoint needed
- **Portal Creation**: Automatic based on activity (no manual channel mapping)
- **Secrets**: Stored in bridge database after authentication (not in NixOS config)
- **Token Requirements**: Bot token (xoxb-) + app-level token (xapp-)

### Secrets Management
- **Encryption**: Age encryption via SSH host key (/etc/ssh/ssh_host_ed25519_key)
- **Storage**: secrets/secrets.yaml (encrypted, safe to commit)
- **Runtime**: Decrypted to /run/secrets/ (tmpfs, cleared on reboot)
- **Permissions**: 0440 for service-specific secrets, owned by service user

### Deployment Workflow
1. Make configuration changes locally
2. Commit to git
3. Deploy via nixos-rebuild
4. Verify service status and logs
5. Document in worklogs/
6. Test functionality
7. Monitor for stability

## Recent Changes
- 001-extract-matrix-platform: Added Nix 2.x, NixOS 24.05+, Bash 5.x (for scripts)
- 002-slack-bridge-integration: Added mautrix-slack bridge with Socket Mode (2025-10-22)
  - Phase 0: Research complete (Socket Mode, API scopes, sops-nix, channel patterns)
  - Phase 1: Design complete (data-model.md, contracts/, quickstart.md)
  - Next: Phase 2 (/speckit.tasks for implementation breakdown)

## Known Issues
- mautrix-slack exits with code 11 without credentials (expected, requires `login app`)
- olm-3.2.16 marked insecure (permitted via nixpkgs.config.permittedInsecurePackages)

## Testing Guidelines
- Test message latency: Should be <5 seconds (FR-001, FR-002)
- Test reactions, edits, file attachments
- Monitor health indicators: connection_status, last_successful_message, error_count
- Stability target: 99% uptime over 7-day period

<!-- MANUAL ADDITIONS START -->
<!-- MANUAL ADDITIONS END -->