CLAUDE.md & Sync Guardrails

What is CLAUDE.md?

CLAUDE.md is a configuration file placed in each developer’s home directory that provides mandatory instructions to Claude Code (the AI coding assistant). It acts as a safety net — ensuring that every AI-assisted operation follows the platform’s rules, regardless of which user or session is active.

Every user on the Magic e-VERSE server has a CLAUDE.md in their home directory. These files reference a shared guardrails file that is the single source-of-truth for all sync and deployment rules.

File Locations

File	Purpose
/home/<user>/CLAUDE.md	Per-user instructions (references shared guardrails)
/mnt/data/magic_omniverse/CLAUDE_GUARDRAILS.md	Single source-of-truth for all sync rules
/mnt/data/magic_omniverse/CLAUDE_TEMPLATE.md	Template for creating new user CLAUDE.md files

Tip

When updating guardrails, edit only /mnt/data/magic_omniverse/CLAUDE_GUARDRAILS.md. All user CLAUDE.md files reference this shared file automatically.

---

The 8 Guardrail Rules

Rule 1: NEVER Sync Storefronts

Danger

This is the most critical rule. NEVER copy storefront/frontend files between tenants.

Each tenant has its own unique design, branding, theme, and configuration. Syncing storefronts overwrites tenant-specific designs — in the past this caused all tenants to display the Brinxx theme, including Jodasign and others.

What MAY be synced (backend only):

backend/src/api/          # API routes
backend/src/modules/      # Custom modules
backend/src/jobs/         # Background jobs
backend/src/subscribers/  # Event subscribers
backend/src/workflows/    # Medusa workflows
backend/src/utils/        # Utility functions
backend/src/links/        # Module links
backend/src/scripts/      # Utility scripts

What must NEVER be synced:

storefront/               # NEVER - unique design per tenant!
backend/.env              # NEVER - tenant-specific credentials
backend/.env.*            # NEVER - environment variants
docker-compose.yml        # NEVER - tenant-specific ports, DB, config
docker-compose.prod.yml   # NEVER - production overrides
node_modules/             # NEVER - local build artifacts
backend/medusa-config.*   # NEVER - tenant-specific Medusa config
migrations/               # NEVER - evaluate per tenant separately
backend/package.json      # NEVER - can have tenant-specific dependencies

Why Storefronts Differ

Each tenant storefront uses a theme system controlled by NEXT_PUBLIC_THEME in docker-compose:

Tenant	Theme	Design
Brinxx	brinxx	Brinxx corporate branding
Jodasign	jodasign	Jodasign custom design
Logohorloge	logohorloge	Logohorloge styling
Demo	demo	Demo/showcase theme
Default	default	Default template
…	…	Each is unique

Storefronts contain tenant-specific:

• CSS themes and color schemes
• Layout components and branding
• Logo assets and images
• Custom pages and content
• CORS and domain configurations

---

Rule 2: Pre-Sync Checklist

Before syncing ANY code from magic_development to other tenants:

1. Verify development is running and tested

   docker ps | grep magic_development_backend_dev
   # Must show "healthy" or "Up" status

2. List EXACT files to sync — no wildcard copies of entire directories

   # CORRECT: specific files
   FILE="backend/src/api/admin/aplt/orders/route.ts"
   
   # WRONG: entire directories
   cp -r backend/src/ target/backend/src/  # NEVER DO THIS

3. Diff check for tenant-specific customizations

   diff /mnt/data/magic_omniverse/magic_commerce/magic_development/backend/src/path/file.ts \
        /mnt/data/magic_omniverse/magic_commerce/magic_brinxx/backend/src/path/file.ts

   Caution

   Some tenants have custom backend code that differs from development. For example, magic_jodasign has enhanced order number sequencing with thread-safe operations. Always check diffs before overwriting!

4. Create backups of target files

   cp "$TARGET/$FILE" "$TARGET/$FILE.bak_$(date +%Y%m%d_%H%M%S)"

5. Get explicit confirmation before proceeding with the sync

---

Rule 3: Safe Sync Command Template

Always use this pattern — it includes backups and targets only backend files:

# Safe sync template - ONLY backend files
SOURCE="/mnt/data/magic_omniverse/magic_commerce/magic_development"
TENANTS="magic_brinxx magic_default magic_logohorloge magic_bovisales magic_demo magic_desluis magic_jodasign"

# List each file explicitly
FILES=(
  "backend/src/api/admin/aplt/orders/route.ts"
  "backend/src/api/admin/aplt/orders/pdf/route.ts"
)

