# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This repository contains SSO infrastructure configuration and documentation for a self-hosted Pangolin + Authentik + Guacamole deployment on brn (10.50.0.74). It is NOT a code project - it's an infrastructure-as-documentation repository with shell scripts, configuration guides, and deployment artifacts.

## Architecture

**Three platforms deployed on brn (10.50.0.74):**

| Platform | URL | Purpose | Docker Path |
|----------|-----|---------|-------------|
| Authentik | https://sso.obr.sh | Central OIDC identity provider | /srv/docker/authentik |
| Pangolin | https://tunnel.obr.sh | WireGuard tunnel manager + identity-aware proxy | /srv/docker/pangolin |
| Guacamole | https://remote.obr.sh/guacamole/ | Clientless RDP gateway | /srv/docker/guacamole |

**Protected services (SSO integration targets):**
- Jellyfin (video.obnh.io) - Media server
- OpenWebUI (ll.obr.sh) - AI chat interface
- Transmission (tor.obnh.network) - Torrent client
- Pi-hole (dns.obnh.io) - DNS/ad blocking
- Gitea instances on fry.obr.sh and proton.obr.sh

**Network constraints (CRITICAL - must preserve):**
- LAN: 10.50.0.0/24 via br0
- WAN: 31.24.10.184/23 via enp131s0
- NAT masquerade for LAN → WAN routing

## Common Commands

```bash
# Health check all SSO platforms
./scripts/monitor-sso-health.sh

# Backup all SSO databases and configs
./scripts/backup-sso-infrastructure.sh

# View logs
cd /srv/docker/authentik && sudo docker compose logs -f
cd /srv/docker/pangolin && sudo docker compose logs -f
cd /srv/docker/guacamole && sudo docker compose logs -f

# Restart a service
cd /srv/docker/<service> && sudo docker compose restart
```

## Key Files

**Scripts:**
- `scripts/monitor-sso-health.sh` - Checks HTTP status, container health, network connectivity
- `scripts/backup-sso-infrastructure.sh` - Backs up PostgreSQL databases and configs to /srv/backups/

**Documentation:**
- `ADD-OIDC-INTEGRATIONS.md` - Complete OIDC provider setup guide (6 providers)
- `DEPLOYMENT-COMPLETE.md` - Deployment summary and next steps
- `QUICK-START.md` - 5-minute setup checklist

**Research artifacts (read-only reference):**
- `.tasks/artifacts/` - Platform research, architecture analysis

## Deployment Notes

- All Docker stacks use `/srv/docker/<name>/` paths
- Secrets stored in `.env` files (chmod 600)
- Traefik handles TLS termination and routing
- Configuration deployed via Ralph Loop (iterative automation)

## When Making Changes

1. Always run `./scripts/monitor-sso-health.sh` before and after changes
2. Backup first: `./scripts/backup-sso-infrastructure.sh`
3. Never modify network routing rules without verifying LAN/WAN access preserved
4. Docker compose changes require `sudo docker compose up -d` to apply