# CLAUDE.md

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

## Project Purpose

Production-grade n8n automation stack running on Docker Compose. The primary use-case is importing, managing, and running n8n workflow projects from third parties.

## Intended Stack Architecture

| Service | Role |
|---|---|
| n8n (main) | Workflow editor + webhook entrypoint |
| n8n-worker(s) | Queue-mode execution workers |
| PostgreSQL | Primary database |
| Redis | Queue backend for worker mode |
| Reverse Proxy | HTTPS termination (integrate existing proxy if present) |

All data-heavy paths (volumes, backups) live under `/home/dschlueter/nvme2n1p7_home/n8n_stack/`.

## Directory Layout (target)

```
compose/          # docker-compose.yml and any override files
.env              # secrets and config (never commit — see .gitignore)
.env.example      # safe template for .env
data/             # docker volume mount-points (gitignored)
backups/          # database + file backups (gitignored)
imports/
  workflows/      # JSON files to import
  credentials/    # JSON credential exports
local-files/      # files made available inside n8n containers
docs/             # architecture notes, runbooks
scripts/          # helper shell scripts (see below)
```

## Helper Scripts (scripts/)

| Script | Purpose |
|---|---|
| `import-workflow.sh` | Import a workflow JSON via n8n CLI |
| `import-credentials.sh` | Import credentials JSON via n8n CLI |
| `export-workflows.sh` | Dump all workflows to `imports/workflows/` |
| `export-credentials.sh` | Dump credentials (unencrypted — handle with care) |
| `backup-n8n.sh` | Snapshot DB + n8n data to `backups/` |
| `restore-n8n.sh` | Restore from a snapshot |

## Common Operations

```bash
# Start full stack
docker compose -f compose/docker-compose.yml up -d

# Stop stack
docker compose -f compose/docker-compose.yml down

# View logs
docker compose -f compose/docker-compose.yml logs -f n8n

# Check health
docker compose -f compose/docker-compose.yml ps

# Import a workflow
bash scripts/import-workflow.sh imports/workflows/my-workflow.json

# Export all workflows
bash scripts/export-workflows.sh

# Full backup
bash scripts/backup-n8n.sh
```

## Key Configuration Notes

- All secrets (DB password, `N8N_ENCRYPTION_KEY`, Redis password) are generated once and stored in `.env`. The encryption key must never change after first run — doing so breaks stored credentials.
- Queue mode requires `EXECUTIONS_MODE=queue` in `.env` and a running Redis instance.
- Timezone is `Europe/Berlin` throughout.
- Only port 443/80 (via reverse proxy) should be exposed externally; n8n listens internally on 5678.

## Security Notes on Export

`export-credentials.sh` produces **unencrypted** JSON — treat the output like a private key. Keep exports out of `imports/credentials/` if that directory is ever shared.

## Idempotency Rule

All scripts and compose changes must be idempotent (safe to re-run). Before risky changes, back up the relevant config or volume first.