for tenant in $TENANTS; do
  TARGET="/mnt/data/magic_omniverse/magic_commerce/$tenant"
  echo "--- Syncing to $tenant ---"
  for FILE in "${FILES[@]}"; do
    # Backup first
    if [ -f "$TARGET/$FILE" ]; then
      cp "$TARGET/$FILE" "$TARGET/$FILE.bak_$(date +%Y%m%d_%H%M%S)"
    fi
    # Copy
    cp "$SOURCE/$FILE" "$TARGET/$FILE"
    echo "  Synced: $FILE"
  done
done

NEVER use these commands

# These commands are FORBIDDEN:
cp -r magic_development/* magic_brinxx/
cp -r magic_development/storefront/ magic_brinxx/storefront/
rsync -av magic_development/ magic_brinxx/
rsync -av --delete storefront/src/ target/storefront/src/

---

Rule 4: Post-Sync Verification

After syncing and rebuilding:

1. Rebuild ONLY the backend (never the storefront unless explicitly asked for that specific tenant)

   cd /mnt/data/magic_omniverse/magic_commerce/magic_brinxx
   docker compose build backend
   docker compose up -d backend

2. Check container starts successfully

   # Wait a few seconds, then check
   docker ps | grep magic_brinxx_backend_dev
   docker logs magic_brinxx_backend_dev --tail=30

3. Verify no startup errors — look for migration errors, missing modules, or config issues in the logs

---

Rule 5: Jodasign Special Permissions

magic_jodasign files are owned by adminwayne3. All file operations require sudo:

# Copy with sudo
sudo cp "$SOURCE/$FILE" "/mnt/data/magic_omniverse/magic_commerce/magic_jodasign/$FILE"

# Fix ownership after copy
sudo chown adminwayne3:adminwayne3 "/mnt/data/magic_omniverse/magic_commerce/magic_jodasign/$FILE"

Note

Forgetting to fix ownership will cause permission errors when the jodasign container tries to read the files.

---

Rule 6: Database Migration Safety

• NEVER auto-run migrations on tenant databases
• NEVER sync migration files between tenants
• Each tenant’s database may have different schemas or custom tables
• Always create a backup before any migration:

# Backup specific tenant database
docker exec magic_pim_postgres_dev pg_dump -U postgres \
  -d magic_b2b_brinxx > /tmp/backup_brinxx_$(date +%Y%m%d_%H%M).sql

---

Rule 7: Tenant-Specific Configuration Files

These files are unique per tenant and must NEVER be overwritten:

File	Contains
.env / .env.*	Database URL, API keys, publishable keys
docker-compose.yml	Ports, volumes, container names, theme config
medusa-config.js/ts	Database connection, plugins, tenant-specific settings
storefront/*	Entire storefront — unique design per tenant
package.json	Can have tenant-specific dependencies

---

Rule 8: When In Doubt — STOP and ASK

• Not sure if a file is tenant-specific? Ask first
• Syncing more than 5 files? Ask for confirmation
• Syncing a new path/directory not synced before? Ask first
• Diff shows the target file differs from development? Report the difference and ask

---

Tenant Architecture Reference

Port Mapping

Tenant	Backend	Storefront	Redis	Admin
Development	4010	10010	6310	7010
Bovisales	4020	10020	6320	7020
Default	4030	10030	6330	7030
Brinxx	4040	10040	6340	7040
Logohorloge	4050	10050	6350	7050
Demo	4060	10060	6360	7060
Spranz	4070	10070	6370	7070
De Sluis	4080	10080	6380	7080
Jodasign	4091	10091	6391	7091

Database Mapping

Each tenant has its own PostgreSQL database:

magic_b2b_development    ← Development/testing
magic_b2b_brinxx         ← Brinxx production
magic_b2b_default        ← Default store
magic_b2b_logohorloge    ← Logohorloge
magic_b2b_bovisales      ← Bovisales
magic_b2b_demo           ← Demo environment
magic_b2b_desluis        ← De Sluis
magic_b2b_jodasign       ← Jodasign

Sync Flow Diagram

┌─────────────────────────────────────┐
│        magic_development            │
│        (Master Tenant)              │
│                                     │
│  backend/src/  ← All changes here   │
│  storefront/   ← Dev design only    │
└───────────┬─────────────────────────┘
            │
            │  ONLY backend/src/ files
            │  (never storefront!)
            │
    ┌───────┼───────┬───────┬─────────┐
    ▼       ▼       ▼       ▼         ▼
 brinxx  default  logo   bovisales  demo ...
 (own     (own     (own    (own      (own
 design)  design)  design) design)   design)

---

Quick Reference Checklist

Use this checklist before every sync operation:

SYNC CHECKLIST:
[ ] Only backend files? (NEVER storefront!)
[ ] Specific files listed? (no wildcard copies)
[ ] Development tested and running?
[ ] Diff checked for tenant-specific changes?
[ ] Backups created for target files?
[ ] User confirmed the sync?
[ ] After sync: backend-only rebuild?
[ ] After rebuild: container health verified?
[ ] Jodasign: sudo + chown used?

---

Adding a New User

When a new admin user is created on the server:

# Copy the CLAUDE.md template to the new user
sudo cp /mnt/data/magic_omniverse/CLAUDE_TEMPLATE.md /home/<newuser>/CLAUDE.md
sudo chown <newuser>:<newuser> /home/<newuser>/CLAUDE.md

Updating Guardrails

To update the guardrails for all users at once, edit the shared file:

# Edit the single source-of-truth
nano /mnt/data/magic_omniverse/CLAUDE_GUARDRAILS.md

# The per-user CLAUDE.md files reference this automatically

For major changes, also update the template:

nano /mnt/data/magic_omniverse/CLAUDE_TEMPLATE.md

---

Complete File: CLAUDE.md (Main - adminmichiel1)

Note

This is the full CLAUDE.md deployed at /home/adminmichiel1/CLAUDE.md. It is the most comprehensive version with all system details. Other users receive the template version (see below).

File location: /home/adminmichiel1/CLAUDE.md

# Magic e-VERSE Server - Claude Code Instructies

## VERPLICHTE WORKFLOW REGELS - NA ELKE FEATURE/WIJZIGING

**Deze regels zijn NIET optioneel. Ze MOETEN altijd worden uitgevoerd na elke significante code wijziging.**

### 1. Dev Projects Changelog bijwerken
Na elke feature, bugfix of wijziging MOET je het registreren in Dev Projects:
- Maak een nieuw project aan als er nog geen bestaat voor de taak
- Voeg changelog entries toe (create/modify/deploy) via de API
- Registreer alle gewijzigde/nieuwe bestanden via de files API
- Zie sectie "Dev Projects" hieronder voor API commando's

### 2. Dev Documentatie bijwerken
Na elke significante feature of API wijziging MOET de Starlight documentatie worden bijgewerkt:
- Update relevante pagina's in `/mnt/data/magic_omniverse/magic_docs/starlight/src/content/docs/`
- Voeg nieuwe pagina's toe aan de sidebar in `astro.config.mjs` (indien nodig)
- Rebuild & deploy: `cd /mnt/data/magic_omniverse/magic_docs/starlight && npm run build`
- Dit geldt voor: nieuwe API endpoints, nieuwe features, architectuur wijzigingen, integraties

### 3. Code distribueren naar alle tenants
Na elke wijziging in `magic_development` MOET de code naar alle 7 andere tenants worden gekopieerd:
- **VOLG ALTIJD de guardrails in `/mnt/data/magic_omniverse/CLAUDE_GUARDRAILS.md`**
- **NOOIT storefronts/frontends syncen** - alleen backend code!
- Kopieer gewijzigde **backend** bestanden naar alle tenants (brinxx, default, logohorloge, bovisales, demo, desluis, jodasign)
- Maak altijd backups van target bestanden voor overschrijven
- Let op: `magic_jodasign` heeft vaak sudo nodig (adminwayne3 ownership)
- Rebuild minstens development + brinxx backends
- Verifieer container status na rebuild

---

## Systeem Architectuur Overzicht

```
Magic e-Verse Ecosystem
├── Portal (portal.magiceverse.online) - Centraal dashboard
├── PIM (pim.magiceverse.online) - Product Information Management
├── E-commerce Tenants (8 stuks) - Medusa webshops
├── Agents - AI assistenten
└── Beta Server (beta.brinxx.nl) - Test omgeving
```

---

## Alle Websites & Services

### Portals & Dashboards
| Service | URL | Locatie | Functie |
|---------|-----|---------|---------|
| Magic Portal | portal.magiceverse.online | `/mnt/data/magic_omniverse/magic_portal/` | Centraal dashboard, tenant manager, documentatie |
| Dashboard | dashboard.magiceverse.online | `/mnt/data/magic_omniverse/magic_dashboard/` | Dev projects API, monitoring |

### PIM (Product Information Management)
| Service | URL | Locatie | Functie |
|---------|-----|---------|---------|
| Magic PIM | pim.magiceverse.online | `/mnt/data/magic_pim/` | Master product database, tenant sync |

### E-commerce Tenants (Medusa 2.0)
| Tenant | Admin URL | Storefront URL | Locatie |
|--------|-----------|----------------|---------|
| Development | admin-development.magiceverse.online | - | `/mnt/data/magic_omniverse/magic_commerce/magic_development/` |
| Brinxx | admin-brinxx.magiceverse.online | brinxx.magiceverse.online | `/mnt/data/magic_omniverse/magic_commerce/magic_brinxx/` |
| Default | admin-default.magiceverse.online | default.magiceverse.online | `/mnt/data/magic_omniverse/magic_commerce/magic_default/` |
| Logohorloge | admin-logohorloge.magiceverse.online | logohorloge.magiceverse.online | `/mnt/data/magic_omniverse/magic_commerce/magic_logohorloge/` |
| Bovisales | admin-bovisales.magiceverse.online | bovisales.magiceverse.online | `/mnt/data/magic_omniverse/magic_commerce/magic_bovisales/` |
| Demo | admin-demo.magiceverse.online | demo.magiceverse.online | `/mnt/data/magic_omniverse/magic_commerce/magic_demo/` |
| De Sluis | admin-desluis.magiceverse.online | desluis.magiceverse.online | `/mnt/data/magic_omniverse/magic_commerce/magic_desluis/` |
| Jodasign | admin-jodasign.magiceverse.online | jodasign.magiceverse.online | `/mnt/data/magic_omniverse/magic_commerce/magic_jodasign/` |

### Beta Server (Extern)
| Service | URL | SSH | Locatie |
|---------|-----|-----|---------|
| Beta Brinxx | beta.brinxx.nl | `ssh beta-brinxx` (37.97.132.23) | `/var/www/brinxx.nl/` |

---

## Folder Structuur

```
/mnt/data/
├── magic_pim/                    # PIM systeem (master products)
│   ├── backend/                  # Medusa backend
│   └── storefront/               # Next.js frontend
│
├── magic_omniverse/
│   ├── magic_portal/             # Centraal portal (Vite + React)
│   ├── magic_dashboard/          # Dashboard API
│   └── magic_commerce/           # Alle e-commerce tenants
│       ├── magic_development/    # BASIS voor code distributie!
│       ├── magic_brinxx/
│       ├── magic_default/
│       ├── magic_logohorloge/
│       ├── magic_bovisales/
│       ├── magic_demo/
│       ├── magic_desluis/
│       └── magic_jodasign/
│
├── pim_data/                     # Product afbeeldingen
│   ├── spranz/                   # Spranz leverancier images
│   ├── langenberg/               # Langenberg leverancier images
│   └── svg/                      # SVG logo's
│
└── brinxx_invoices/              # Facturen opslag
```

---

## Code Distributie Workflow

> **LEES EERST:** Alle sync guardrails staan in `/mnt/data/magic_omniverse/CLAUDE_GUARDRAILS.md`
> **Deze regels zijn VERPLICHT en moeten ALTIJD worden gevolgd bij elke sync operatie.**

### KRITIEKE REGELS (samenvatting)

1. **NOOIT STOREFRONTS SYNCEN** - Elke tenant heeft een uniek design. Alleen `backend/` code syncen!
2. **Specifieke bestanden benoemen** - Geen wildcard copies van hele mappen
3. **Altijd backups maken** van target bestanden voor overschrijven
4. **Altijd diff checken** voor tenant-specifieke wijzigingen
5. **Jodasign** vereist `sudo` (adminwayne3 ownership)
6. **Bij twijfel: STOP en VRAAG**

### Workflow

1. Ontwikkel in `magic_development`
2. Test lokaal (controleer dat development container draait)
3. Kopieer **alleen backend bestanden** naar andere tenants:
```bash
SOURCE="/mnt/data/magic_omniverse/magic_commerce/magic_development"
TENANTS="magic_brinxx magic_default magic_logohorloge magic_bovisales magic_demo magic_desluis magic_jodasign"
FILE="backend/src/api/admin/aplt/orders/pdf/route.ts"

for tenant in $TENANTS; do
  TARGET="/mnt/data/magic_omniverse/magic_commerce/$tenant"
  [ -f "$TARGET/$FILE" ] && cp "$TARGET/$FILE" "$TARGET/$FILE.bak_$(date +%Y%m%d_%H%M%S)"
  cp "$SOURCE/$FILE" "$TARGET/$FILE"
  echo "Synced $FILE to $tenant"
done
```

4. Rebuild **alleen de backend** (NOOIT de storefront):
```bash
cd /mnt/data/magic_omniverse/magic_commerce/magic_brinxx
docker compose build backend
docker compose up -d backend
```

5. Verifieer na rebuild:
```bash
docker ps | grep magic_brinxx_backend_dev
docker logs magic_brinxx_backend_dev --tail=20
```

---

## Databases

### PostgreSQL (magic_pim_postgres_dev)
| Database | Functie |
|----------|---------|
| magic_pim | Master product data |
| magic_b2b_brinxx | Brinxx tenant data |
| magic_b2b_default | Default tenant data |
| magic_b2b_logohorloge | Logohorloge tenant data |
| etc... | Elke tenant heeft eigen database |

### MySQL (mysql container)
| Database | Functie |
|----------|---------|
| magic_doc | Portal documentatie |
| aplt_flow | Workflow data |

### Backup Commando's
```bash
# PostgreSQL
docker exec magic_pim_postgres_dev pg_dumpall -U postgres > /tmp/postgres_backup_$(date +%Y%m%d_%H%M).sql

# MySQL
docker exec mysql mysqldump -uroot -p<your-db-password> --all-databases > /tmp/mysql_backup_$(date +%Y%m%d_%H%M).sql
```

---

## Docker Containers

### Per Tenant
- `magic_<tenant>_backend_dev` - Medusa backend (port 4040+)
- `magic_<tenant>_storefront_dev` - Next.js storefront (port 10040+)
- `magic_<tenant>_redis_dev` - Redis cache

### Shared
- `magic_pim_postgres_dev` - PostgreSQL database
- `mysql` - MySQL database

### Handige Commando's
```bash
# Status alle containers
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

# Logs bekijken
docker logs magic_brinxx_backend_dev --tail=50 -f

# Rebuild specifieke tenant
cd /mnt/data/magic_omniverse/magic_commerce/magic_brinxx
docker compose build backend --no-cache
docker compose up -d backend
```

---

## Product Afbeeldingen

### Structuur
```
/mnt/data/pim_data/
├── spranz/           # Spranz producten (bijv. spranz/5325-00.001.jpg)
├── langenberg/       # Langenberg producten
└── svg/              # SVG logo's voor personalisatie
```

### Conventies
- **Lowercase extensies:** altijd `.jpg` niet `.JPG`
- **Pad formaat:** `supplier/sku.jpg` (bijv. `spranz/5325-00.001.jpg`)
- **Database opslag:** Relatief pad zonder leading slash

---

## APLT Module (Orders, Offertes, Facturen)

### Belangrijke API Routes
```
/admin/aplt/orders          - Orders beheer
/admin/aplt/orders/pdf      - Order PDF generatie
/admin/aplt/quotations      - Offertes beheer
/admin/aplt/quotations/pdf  - Offerte PDF generatie
/admin/aplt/invoices        - Facturen
```

### Database Tabellen
- `aplt_order_headers` / `aplt_order_lines`
- `aplt_quotation_headers` / `aplt_quotation_lines`
- `aplt_invoice_headers` / `aplt_invoice_lines`
- `aplt_brands` - Merken configuratie
- `aplt_cms_settings` - CMS instellingen per brand

---

## Dev Projects (Magic DEV App)

### Via Portal
https://admin-development.magiceverse.online/app/settings/dev-projects

### Via API
```bash
# Nieuw project
curl -X POST "https://admin-development.magiceverse.online/admin/dev-projects" \
  -H "Content-Type: application/json" \
  -d '{"name": "Feature naam", "description": "Beschrijving", "project_type": "feature"}'

# Bestanden toevoegen
curl -X POST "https://admin-development.magiceverse.online/admin/dev-projects/files" \
  -H "Content-Type: application/json" \
  -d '{"project_id": <ID>, "files": [{"file_path": "...", "change_type": "modified"}]}'

# Changelog
curl -X POST "https://admin-development.magiceverse.online/admin/dev-projects/changelog" \
  -H "Content-Type: application/json" \
  -d '{"project_id": <ID>, "action": "modify", "description": "...", "changed_by": "claude"}'
```

---

## Beta Server (beta.brinxx.nl)

### Connectie
```bash
ssh beta-brinxx
# of
ssh ubuntu@37.97.132.23
```

### Paden
- Code: `/var/www/brinxx.nl/`
- Images: `/mnt/data/pim_data/`

### Rebuild
```bash
ssh beta-brinxx "cd /var/www/brinxx.nl && docker compose build backend && docker compose up -d backend"
```

---

## VERBODEN

- **NOOIT** direct op main/master branch werken
- **NOOIT** `docker rm` op database containers zonder backup
- **NOOIT** credentials in code committen
- **NOOIT** force push naar production branches

---

## Handige One-liners

```bash
# Check alle tenant containers
docker ps | grep magic_

# Rebuild alle backends (VOORZICHTIG!)
for d in /mnt/data/magic_omniverse/magic_commerce/*/; do
  cd "$d" && docker compose build backend && docker compose up -d backend
