CLAUDE.md Per Repository

Why Per-Repo CLAUDE.md?

With the migration to Coolify (March 2026), development moved from direct server editing to GitHub-based deployments. Each repository now has its own CLAUDE.md that gives Claude Code the context it needs when working in that repo.

Old Workflow (deprecated)

Edit files on server → copy to 7 tenants → docker compose rebuild

New Workflow

Work in GitHub repo → push to main → Coolify auto-deploys all tenants

Three-Layer Strategy

Layer	Location	What It Contains
Ecosystem guide	`~/CLAUDE.md` (home directory)	Server access, which repo for what, shared conventions
Repo-specific	`<repo>/CLAUDE.md`	That repo’s structure, tech stack, deployment, patterns
External customer	On customer’s server	Server-specific paths, credentials, deploy process

Summary Table

Repo	Type	URL	Database
Magic-e-VERSE	Commerce platform	`admin-*.magicomniverse.online`	`magic_b2b_*` (per tenant)
Magic-PIM	Product management	`pim.magicomniverse.online`	`magic_pim`
Magic-Portal	Dashboard	`portal.magicomniverse.online`	SQLite + MySQL
Magic-Monitor	Monitoring	`monitor.magicomniverse.online`	`magic_monitor`
Magic-Agent	AI agents	`agent-*.magicomniverse.online`	`magic_agent_*`
Magic-Logo	Logo designer	`logo.magicomniverse.online`	`magic_*_logo`
Magic-Modal	Logo modal	`modal.magicomniverse.online`	—
Magic-3D	3D viewer	`3d.magicomniverse.online`	—
Magic-Editor	Image editor	`editor.magicomniverse.online`	—
Magic-Moodshot	AI images	`moodshot.magicomniverse.online`	`moodshot_service`
Magic-Resize	Image resize	`resize.magicomniverse.online`	—
Magic-Connector	FastEditor	internal	`magic_connector`
Magic-Contact	Lead capture	internal	`magic_contact`
Magic-Price-Import	Price import	`price-import.magicomniverse.online`	—
Magic-Terminal	SSH terminal	`terminal.magicomniverse.online`	—

Coolify Deployment Overview

All repos deploy via Coolify at coolify.magicomniverse.online.

Push to GitHub (main branch)
        │
        ▼
Coolify detects change (GitHub App webhook)
        │
        ▼