done

# Check disk space
df -h /mnt/data

# Zoek bestand in alle tenants
find /mnt/data/magic_omniverse/magic_commerce -name "route.ts" | grep pdf

# Database query (PostgreSQL)
docker exec magic_pim_postgres_dev psql -U postgres -d magic_b2b_brinxx -c "SELECT * FROM aplt_brands;"
```

---

## Documentatie

- **Dev Docs (Astro Starlight):** https://devdocs.magiceverse.online
- Portal Docs: https://portal.magiceverse.online/documentation/
- Dev Projects: https://portal.magiceverse.online/documentation/?doc=magic-dev-projects

---

## BELANGRIJKE DATA CONVENTIES - SPRANZ

### aplt_products Tabel Structuur (magic_spranz_logo database)
**KRITISCH:** De `sku` en `variant_code` velden hebben specifieke betekenissen:

| Veld | Betekenis | Voorbeeld |
|------|-----------|-----------|
| `sku` | **Base SKU** (zonder variant suffix) | `376-00` |
| `variant_code` | **Volledige variant code** (met suffix) | `376-00.001` |

**CORRECT:**
```sql
sku = '376-00'
variant_code = '376-00.001'
svg_path = 'svg/spranz/'
```

**FOUT (niet doen!):**
```sql
sku = '1701-00.001'  -- FOUT! Dit is een variant_code, niet base SKU
variant_code = ''    -- FOUT! Leeg terwijl het een variant is
```

### SVG Bestandsnamen
- SVG bestanden worden opgeslagen als: `{variant_code}.svg`
- Voorbeeld: `376-00.001.svg`, `376-00.002.svg`
- Base SKU SVG: `{sku}.svg` -> `376-00.svg`

### Designer Frontend Logica
De designer zoekt SVG's op basis van:
1. Eerst: `/{svg_path}/{sku}.{variant}.svg` (bijv. `/svg/spranz/376-00.001.svg`)
2. Fallback: `/{svg_path}/{sku}.svg` (bijv. `/svg/spranz/376-00.svg`)

---

## Bij Twijfel: VRAAG EERST!

---

Complete File: CLAUDE_GUARDRAILS.md

Danger

This is the single source-of-truth for all sync rules. All users reference this file. Edit this file to update rules for everyone.

File location: /mnt/data/magic_omniverse/CLAUDE_GUARDRAILS.md

# Magic e-VERSE Guardrails - Verplicht voor alle gebruikers

> Dit bestand is de single source-of-truth voor sync & deployment regels.
> Locatie: `/mnt/data/magic_omniverse/CLAUDE_GUARDRAILS.md`

---

## SYNC GUARDRAILS - ABSOLUUT VERPLICHT

### REGEL 1: NOOIT STOREFRONTS/FRONTENDS SYNCEN

**Dit is de belangrijkste regel. NOOIT overtreden.**

- **NOOIT** de `storefront/` map kopieren van de ene tenant naar de andere
- **NOOIT** frontend bestanden (Next.js, React componenten, CSS, thema's) syncen tussen tenants
- Elke tenant heeft zijn **eigen unieke design, branding, thema en configuratie**
- Alleen `backend/` code mag worden gesynchroniseerd tussen tenants

**Waarom:** Elke tenant heeft een eigen storefront design. In het verleden is het voorgekomen dat alle tenants het Brinxx design kregen door foutief frontend syncen. Dit is een kritieke fout die direct zichtbaar is voor eindgebruikers.

**Wat WEL mag worden gesynchroniseerd (alleen backend):**
```
backend/src/api/          # API routes
backend/src/modules/      # Custom modules
backend/src/jobs/         # Background jobs
backend/src/subscribers/  # Event subscribers
backend/src/workflows/    # Medusa workflows
backend/src/utils/        # Utility functies
backend/src/links/        # Module links
backend/src/admin/        # Admin UI extensies (ALLEEN als ze tenant-onafhankelijk zijn)
```

**Wat NOOIT mag worden gesynchroniseerd:**
```
storefront/               # NOOIT - uniek design per tenant
backend/.env              # NOOIT - tenant-specifieke configuratie
backend/.env.*            # NOOIT - environment varianten
docker-compose.yml        # NOOIT - tenant-specifieke setup
docker-compose.prod.yml   # NOOIT - tenant-specifieke productie config
node_modules/             # NOOIT - wordt lokaal geinstalleerd
backend/medusa-config.*   # NOOIT - tenant-specifieke Medusa config
migrations/               # NOOIT - database migraties apart beheren
```

---

### REGEL 2: PRE-SYNC CHECKLIST

Voordat je code synchroniseert van `magic_development` naar andere tenants, MOET je:

1. **Bevestig dat development draait en getest is**
   ```bash
   docker ps | grep magic_development_backend_dev
   # Controleer of container healthy is
   ```

2. **Maak een lijst van EXACT welke bestanden je gaat syncen**
   - Noem elk bestand expliciet - geen wildcard copies van hele mappen
   - Vraag bevestiging aan de gebruiker voordat je kopieert

3. **Controleer of bestanden tenant-specifieke aanpassingen bevatten**
   ```bash
   # Vergelijk eerst het bestand in development vs target tenant
   diff /mnt/data/magic_omniverse/magic_commerce/magic_development/backend/src/path/file.ts \
        /mnt/data/magic_omniverse/magic_commerce/magic_brinxx/backend/src/path/file.ts
   ```

4. **Maak backup van target bestanden**
   ```bash
   # Backup VOOR overschrijven
   cp target_file.ts target_file.ts.bak_$(date +%Y%m%d_%H%M%S)
   ```

---

### REGEL 3: SYNC COMMANDO TEMPLATE

Gebruik ALTIJD dit patroon voor het syncen van backend code:

```bash
# CORRECT: Specifieke bestanden syncen (ALLEEN backend)
SOURCE="/mnt/data/magic_omniverse/magic_commerce/magic_development"
TENANTS="magic_brinxx magic_default magic_logohorloge magic_bovisales magic_demo magic_desluis magic_jodasign"
FILE="backend/src/api/admin/aplt/orders/route.ts"