Coolify builds Docker image (from repo's Dockerfile)
        │
        ▼
Coolify deploys container (Traefik routes traffic via subdomain)
        │
        ▼
Live at *.magicomniverse.online

Item	Value
Dashboard	`coolify.magicomniverse.online`
Server	`159.195.68.41` (`ssh magicomniverse`)
GitHub App	`magic-everse-coolify`
Proxy	Traefik v3.6
Registry	Local Docker registry on port 5000
PostgreSQL	`magic-postgres` (postgres:16-alpine) — 55 databases
MySQL	`mysql` (mysql:8.0) — 5 databases

Full CLAUDE.md Contents Per Repository

Below is the complete content of every CLAUDE.md file across the platform.

1. Magic-e-VERSE (Main Repo)

File: Magic-e-VERSE/CLAUDE.md Repo: github.com/midego1/Magic-e-VERSE Deploys: All 12 commerce tenant backends + storefronts

# Magic e-VERSE — Development Guide

## Architecture Overview

Magic e-VERSE is a **multi-tenant B2B e-commerce platform** built on Medusa v2. One codebase serves all tenants — each tenant gets its own Coolify deployment with different env vars, database, and theme.

```
Magic e-VERSE Ecosystem
├── Magic-e-VERSE (this repo)     — Core: Medusa backend + Next.js storefront
├── Magic-PIM                     — Master product database
├── Magic-Monitor                 — Tenant Pulse platform monitor
├── Magic-Portal                  — Central dashboard & tenant manager
├── Magic-Agent                   — AI chatbot agents (per-tenant)
├── Magic-Logo                    — 2D logo designer/configurator
├── Magic-Modal                   — Embeddable logo editing modal (Fabric.js)
├── Magic-3D                      — 3D product viewer & logo placement
├── Magic-Editor                  — Image editor (miniPaint-based)
├── Magic-Moodshot                — AI product lifestyle image generator
├── Magic-Resize                  — Batch image resize tool
├── Magic-Connector               — FastEditor integration bridge
├── Magic-Contact                 — Contact & lead capture
├── Magic-Terminal                — Web-based SSH (Sshwifty)
└── Magic-Price-Import            — Supplier price data import
```

All repos live under `github.com/midego1/` and deploy via **Coolify** on `magicomniverse` (159.195.68.41).

---

## When to Work in Which Repo

| If you're changing... | Work in |
|---|---|
| Backend APIs, admin pages, order/quotation/invoice logic | **Magic-e-VERSE** `backend/` |
| Storefront pages, checkout, product display, theming | **Magic-e-VERSE** `storefront/` |
| Agent AI behavior, flow builder, escalation | **Magic-Agent** |
| Master product catalog, PIM sync | **Magic-PIM** |
| Platform monitoring, health checks | **Magic-Monitor** |
| Central portal, tenant management | **Magic-Portal** |
| Logo designer (2D placement, techniques, SVG) | **Magic-Logo** |
| Logo modal widget (embedded in storefronts) | **Magic-Modal** |
| 3D product viewer | **Magic-3D** |
| Image editing capabilities | **Magic-Editor** |
| Product moodshot/lifestyle images | **Magic-Moodshot** |
| Image resizing | **Magic-Resize** |
| FastEditor connector | **Magic-Connector** |
| Contact forms, lead capture | **Magic-Contact** |
| Supplier price imports | **Magic-Price-Import** |
| SSH terminal access | **Magic-Terminal** |

**Rule of thumb:** If it's about commerce (products, orders, customers, storefront), it's this repo. If it's a standalone tool, it's its own repo.

---

## This Repo Structure

```
Magic-e-VERSE/
├── backend/                  # Medusa v2.11.3 backend
│   ├── src/
│   │   ├── admin/            # Custom admin UI (routes, widgets, i18n)
│   │   │   └── routes/       # 17 admin pages, numbered for sidebar order
│   │   ├── api/
│   │   │   ├── admin/aplt/   # APLT module (orders, quotations, invoices, PDF)
│   │   │   ├── admin/        # CMS, brand wizard, connectors, dev-projects, menu
│   │   │   ├── store/        # Customer-facing APIs (products, categories, logos)
│   │   │   └── products/     # Image serving endpoint
│   │   ├── features/         # Feature flag system (tenant licensing)
│   │   ├── modules/connectors/ # Supplier data parsers (midocean, pfconcept, spranz, toppoint, xdconnect)
│   │   ├── jobs/             # Background jobs
│   │   ├── subscribers/      # Event subscribers
│   │   └── workflows/        # Medusa workflows
│   ├── Dockerfile            # Multi-stage build (node:22-alpine)
│   └── .env.template         # Environment variable template
├── storefront/               # Next.js 15 storefront (React 19)
│   ├── src/
│   │   ├── app/              # App Router pages
│   │   ├── modules/          # UI components (products, cart, checkout, cms, etc.)
│   │   ├── themes/           # Per-tenant CSS overrides (brinxx/, default/, etc.)
│   │   └── lib/              # Utils, hooks, data fetching, i18n
│   ├── Dockerfile            # Multi-stage build with NEXT_PUBLIC_* build args
│   └── .env.template
├── magic_agent/              # Agent API stubs (minimal, main agents in Magic-Agent repo)
├── magic_beta_portal/        # Beta portal UI (Vite + React + Shadcn)
└── migrations/               # SQL migration files
```

---

## Deployment — Coolify

**All deployments go through GitHub → Coolify.** No manual file copying or docker compose on the server.

- **Coolify dashboard:** https://coolify.magicomniverse.online
- **Server:** `ssh magicomniverse` (159.195.68.41, root)
- **GitHub App:** `magic-everse-coolify` (auto-deploys on push)

### Workflow
1. Develop on a feature branch
2. Push to GitHub
3. Merge to `main`
4. Coolify auto-deploys all tenant instances from `main`

### Tenants on Coolify

Each tenant has a **backend** + **storefront** + **redis** deployment, all from this repo:

| Tenant | Admin URL | Storefront URL | Database |
|---|---|---|---|
| development | admin-development.magicomniverse.online | development.magicomniverse.online | magic_b2b_development |
| brinxx | admin-brinxx.magicomniverse.online | brinxx.magicomniverse.online | magic_b2b_brinxx |
| default | admin-default.magicomniverse.online | default.magicomniverse.online | magic_b2b_default |
| bovisales | admin-bovisales.magicomniverse.online | bovisales.magicomniverse.online | magic_b2b_bovisales |
| demo | admin-demo.magicomniverse.online | demo.magicomniverse.online | magic_b2b_demo |
| desluis | admin-desluis.magicomniverse.online | desluis.magicomniverse.online | magic_b2b_desluis |
| jodasign | admin-jodasign.magicomniverse.online | jodasign.magicomniverse.online | magic_b2b_jodasign |
| logohorloge | admin-logohorloge.magicomniverse.online | logohorloge.magicomniverse.online | magic_b2b_logohorloge |
| mondial | admin-mondial.magicomniverse.online | mondial.magicomniverse.online | magic_b2b_mondial |
| spranz | admin-spranz.magicomniverse.online | spranz.magicomniverse.online | magic_b2b_spranz |
| toolvizion | (backend only) | (backend only) | magic_b2b_toolvizion |
| master | admin-master.magicomniverse.online | — | master_magic |

### Tenant Differentiation

Tenants share the same codebase. Differences come from:
- **Environment variables** — `DATABASE_URL`, `NEXT_PUBLIC_THEME`, `MEDUSA_BACKEND_URL`, etc.
- **Feature flags** — `backend/src/features/` controls which features each tenant has access to
- **Storefront themes** — CSS variable overrides in `storefront/src/themes/<tenant>/override.css`
- **Database content** — Each tenant has its own PostgreSQL database with different products, orders, settings

### Coolify API Tokens

| Token | Purpose |
|---|---|
| claude-api | Claude Code automation |
| claude-redeploy | Redeploy automation |
| claude-preview | Preview deployments |
| magic-monitor-api | Monitor health checks |
| deploy | General deploy |
| price-import-deploy | Price import CI |

---

## Databases

All databases run on the Coolify server (`magicomniverse`).

### PostgreSQL (`magic-postgres`, postgres:16-alpine)
- **Host (from Coolify containers):** `magic-postgres`
- **Host (from outside):** `ssh magicomniverse` then `docker exec magic-postgres psql -U postgres`
- **Credentials:** `postgres` / `<your-db-password>`
- **55 databases** including tenant DBs, agent DBs, logo DBs, and service DBs

### MySQL (`mysql`, mysql:8.0)
- **Credentials:** `root` / `<your-db-password>`
- **Databases:** magic_doc, magic_promotionalz, portal_db, uren, dartv2dev

### Key Database Tables (APLT Module)
```
aplt_order_headers / aplt_order_lines
aplt_quotation_headers / aplt_quotation_lines
aplt_invoice_headers / aplt_invoice_lines
aplt_brands
aplt_cms_settings
```

### Database Access
```bash
# From the dev server (SSH tunnel)
ssh magicomniverse "docker exec magic-postgres psql -U postgres -d magic_b2b_brinxx -c 'SELECT count(*) FROM aplt_order_headers;'"

# Backup
ssh magicomniverse "docker exec magic-postgres pg_dumpall -U postgres" > backup_$(date +%Y%m%d).sql
```

---

## Feature Flags

The feature flag system in `backend/src/features/` controls tenant licensing. Use `featureGuard` middleware on API routes to gate features per tenant.

When adding a new feature that should only be available to certain tenants:
1. Add the flag to `backend/src/features/flags.ts`
2. Wrap the API route with `featureGuard`
3. The flag is controlled per tenant via database/env configuration

**This replaces the old workflow of copying different code to different tenants.**

---

## APLT Module

The core business module for B2B operations.

### API Routes
```
/admin/aplt/orders          — Orders management
/admin/aplt/orders/pdf      — Order PDF generation
/admin/aplt/quotations      — Quotations management
/admin/aplt/quotations/pdf  — Quotation PDF generation
/admin/aplt/invoices        — Invoices
/admin/aplt/customers       — Customer management
/admin/aplt/products        — Product management
/admin/aplt/suppliers       — Supplier management
```

---

## Supplier Connectors

Backend modules for importing data from suppliers:

| Supplier | Module | Notes |
|---|---|---|
| MidOcean | `modules/connectors/midocean/` | Major supplier |
| PF Concept | `modules/connectors/pfconcept/` | Major supplier |
| Spranz | `modules/connectors/spranz/` | German supplier |
| Toppoint | `modules/connectors/toppoint/` | Dutch supplier |
| XD Connect | `modules/connectors/xdconnect/` | Includes category sync |

---

## Storefront Theming

Each tenant gets a visual theme via CSS variable overrides:

```
storefront/src/themes/
├── base/variables.css        # Base theme (all shared variables)
├── brinxx/override.css       # Brinxx overrides
├── default/override.css      # Default overrides
└── index.ts                  # Theme loader (uses NEXT_PUBLIC_THEME env var)
```

To add a new tenant theme:
1. Create `storefront/src/themes/<tenant>/override.css`
2. Register it in `storefront/src/themes/index.ts`
3. Set `NEXT_PUBLIC_THEME=<tenant>` in the Coolify deployment

---

## Data Conventions — Spranz

### aplt_products Table (magic_spranz_logo database)

| Field | Meaning | Example |
|---|---|---|
| `sku` | Base SKU (without variant suffix) | `376-00` |
| `variant_code` | Full variant code (with suffix) | `376-00.001` |

**CORRECT:** `sku = '376-00'`, `variant_code = '376-00.001'`
**WRONG:** `sku = '1701-00.001'` — this is a variant_code, not a base SKU

### SVG Files
- Stored as: `{variant_code}.svg` (e.g., `376-00.001.svg`)
- Path field: `svg_path = 'svg/spranz/'`
- Designer lookup order:
  1. `/{svg_path}/{variant_code}.svg`
  2. `/{svg_path}/{sku}.svg` (fallback)

### Product Images
- Located on Coolify server: `/mnt/data/pim_data/`
- Structure: `supplier/sku.jpg` (e.g., `spranz/5325-00.001.jpg`)
- Always lowercase extensions (`.jpg` not `.JPG`)

---

## Platform Services (Other Repos on Coolify)

| Service | URL | Repo |
|---|---|---|
| Portal | portal.magicomniverse.online | Magic-Portal |
| PIM | pim.magicomniverse.online | Magic-PIM |
| Monitor | monitor.magicomniverse.online | Magic-Monitor |
| Editor | editor.magicomniverse.online | Magic-Editor |
| Logo Designer | logo.magicomniverse.online | Magic-Logo |
| Logo Modal | modal.magicomniverse.online | Magic-Modal |
| 3D Viewer | 3d.magicomniverse.online | Magic-3D |
| Moodshot | moodshot.magicomniverse.online | Magic-Moodshot |
| Resize | resize.magicomniverse.online | Magic-Resize |
| Terminal | terminal.magicomniverse.online | Magic-Terminal |
| Price Import | price-import.magicomniverse.online | Magic-Price-Import |
| Flowbuilder | flowbuilder.magicomniverse.online | Magic-Agent |
| Escalation | escalation.magicomniverse.online | Magic-Agent |
| Agent Widget | agent.magicomniverse.online | Magic-Agent |
| n8n (main) | n8n.magicomniverse.online | — (Docker image) |

---

## AI Agents

16 AI agents run on Coolify, deployed from pre-built images in the local Docker registry:

Agents: brinxx, jodasign, logohorloge, magic_dwf, magiceverse, mondial, ollivanders, princess, spranz, support_agent, topgiving

Each agent is available at `agent-<name>.magicomniverse.online` and uses its own database (`magic_agent_<name>` in PostgreSQL).

---

## Dev Server Access

For server-level operations (not code changes), SSH into the Coolify server:

```bash
ssh magicomniverse    # Root access to Coolify server (159.195.68.41)
ssh beta-brinxx       # Beta server (37.97.132.23)
```

---

## External Services

| Service | URL | Purpose |
|---|---|---|
| Spranz Designer | designer.spranz.de | External logo designer (Hetzner, 23.88.122.78) |
| Spranz Management | designer.spranz.de/managementtool/ | SVG/product management |
| Coolify Dashboard | coolify.magicomniverse.online | Deployment management |
| Glances | glances.magicomniverse.online | Server resource monitoring |
| Netdata | netdata.magicomniverse.online | Detailed server metrics |
| Nextcloud | (internal) | Document collaboration |
| Vaultwarden | vault.magiceverse.online | Password manager |

---

## Rules

- **Deploy via GitHub only** — push to repo, Coolify deploys. No manual file copying.
- **Feature flags for tenant differences** — never maintain separate code per tenant.
- **Never delete data without asking** — databases, files, containers, branches.
- **Never force push to main** — use feature branches and PRs.
- **Never commit credentials** — use Coolify env vars.
- **Test on development tenant first** — admin-development.magicomniverse.online before deploying to all.

---

## gstack Skills

For web browsing, always use the `/browse` skill. Never use `mcp__claude-in-chrome__*` tools.

2. Magic-Monitor

File: Magic-Monitor/CLAUDE.md Repo: github.com/midego1/Magic-Monitor Deploys: monitor.magicomniverse.online

# Magic Monitor (Tenant Pulse)

Platform monitoring dashboard for the Magic e-VERSE ecosystem. Polls all tenant databases every 5 minutes, collects business metrics (orders, revenue, customers, products), tracks errors, and surfaces alerts when things go wrong.

**Live:** https://monitor.magicomniverse.online

## Tech Stack

- **Backend:** Node.js + Express + TypeScript
- **Frontend:** React 18 + Vite + Tailwind CSS v4 + Radix UI + Recharts
- **Database:** PostgreSQL (`magic_monitor` on shared `magic-postgres`)
- **Scheduling:** node-cron (in-process)
- **Deploy:** Coolify (UUID `hwwmonk4o0vyy43qw04hsm5x`)

## Project Structure

```
Magic-Monitor/
├── src/
│   ├── server.ts              # Express app, mounts routes, serves frontend
│   ├── collector/
│   │   ├── index.ts           # Cron: polls tenant DBs every 5min, retention daily 03:00
│   │   └── health-pings.ts    # HTTP health checks against tenant URLs
│   ├── alerts/
│   │   └── index.ts           # Alert rules: error spikes, tenant down, stale collector
│   ├── db/
│   │   ├── connection.ts      # pg Pool + connectTenantDb helper
│   │   ├── schema.ts          # CREATE TABLE IF NOT EXISTS (auto-init)
│   │   └── seed.ts            # Upsert all 8 tenants
│   └── routes/
│       ├── tenants.ts         # CRUD tenants + latest metrics
│       ├── metrics.ts         # Global/per-tenant metric aggregations
│       ├── errors.ts          # Error events feed
│       ├── containers.ts      # Docker container status
│       ├── pim.ts             # PIM system status
│       ├── aplt.ts            # APLT module status (orders/invoices)
│       ├── users.ts           # Admin user management
│       ├── operations.ts      # Platform events timeline
│       ├── audit.ts           # Audit log
│       ├── export.ts          # Data export
│       └── settings.ts        # Monitor settings
├── frontend/
│   ├── src/
│   │   ├── App.tsx            # Main SPA with sidebar navigation
│   │   ├── components/
│   │   │   ├── TenantCard.tsx       # Per-tenant status card
│   │   │   ├── TenantDetail.tsx     # Drill-down view
│   │   │   ├── TenantCompare.tsx    # Side-by-side comparison
│   │   │   ├── PlatformCharts.tsx   # Recharts dashboards
│   │   │   ├── ErrorFeed.tsx        # Live error stream
│   │   │   ├── ContainersView.tsx   # Docker containers
│   │   │   ├── PimView.tsx          # PIM status
│   │   │   ├── ApltView.tsx         # APLT module
│   │   │   ├── UsersView.tsx        # User management
│   │   │   ├── AuditLog.tsx         # Audit trail
│   │   │   ├── GlobalSearch.tsx     # Cmd+K search (cmdk)
│   │   │   ├── SettingsPage.tsx     # Configuration
│   │   │   └── ui/                  # Radix-based primitives
│   │   ├── hooks/useApi.ts    # Polling fetch hook
│   │   └── types/index.ts    # TypeScript interfaces
│   └── vite.config.ts
├── Dockerfile                 # Multi-stage: frontend build + backend build + production
├── package.json
└── tsconfig.json
```

## Key API Endpoints

| Endpoint | Purpose |
|----------|---------|
| `GET /api/health` | Health check (503 if collector stale >10min) |
| `GET /api/tenants` | All tenants with latest metrics |
| `GET /api/metrics` | Global aggregated metrics |
| `GET /api/errors` | Error events feed |
| `GET /api/containers` | Docker container statuses |
| `GET /api/pim` | PIM system health |
| `GET /api/aplt` | APLT module status |
| `GET /api/audit` | Audit log entries |
| `GET /api/operations` | Platform events timeline |
| `GET /api/settings` | Monitor configuration |
| `GET /api/users` | Admin users |
| `GET /api/export` | Data export |

## Collector

Runs in-process via node-cron:
- **Every 5 minutes:** Connects to each tenant's PostgreSQL database, queries orders/revenue/customers/products for the day, stores in `tenant_metrics_hourly`. Runs HTTP health pings after.
- **Daily at 03:00:** Retention cleanup (errors: 30d, metrics: 90d, events: 90d, audit: 1y, health_checks: 7d).
- **Alerting:** Error spike detection, tenant-down after 3 consecutive poll failures, stale collector warning.

## How to Run Locally

```bash
# Prerequisites: Node 20+, PostgreSQL with magic_monitor database

# Backend
cp .env.example .env   # Edit DATABASE_URL and PG credentials
npm install
npm run dev            # tsx watch on :3000

# Frontend (separate terminal)
cd frontend
npm install
npm run dev            # Vite dev server with proxy
```

## Deployment

Deployed via Coolify at `monitor.magicomniverse.online`.

- **Coolify UUID:** `hwwmonk4o0vyy43qw04hsm5x`
- **Port:** 3000
- **Dockerfile:** Multi-stage build (frontend + backend compiled, then production image with only runtime deps)
- **Healthcheck:** `GET /api/health` every 30s, unhealthy if collector hasn't run in 10 minutes

## Database

Uses `magic_monitor` database on the shared PostgreSQL instance (`magic-postgres`).

Key tables:
- `tenants` — registered tenants with Coolify UUIDs, URLs, ports
- `tenant_metrics_hourly` — time-series business metrics per tenant
- `error_events` — error log with severity, service, tenant
- `platform_events` — operational events (deploys, restarts)
- `audit_log` — who did what
- `alert_history` — fired alerts
- `health_checks` — HTTP ping results

Schema auto-initializes on startup via `initSchema()`.

## Environment Variables

See `.env.example`:
- `DATABASE_URL` — connection string for the monitor's own database
- `PG_HOST`, `PG_PORT`, `PG_USER`, `PG_PASSWORD` — used by collector to connect to tenant databases
- `COOLIFY_API_URL`, `COOLIFY_API_TOKEN` — Coolify API for container management
- `PORT` — server port (default 3000)

3. Magic-PIM

File: Magic-PIM/CLAUDE.md Repo: github.com/midego1/Magic-PIM Deploys: pim.magicomniverse.online

# Magic PIM

## What This Is
Master Product Information Management system for the Magic e-Verse ecosystem. Centralizes product data from multiple suppliers (Spranz, XDConnect, PFConcept, Midocean, Toppoint, Langenberg) and syncs to tenant e-commerce stores. Built on Medusa 2.0 with a Next.js storefront.

## Tech Stack
- **Backend:** Medusa 2.0 (Node.js/TypeScript), PostgreSQL, Redis
- **Storefront:** Next.js, Tailwind CSS
- **Database:** `magic_pim` on `magic_pim_postgres_dev` (port 5432)
- **Containerization:** Docker Compose (postgres, redis, backend, storefront)
- **Supplier Sync:** Custom connector modules per supplier

## Deployment
- **URL:** pim.magicomniverse.online
- **Admin:** magic-pimadmin.magiceverse.online
- **Repo:** github.com/midego1/Magic-PIM
- Push to `main` -> Coolify auto-deploys
- Ports: Backend 4002, Storefront 10002, PIM API 7992

## Project Structure
```
Magic-PIM/
├── backend/
│   ├── src/
│   │   ├── admin/              # Medusa admin UI customizations
│   │   │   ├── routes/         # Custom admin pages (19+ routes)
│   │   │   └── widgets/
│   │   ├── api/                # REST API routes
│   │   │   ├── admin/          # Admin API endpoints
│   │   │   ├── store/          # Storefront API endpoints
│   │   │   ├── aplt/           # APLT module (orders, quotes, invoices)
│   │   │   ├── branding/       # White-label branding
│   │   │   ├── images/         # Product image serving
│   │   │   └── products/       # Product API
│   │   ├── modules/
│   │   │   └── connectors/     # Supplier sync connectors
│   │   ├── jobs/               # Background jobs
│   │   ├── scripts/            # Utility scripts
│   │   ├── subscribers/        # Event subscribers
│   │   ├── workflows/          # Medusa workflows
│   │   └── utils/
│   ├── medusa-config.ts
│   ├── Dockerfile
│   └── package.json
├── storefront/
│   ├── src/
│   │   ├── app/                # Next.js app router
│   │   ├── modules/            # UI modules
│   │   └── lib/                # Utilities
│   ├── Dockerfile
│   └── package.json
├── docker-compose.yml          # Local dev (postgres, redis, backend, storefront)
├── docker-compose.prod.yml     # Production overrides
└── package.json                # Root utility scripts (migration tools)
```

## Key Concepts
- **Supplier Connectors:** Each supplier has a connector module in `backend/src/modules/connectors/` that handles product import, image sync, and pricing updates
- **APLT Module:** Custom order/quotation/invoice system at `backend/src/api/aplt/` with PDF generation
- **Tenant Sync:** PIM is the master data source. Products sync down to individual tenant databases (`magic_b2b_<tenant>`)
- **Admin Routes:** Heavy customization of Medusa admin with 19+ custom routes for CMS, licensing, connectors, etc.
- **Product Images:** Stored in `/mnt/data/pim_data/` organized by supplier (e.g., `spranz/5325-00.001.jpg`)

## Development
```bash
# Start all services
cd Magic-PIM
docker compose up -d

# Backend only
cd Magic-PIM/backend
npm run dev

# Storefront only
cd Magic-PIM/storefront
npm run dev

# Database access
docker exec magic_pim_postgres_dev psql -U postgres -d magic_pim
```

## Important Rules
- **Dev Projects workflow is mandatory** -- create a project via API before making changes
- Never work directly on `main` branch
- PostgreSQL credentials: `postgres` / `<your-db-password>`
- The root `package.json` contains migration/utility scripts, NOT the application code

4. Magic-Portal

File: Magic-Portal/CLAUDE.md Repo: github.com/midego1/Magic-Portal Deploys: portal.magicomniverse.online

# Magic Portal

## What This Is
Central dashboard and tenant management hub for the Magic e-Verse ecosystem. Provides authentication (with WhatsApp 2FA), tenant overview, documentation, ticket management, and e-commerce monitoring. Single-page React app with an Express backend.

## Tech Stack
- **Frontend:** React 19 + TypeScript + Vite, React Router, React Markdown
- **Backend:** Express.js (server.cjs), MySQL sessions, bcrypt auth
- **Database:** MySQL (`magic_doc` on shared mysql container)
- **Auth:** Session-based with WhatsApp 2FA (Meta Business API)
- **i18n:** @magiverse/i18n (shared package)
- **File uploads:** Multer (e-commerce images, ticket attachments)
- **Email:** Nodemailer

## Deployment
- **URL:** portal.magicomniverse.online
- **Repo:** github.com/midego1/Magic-Portal
- Push to `main` -> Coolify auto-deploys
- Dockerfile: Node 22, pre-built `dist/` served by Express on port 4096

## Project Structure
```
Magic-Portal/
├── src/
│   ├── main.tsx                 # App entry
│   ├── App.tsx                  # Root component + routing
│   ├── components/
│   │   └── MagicHeader.tsx      # Shared header component
│   ├── i18n/                    # Internationalization
│   ├── assets/                  # Static assets
│   ├── App.css / index.css      # Styles
├── server.cjs                   # Express backend (auth, API, sessions, 2FA)
├── portal.db                    # Local SQLite (fallback/cache)
├── public/                      # Static public assets
├── uploads/                     # User uploads (e-commerce, tickets)
│   ├── ecommerce/
│   └── tickets/
├── Dockerfile                   # Node 22, serves pre-built dist
├── vite.config.ts
├── package.json                 # magic_portal
└── dist/                        # Production build output
```

## Key Concepts
- **server.cjs** is the main backend -- handles auth, MySQL sessions, WhatsApp 2FA, file uploads, and serves the built frontend
- **WhatsApp 2FA** uses Meta Business API with template messages for verification codes
- **Tenant monitoring:** Portal connects to all tenant backends to check health/status
- The frontend is pre-built (`npm run build`) and the Dockerfile copies `dist/` -- it does NOT build during Docker build
- **i18n dependency** on `@magiverse/i18n` (local file reference) is stripped from Dockerfile during install

## Local Development
```bash
cd Magic-Portal

# Frontend dev server (Vite)
npm run dev

# Backend server
npm run server         # or: node server.cjs

# Build frontend
npm run build

# Full production-like run
npm run build && node server.cjs
```

5. Magic-Agent

File: Magic-Agent/CLAUDE.md Repo: github.com/midego1/Magic-Agent (needs initial push — no git remote yet) Deploys: 16 Coolify apps

# Magic Agent

## What This Is
Multi-tenant AI agent platform for B2B e-commerce. Each tenant gets an AI assistant via WhatsApp, webchat, and (planned) email/voice. Agents answer questions, search products, create quotes, and escalate to humans. 16 Coolify apps: per-tenant agents, flowbuilder, escalation, webhook, and widget servers.

## Tech Stack
- **Agents:** Node.js/TypeScript, Anthropic Claude SDK, Express
- **FlowBuilder:** React 18 + ReactFlow + Vite + Tailwind + shadcn/ui
- **Widget:** Vanilla JS (universal, plug & play across tenants)
- **Agents Portal:** React 18 + Vite + Tailwind + shadcn/ui, Zustand, Express API
- **Database:** PostgreSQL (per-tenant: `magic_agent_<tenant>`, portal: `magic_agents_portal`)
- **Process Manager:** PM2

## Deployment
- **Repo:** github.com/midego1/Magic-Agent (NOTE: no git remote configured yet -- needs `git remote add origin` and initial push)
- Multiple Coolify apps per service (agents, flowbuilder, widget, portal, escalation)
- Per-tenant agents on ports 11001-11099, Widget on 4061, Portal on 11080, FlowBuilder on 11006

## Project Structure
```
Magic-Agent/
├── agents-portal/           # agents.magiceverse.online (React dashboard, see its CLAUDE.md)
├── flowbuilder2/            # FlowBuilder UI (React + ReactFlow), embedded in portal
├── widget/                  # Universal chat widget (widget-loader.js -> widget-core.js)
├── backend/                 # Shared agent backend logic
├── escalation-server/       # Human takeover system
├── webhook-server/          # Incoming webhook handler
├── agents/                  # Agent source code per tenant (15 tenants)
│   ├── brinxx/              # TypeScript agent (primary dev target)
│   └── <tenant>/            # Each has src/, config/, .env
├── magic_agent_<tenant>/    # Per-tenant runtime (agent.js + .env) -- DO NOT sync
├── init-db/                 # Database initialization scripts
├── sql/                     # Database schemas + migrations
├── n8n-workflows/           # N8N workflow exports
└── docs/                    # Internal documentation
```

## Key Concepts
- **Widget is universal:** `widget-loader.js` loads with `data-agent=<tenant>`, fetches config from DB (colors, name, texts), injects `widget-core.js`. No per-tenant code changes needed.
- **Per-tenant isolation:** Each tenant has its own database (`magic_agent_<tenant>`), agent code, and .env. Never mix databases.
- **Agents read from commerce DBs** (`magic_b2b_<tenant>`) but never write to them.
- **New tenant checklist:** Create DB -> run init-db scripts -> insert widget config -> add to agent registry -> copy template from `magic_agent_default_agent/` -> start PM2 -> test.

## Critical Rules
1. No hardcoded tenant names -- always from DB or env vars
2. No hardcoded ports -- from agent registry or config
3. No hardcoded credentials -- always via .env
4. No changes to tenant-specific code -- fix in shared codebase
5. Never work directly on production -- test locally first
6. Always backup before changes
7. Never sync: `.env`, credentials, tenant-specific agent config, conversation history

## Local Development
```bash
# Widget server
cd widget && node widget-server.js

# FlowBuilder
cd flowbuilder2 && npm run dev

# Specific tenant agent
cd agents/brinxx && npm run dev

# All services via PM2
pm2 start ecosystem.config.js
```

6. Magic-Logo

File: Magic-Logo/CLAUDE.md Repo: github.com/midego1/Magic-Logo Deploys: logo.magicomniverse.online

# Magic Logo

## What This Is
2D Logo Designer and Product Configurator for the Magic e-Verse platform. Allows customers to upload logos, select print techniques, choose colors, and preview their logo on products. Multi-tenant with separate deployments per brand (Spranz, Logohorloge, Default, Dev).

## Tech Stack
- **Backend:** Express.js + TypeScript, Prisma ORM, PostgreSQL
- **Frontend:** React + Vite, Fabric.js (canvas), Zustand (state), Bootstrap
- **Image Processing:** Sharp, Inkscape, Ghostscript, ImageMagick, Potrace (for EPS/AI/SVG conversion)
- **AI Integration:** Anthropic Claude SDK (logo analysis), Kie.ai (AI rendering)
- **Database:** PostgreSQL on `magic_logo_postgres` (port 8452)

## Deployment
- **URL:** logo.magicomniverse.online
- **Repo:** github.com/midego1/Magic-Logo
- Push to `main` -> Coolify auto-deploys
- Each tenant variant is a separate Coolify app (spranz, default, logohorloge, dev)
- Backend and frontend have separate Dockerfiles per tenant

## Project Structure
```
Magic-Logo/
├── spranz/                     # Spranz tenant (primary development target)
│   ├── backend/
│   │   ├── src/
│   │   │   ├── api/            # API route handlers
│   │   │   │   ├── products.ts       # Product lookup
│   │   │   │   ├── techniques.ts     # Print techniques
│   │   │   │   ├── logos.ts          # Logo upload/management
│   │   │   │   ├── colors.ts         # Color variants
│   │   │   │   ├── variants.ts       # Product variants
│   │   │   │   ├── configurations.ts # Saved configs
│   │   │   │   ├── kieai.ts          # Kie.ai AI render integration
│   │   │   │   ├── moodshot.ts       # Moodshot generation
│   │   │   │   ├── export.ts         # Export (PDF, ZIP)
│   │   │   │   ├── rembg.ts          # Background removal
│   │   │   │   ├── screenshot3d.ts   # 3D screenshot capture
│   │   │   │   ├── transactions.ts   # Transaction/session tracking
│   │   │   │   └── config3d.ts       # 3D config lookup
│   │   │   ├── services/       # Business logic
│   │   │   ├── config/         # App configuration
│   │   │   ├── utils/          # Helpers
│   │   │   └── index.ts        # Express app entry point
│   │   ├── prisma/             # Database schema & migrations
│   │   ├── Dockerfile
│   │   └── package.json
│   ├── frontend/
│   │   ├── src/                # React app (Vite)
│   │   ├── Dockerfile          # Builds to nginx
│   │   └── package.json
│   └── docker-compose.yml
│
├── default/                    # Default tenant (same structure as spranz)
├── dev/                        # Development tenant
├── logohorloge/                # Logohorloge tenant (minimal, backend+frontend only)
│
├── backend/                    # Shared backend resources (cache, logs, uploads)
├── frontend/                   # Legacy/shared frontend
├── docs/                       # Documentation
└── magic_logo/                 # Legacy monorepo structure
```

## Key Concepts
- **Multi-tenant Architecture:** Each tenant (spranz, default, dev, logohorloge) has its own backend + frontend deployment with separate database and configuration
- **SVG Handling:** Critical path -- SVGs stored at `/mnt/data/pim_data/svg/spranz/`, named as `{variant_code}.svg`. The designer loads SVGs to show logo placement areas on products
- **Spranz SKU Convention:** `sku` = base SKU (e.g., `376-00`), `variant_code` = full variant (e.g., `376-00.001`). Getting this wrong causes broken SVG lookups (double suffixes)
- **Print Techniques:** Products support multiple techniques (engraving, pad print, etc.) with different color limits and pricing
- **Logo Processing Pipeline:** Upload -> optional background removal (rembg) -> optional vectorization -> place on product SVG -> export as PDF/PNG
- **Kie.ai Integration:** AI-powered photorealistic rendering of logo on product via Kie.ai API (redpandaai.co)

## Development
```bash
# Spranz backend
cd spranz/backend && npm run dev

# Spranz frontend
cd spranz/frontend && npm run dev

# Prisma studio (database GUI)
cd spranz/backend && npx prisma studio

# Docker (full stack)
cd spranz && docker compose up -d
```

## Important Rules
- Spranz is the primary development tenant -- changes go here first, then sync to others
- The Spranz designer server (designer.spranz.de) is external on Hetzner (23.88.122.78)
- Logohorloge has a unique 2D mini preview modal -- do NOT overwrite with spranz code
- Backend runs natively on port 4055 for spranz (not always Docker)
- Image processing requires system packages: inkscape, ghostscript, imagemagick, potrace

File: Magic-Modal/CLAUDE.md Repo: github.com/midego1/Magic-Modal Deploys: modal.magicomniverse.online

# Magic Modal

## What This Is
Embeddable logo editing modal for the Magic e-Verse platform. A React component that lets users upload, position, resize, and rotate logos on product images using a Fabric.js canvas. Designed to be embedded in storefronts and designer tools via iframe or direct import.

## Tech Stack
- **Framework:** React 18 + TypeScript + Vite
- **Canvas:** Fabric.js 5.x (logo manipulation, drag/drop, scaling)
- **Image Tracing:** imagetracerjs (raster-to-vector conversion)
- **Icons:** FontAwesome
- **Build Output:** Static files served by nginx
- **Port:** 3092

## Deployment
- **URL:** modal.magicomniverse.online
- **Repo:** github.com/midego1/Magic-Modal
- Push to `main` -> Coolify auto-deploys
- Dockerfile: multi-stage (node builder -> nginx)

## Project Structure
```
Magic-Modal/
├── src/
│   ├── main.tsx                 # App entry point
│   ├── App.tsx                  # Root component
│   ├── index.ts                 # Library export
│   ├── components/
│   │   └── MagicLogoModal.tsx   # Main modal component (Fabric.js canvas)
│   ├── hooks/                   # Custom React hooks
│   ├── styles/                  # CSS styles
│   └── types/                   # TypeScript type definitions
├── spranz/                      # Spranz-specific variant/config
├── default/                     # Default variant/config
├── public/                      # Static assets
├── Dockerfile                   # Multi-stage: node build -> nginx on port 3092
├── docker-compose.yml
├── vite.config.ts
├── package.json                 # @magiverse/magic-modal
└── dist/                        # Built output (served by nginx)
```

## Key Concepts
- **MagicLogoModal** is the core component -- handles logo upload, canvas interaction, and export
- **Multi-variant:** `spranz/` and `default/` folders contain tenant-specific configurations
- The modal is designed for iframe embedding -- it communicates with the parent window via postMessage
- Fabric.js canvas handles all logo manipulation (position, scale, rotation, crop)

## Local Development
```bash
cd Magic-Modal
npm run dev        # Vite dev server
npm run build      # TypeScript compile + Vite build
npm run preview    # Preview production build
```

8. Magic-3D

File: Magic-3D/CLAUDE.md Repo: github.com/midego1/Magic-3D Deploys: 3d.magicomniverse.online

# Magic 3D

## What This Is
3D product viewer and logo configurator for the Magic e-Verse platform. Renders interactive 3D product models with logo placement preview. Multi-variant with separate builds per brand (default, spranz, demokkenkoning).

## Tech Stack
- **3D Engine:** Three.js + React Three Fiber + Drei
- **Framework:** React 18 + TypeScript + Vite
- **Backend:** Express.js (serves config, product data)
- **Database:** PostgreSQL + MySQL (product/config data)
- **State:** Zustand

## Deployment
- **URL:** 3d.magicomniverse.online
- **Repo:** github.com/midego1/Magic-3D
- Push to `main` -> Coolify auto-deploys
- Each variant is a separate Coolify app

## Project Structure
```
Magic-3D/
├── default-3d/                  # Default tenant variant
│   ├── src/
│   │   ├── main.tsx             # App entry
│   │   ├── App.tsx              # Root component
│   │   ├── components/          # 3D viewer React components
│   │   ├── hooks/               # Custom hooks
│   │   ├── store/               # Zustand state
│   │   ├── types/               # TypeScript types
│   │   └── server/              # Express backend
│   ├── public/                  # Static assets (3D models, textures)
│   ├── vite.config.ts
│   ├── tsconfig.json            # Client TypeScript config
│   ├── tsconfig.server.json     # Server TypeScript config
│   └── package.json             # @magiverse/magic-3d
│
├── spranz-3d/                   # Spranz variant (same structure)
├── demokkenkoning-3d/           # Demokkenkoning variant
├── default/                     # Legacy/shared
├── dev/                         # Development variant
└── magic_3d/                    # Legacy monorepo
```

## Key Concepts
- **Dual build:** Client (Vite) and server (tsc) are built separately -- see `build:client` and `build:server` scripts
- **3D Config tables:** Product 3D configurations stored in PostgreSQL
- **Each variant** has its own database connections and product catalog
- 3D models are stored in `public/` as GLTF/GLB files

## Local Development
```bash
cd default-3d

# Full stack (client + server)
npm run dev

# Client only
npm run dev:client

# Server only
npm run dev:server

# Build
npm run build          # Builds both client and server
npm run start          # Run production server
```

9. Magic-Editor

File: Magic-Editor/CLAUDE.md Repo: github.com/midego1/Magic-Editor Deploys: editor.magicomniverse.online

# Magic Editor

## What This Is
Browser-based image editor built on miniPaint (HTML5 Canvas). Supports layers, effects, drawing, and standard image editing operations.

## Tech Stack
- Vanilla JS (miniPaint fork v4.14.2)
- Webpack (build + dev server)
- jQuery, alertifyjs, gif.js, pica (image processing)
- Served via nginx:alpine container

## Deployment
- **URL:** editor.magicomniverse.online
- **Repo:** github.com/midego1/Magic-Editor
- **Container port:** 3091
- **Dockerfile:** nginx:alpine serving static files
- Push to `main` → Coolify auto-deploys

## Project Structure
```
Magic-Editor/
├── src/
│   ├── js/          # Core editor logic
│   └── css/         # Styles
├── server/          # Local dev server helper
├── dist/            # Built output
├── index.html       # Entry point
├── webpack.config.js
└── Dockerfile       # nginx:alpine on port 3091
```

## Development
```bash
npm run server    # Dev server with hot reload
npm run build     # Production build
```

10. Magic-Resize

File: Magic-Resize/CLAUDE.md Repo: github.com/midego1/Magic-Resize Deploys: resize.magicomniverse.online

# Magic Resize

## What This Is
Batch image resize tool. Upload multiple images, set target dimensions, download resized results as a zip.

## Tech Stack
- React 19 + TypeScript
- Vite 7
- JSZip (zip download), file-saver
- Served via nginx:alpine container

## Deployment
- **URL:** resize.magicomniverse.online
- **Repo:** github.com/midego1/Magic-Resize
- **Container port:** 3090
- **Dockerfile:** nginx:alpine serving pre-built `dist/`
- Push to `main` → Coolify auto-deploys

## Project Structure
```
Magic-Resize/
├── src/
│   ├── App.tsx      # Main resize UI
│   ├── main.tsx     # Entry point
│   └── assets/
├── dist/            # Pre-built output (committed)
├── vite.config.ts
└── Dockerfile       # nginx:alpine on port 3090
```

## Development
```bash
npm run dev       # Vite dev server
npm run build     # Build to dist/
```

11. Magic-Connector

File: Magic-Connector/CLAUDE.md Repo: github.com/midego1/Magic-Connector Deploys: Coolify (internal, port 3085)

# Magic Connector

## What This Is
Integration bridge between Magic e-Verse and FastEditor. Manages API config, product mappings, Smartlink sessions, and webhooks for print-ready file delivery.

## Tech Stack
- **Frontend:** React 19 + TypeScript + Vite + React Router
- **Backend:** Express (server.cjs) + PostgreSQL (pg)
- Runs as single Node.js process serving both API and static frontend

## Deployment
- **Repo:** github.com/midego1/Magic-Connector
- **Container port:** 3085
- **Dockerfile:** node:22-alpine, runs `server.cjs`
- Push to `main` → Coolify auto-deploys

## Project Structure
```
Magic-Connector/
├── src/
│   ├── pages/        # React pages
│   ├── components/   # UI components
│   ├── services/     # API client
│   ├── hooks/
│   └── types/
├── server.cjs         # Express backend (API + webhooks)
├── init-db.sql        # Database schema
├── nginx.conf         # Reverse proxy config
├── dist/              # Pre-built frontend
├── vite.config.ts
└── Dockerfile
```

## Key API Routes
- `GET/POST /api/connectors/fasteditor/config` — FastEditor configuration
- `POST /api/connectors/fasteditor/test` — Test API connection
- `POST /api/connectors/fasteditor/smartlink` — Create editor session
- `GET /api/connectors/fasteditor/products` — Product mappings
- `POST /webhook/fasteditor/session-complete` — Session callback
- `GET /api/logs` — Connector activity logs

## Database
- PostgreSQL database: `magic_connector`
- Tables: `connector_configs`, `connector_logs`, `fasteditor_sessions`, `fasteditor_product_mappings`

## Development
```bash
npm run dev       # Vite frontend dev server
npm run server    # Express backend
npm run build     # Build frontend to dist/
```

12. Magic-Contact

File: Magic-Contact/CLAUDE.md Repo: github.com/midego1/Magic-Contact Deploys: Coolify (internal, port 4095)

# Magic Contact

## What This Is
Contact page and lead capture tool. Serves a contact form with vCard download, stores submissions in PostgreSQL.

## Tech Stack
- **Frontend:** React 19 + TypeScript + Vite
- **Backend:** Express (ESM) + PostgreSQL (pg)
- Monorepo with separate `backend/` and `frontend/` directories

## Deployment
- **Repo:** github.com/midego1/Magic-Contact
- **Container port:** 4095
- **Dockerfile:** node:22-alpine, runs `backend/server.js` and serves `frontend/dist/`
- Push to `main` → Coolify auto-deploys

## Project Structure
```
Magic-Contact/
├── backend/
│   ├── server.js       # Express API + static file serving
│   └── package.json
├── frontend/
│   ├── src/            # React app
│   ├── dist/           # Pre-built output
│   └── vite.config.ts
└── Dockerfile
```

## Key Endpoints
- `GET /api/vcard` — Download Wayne Laagewaard vCard
- Contact form submissions stored in PostgreSQL via `DATABASE_URL` env var

## Development
```bash
# Backend
cd backend && npm run dev

# Frontend
cd frontend && npm run dev
npm run build     # Build to frontend/dist/
```

13. Magic-Moodshot

File: Magic-Moodshot/CLAUDE.md Repo: github.com/midego1/Magic-Moodshot Deploys: moodshot.magicomniverse.online

# Magic Moodshot

## What This Is
Product moodshot generator. Upload a product photo, select a background scene, and create styled product visuals using AI image compositing.

## Tech Stack
- **Frontend:** React 19 + TypeScript + Vite
- **Backend:** Express + TypeScript (tsx), multer (file uploads), node-fetch
- PostgreSQL (`moodshot_service` database)
- Concurrently for parallel dev servers

## Deployment
- **URL:** moodshot.magicomniverse.online
- **Repo:** github.com/midego1/Magic-Moodshot
- **Container port:** 4120
- Push to `main` → Coolify auto-deploys

## Project Structure
```
Magic-Moodshot/
├── src/
│   ├── App.tsx        # Main UI
│   ├── main.tsx       # Entry point
│   └── assets/
├── server/
│   └── index.ts       # Express API (uploads, backgrounds, AI compositing)
├── vite.config.ts
├── tsconfig.json
└── package.json
```

## Key API Routes
- `GET /backgrounds` — List available background images
- `POST /upload` — Upload product image for compositing

## Development
```bash
npm run dev          # Vite frontend only
npm run dev:server   # Express backend only (tsx watch)
npm run dev:all      # Both in parallel
npm run build        # Build frontend to dist/
```

14. Magic-Price-Import

File: Magic-Price-Import/CLAUDE.md Repo: github.com/midego1/Magic-Price-Import Deploys: price-import.magicomniverse.online

# Magic Price Import

## What This Is
Bulk price import tool for Magic e-Verse tenants. Upload CSV/Excel files with pricing data, map columns, preview changes, and push prices to tenant databases.

## Tech Stack
- **Frontend:** React 18 + TypeScript + Vite + Tailwind CSS
- **Backend:** Express + TypeScript (tsx), multer (file uploads)
- csv-parse, xlsx (file parsing)
- PostgreSQL (pg) for tenant database connections

## Deployment
- **URL:** price-import.magicomniverse.online
- **Repo:** github.com/midego1/Magic-Price-Import
- **Dockerfile:** Multi-stage build (frontend + backend), node:22-alpine production
- **Container port:** 3000
- Push to `main` → Coolify auto-deploys

## Project Structure
```
Magic-Price-Import/
├── frontend/
│   ├── src/
│   │   ├── components/   # UI components
│   │   └── styles/
│   └── vite.config.ts
├── backend/
│   ├── src/
│   │   ├── index.ts      # Express entry point
│   │   ├── routes/       # API routes
│   │   └── utils/        # Parsing helpers
│   └── tsconfig.json
└── Dockerfile            # Multi-stage: build both, serve from node:22-alpine
```

## Development
```bash
# Backend
cd backend && npm run dev    # tsx watch

# Frontend
cd frontend && npm run dev   # Vite dev server
cd frontend && npm run build # Build to dist/
```

15. Magic-Terminal

File: Magic-Terminal/CLAUDE.md Repo: github.com/midego1/Magic-Terminal Deploys: terminal.magicomniverse.online

# Magic Terminal

## What This Is
Web-based SSH terminal using Sshwifty. Provides browser access to the Magic server and Beta Brinxx via preconfigured SSH presets.

## Tech Stack
- Sshwifty (niruix/sshwifty Docker image)
- Config-driven: `sshwifty.conf.json`

## Deployment
- **URL:** terminal.magicomniverse.online
- **Repo:** github.com/midego1/Magic-Terminal
- **Container port:** 8182
- **Dockerfile:** copies config into sshwifty image
- Push to `main` → Coolify auto-deploys

## Project Structure
```
Magic-Terminal/
├── sshwifty.conf.json     # Server config + SSH presets
├── sshwifty_key            # SSH private key (mounted read-only)
├── sshwifty_key.pub
├── docker-compose.yml      # Local run config
└── Dockerfile
```

## Configured Presets
- Magic Server (adminmichiel1) — host.docker.internal:22
- Magic Server (adminwayne) — host.docker.internal:22
- Beta Brinxx (ubuntu@37.97.132.23)

## Notes
- `OnlyAllowPresetRemotes: false` — users can connect to custom hosts
- SSH key is mounted read-only into the container

CLAUDE.md Template

When creating a CLAUDE.md for a new repo, use this structure:

# Repo Name

## What This Is
1-2 sentences describing the service.

## Tech Stack
- Framework (e.g., Express, React, Medusa)
- Language (TypeScript)
- Database (if any)
- Key libraries

## Deployment
- **URL:** service.magicomniverse.online
- **Repo:** github.com/midego1/Repo-Name
- Push to `main` → Coolify auto-deploys

## Project Structure
Brief tree of key directories.

## Key Concepts
Important patterns, conventions, or gotchas (only if relevant).

## Local Development
How to run locally (npm install, npm run dev, etc.).

External Customer Deployments

External customers (like beta.brinxx.nl) get the same Magic-e-VERSE codebase deployed on their own server. Each external deployment gets a customized CLAUDE.md placed directly on the server at the project root.

Customer	Server	SSH	Code Path
Beta Brinxx	37.97.132.23	`ssh beta-brinxx`	`/var/www/brinxx.nl/`