for tenant in $TENANTS; do
  TARGET="/mnt/data/magic_omniverse/magic_commerce/$tenant"
  # Backup eerst
  if [ -f "$TARGET/$FILE" ]; then
    cp "$TARGET/$FILE" "$TARGET/$FILE.bak_$(date +%Y%m%d_%H%M%S)"
  fi
  # Kopieer
  cp "$SOURCE/$FILE" "$TARGET/$FILE"
  echo "Synced $FILE to $tenant"
done
```

```bash
# FOUT - DOE DIT NOOIT:
cp -r magic_development/* magic_brinxx/          # Kopieert ALLES inclusief storefront!
cp -r magic_development/storefront/ magic_brinxx/ # Overschrijft tenant design!
rsync -av magic_development/ magic_brinxx/        # Synct ALLES!
```

---

### REGEL 4: POST-SYNC VERIFICATIE

Na het syncen en rebuilden:

1. **Rebuild alleen de backend** (NOOIT de storefront tenzij expliciet gevraagd voor die specifieke tenant)
   ```bash
   cd /mnt/data/magic_omniverse/magic_commerce/magic_brinxx
   docker compose build backend
   docker compose up -d backend
   ```

2. **Check container status**
   ```bash
   docker ps | grep magic_brinxx_backend_dev
   # Wacht 10 seconden, check opnieuw
   docker logs magic_brinxx_backend_dev --tail=20
   ```

3. **Basis health check**
   ```bash
   curl -s http://localhost:<PORT>/health | head -5
   ```

---

### REGEL 5: JODASIGN SPECIALE PERMISSIES

- `magic_jodasign` bestanden zijn eigendom van `adminwayne3`
- Gebruik `sudo` voor kopieer operaties naar jodasign
- Verifieer permissies na kopieren:
  ```bash
  sudo cp "$SOURCE/$FILE" "/mnt/data/magic_omniverse/magic_commerce/magic_jodasign/$FILE"
  sudo chown adminwayne3:adminwayne3 "/mnt/data/magic_omniverse/magic_commerce/magic_jodasign/$FILE"
  ```

---

### REGEL 6: DATABASE MIGRATIES

- **NOOIT** automatisch migraties uitvoeren op tenant databases
- **NOOIT** migratie bestanden syncen tussen tenants
- Migraties moeten **per tenant** worden beoordeeld en expliciet goedgekeurd
- Maak ALTIJD een database backup voor migraties:
  ```bash
  docker exec magic_pim_postgres_dev pg_dump -U postgres -d magic_b2b_<tenant> > /tmp/backup_<tenant>_$(date +%Y%m%d_%H%M).sql
  ```

---

### REGEL 7: CONFIGURATIE BESTANDEN

De volgende bestanden zijn **tenant-specifiek** en mogen NOOIT worden overschreven:

| Bestand | Reden |
|---------|-------|
| `.env` / `.env.*` | Database credentials, API keys, tenant ID |
| `docker-compose.yml` | Poorten, volumes, container namen |
| `medusa-config.js/ts` | Database URL, tenant-specifieke plugins |
| `storefront/*` | Uniek design en branding per tenant |
| `package.json` | Kan tenant-specifieke dependencies bevatten |

---

### REGEL 8: BIJ TWIJFEL - STOP EN VRAAG

- Als je niet zeker weet of een bestand tenant-specifiek is: **VRAAG**
- Als een sync meer dan 5 bestanden betreft: **VRAAG bevestiging**
- Als je een nieuw pad/map moet syncen dat niet eerder gesynchroniseerd is: **VRAAG**
- Als een diff laat zien dat het target bestand afwijkt van development: **MELD dit en VRAAG**

---

## QUICK REFERENCE

```
SYNC CHECKLIST:
[ ] Alleen backend bestanden? (NOOIT storefront!)
[ ] Specifieke bestanden benoemd? (geen wildcard copies)
[ ] Development getest en werkend?
[ ] Backups gemaakt van target bestanden?
[ ] Diff gecheckt voor tenant-specifieke wijzigingen?
[ ] Gebruiker heeft bevestigd?
[ ] Na sync: backend rebuild + health check?
[ ] Jodasign: sudo + chown gebruikt?
```

---

Complete File: CLAUDE_TEMPLATE.md

Note

This is the template deployed to all user home directories. It is a condensed version that references the shared guardrails file.

File location: /mnt/data/magic_omniverse/CLAUDE_TEMPLATE.md Deployed to: /home/<user>/CLAUDE.md for all users

# Magic e-VERSE Server - Claude Code Instructies

## VERPLICHT: Lees de Guardrails

> **Voor ELKE sync/deployment operatie, lees en volg:**
> `/mnt/data/magic_omniverse/CLAUDE_GUARDRAILS.md`

---

## KRITIEKE REGELS (altijd van toepassing)

1. **NOOIT storefronts/frontends syncen** tussen tenants - elke tenant heeft een uniek design
2. **Alleen backend code syncen** - specifieke bestanden, geen wildcard copies
3. **Altijd backups maken** voor je bestanden overschrijft
4. **NOOIT** `.env`, `docker-compose.yml`, `medusa-config.*` of `storefront/` syncen
5. **NOOIT** direct op main/master branch werken
6. **NOOIT** `docker rm` op database containers zonder backup
7. **NOOIT** credentials in code committen
8. **NOOIT** force push naar production branches
9. **Bij twijfel: STOP en VRAAG**

---

## Systeem Overzicht

- **Tenants:** development (master), brinxx, default, logohorloge, bovisales, demo, desluis, jodasign
- **Tenant locatie:** `/mnt/data/magic_omniverse/magic_commerce/magic_<tenant>/`
- **PIM:** `/mnt/data/magic_pim/`
- **Portal:** `/mnt/data/magic_omniverse/magic_portal/`
- **Documentatie:** `/mnt/data/magic_omniverse/magic_docs/starlight/`
- **Product images:** `/mnt/data/pim_data/`

---

## Code Sync Workflow (alleen backend!)

```bash
# 1. Ontwikkel in magic_development
# 2. Test dat development container draait
docker ps | grep magic_development_backend_dev

# 3. Sync SPECIFIEKE backend bestanden
SOURCE="/mnt/data/magic_omniverse/magic_commerce/magic_development"
TENANTS="magic_brinxx magic_default magic_logohorloge magic_bovisales magic_demo magic_desluis magic_jodasign"
FILE="backend/src/path/to/file.ts"

for tenant in $TENANTS; do
  TARGET="/mnt/data/magic_omniverse/magic_commerce/$tenant"
  [ -f "$TARGET/$FILE" ] && cp "$TARGET/$FILE" "$TARGET/$FILE.bak_$(date +%Y%m%d_%H%M%S)"
  cp "$SOURCE/$FILE" "$TARGET/$FILE"
done

# 4. Rebuild ALLEEN backend (NOOIT storefront)
cd /mnt/data/magic_omniverse/magic_commerce/magic_brinxx
docker compose build backend && docker compose up -d backend

# 5. Verifieer
docker logs magic_brinxx_backend_dev --tail=20
```

**Jodasign:** Gebruik `sudo` voor kopieren + `sudo chown adminwayne3:adminwayne3`

---

## Databases

- **PostgreSQL container:** `magic_pim_postgres_dev`
- **Backup:** `docker exec magic_pim_postgres_dev pg_dump -U postgres -d magic_b2b_<tenant> > /tmp/backup.sql`
- **NOOIT** automatisch migraties uitvoeren op tenant databases

---

## Dev Projects & Documentatie

Na elke feature/wijziging:
1. Registreer in Dev Projects via portal of API
2. Update Starlight docs in `/mnt/data/magic_omniverse/magic_docs/starlight/`
3. Rebuild docs: `cd /mnt/data/magic_omniverse/magic_docs/starlight && npm run build`

---

## Volledige Guardrails

Zie `/mnt/data/magic_omniverse/CLAUDE_GUARDRAILS.md` voor alle details over:
- Pre-sync checklist
- Post-sync verificatie
- Database migratie regels
- Configuratie bestanden die NOOIT gesynchroniseerd mogen worden
- Jodasign permissie regels