# Dev Notes – Stand 25.02.2026

## node_modules-Konflikt: Mac ↔ Docker ↔ Cursor (gelöst)

### Ausgangslage

Die Quasar App läuft in drei Kontexten parallel:

| Kontext | Pfad | Plattform |
|---|---|---|
| **`quasar.app` Docker-Service** | Docker Volume (isoliert) | Linux ARM64 |
| **Cursor IDE Terminal** | `/workspace/frontend/node_modules` | Linux ARM64 |
| **Mac Terminal** | `~/Sites/thats-me.local/frontend/node_modules` | macOS ARM64 |

Der `frontend/`-Ordner ist überall **derselbe** (gemountetes Host-Filesystem). Rollup und andere native Pakete benötigen plattformspezifische Binaries – ein `npm install` auf einer Seite überschrieb bisher die Binaries der anderen.

---

### Fix 1 – Docker Volume für `quasar.app` (docker-compose.yml)

Der `quasar.app`-Service nutzt ein eigenes benanntes Docker-Volume für `node_modules`. Dadurch bleibt sein Linux-`node_modules` vollständig vom Host isoliert:

```yaml
# quasar.app Service:
volumes:
    - './frontend:/app'
    - 'quasar-node-modules:/app/node_modules'   # überschattet Host-Ordner

# volumes-Block:
volumes:
    quasar-node-modules:
        driver: local
```

Der `quasar.app`-Container führt beim Start automatisch `npm install && npm run dev` aus (in sein isoliertes Volume). Er ist damit **völlig unabhängig** vom Host-`node_modules`.

---

### Fix 2 – Rollup-Binaries als `optionalDependencies` (package.json)

Das Cursor-Terminal und der Mac teilen denselben `node_modules`-Ordner. Um den gegenseitigen Konflikt abzumildern, wurden alle relevanten Rollup-Plattform-Binaries explizit als `optionalDependencies` eingetragen:

```json
"optionalDependencies": {
    "@rollup/rollup-darwin-arm64": "^4.0.0",
    "@rollup/rollup-linux-arm64-gnu": "^4.0.0",
    "@rollup/rollup-linux-x64-gnu": "^4.0.0"
}
```

npm installiert davon nur die zur aktuellen Plattform passenden, schlägt aber nie fehl wenn eine fehlt.

---

### Fix 3 – `npm run dev` repariert sich selbst (package.json)

Das `dev`-Script führt vor dem Start automatisch `npm install` aus:

```json
"dev": "npm install && quasar dev"
```

Damit werden nach einem Mac-`npm install` die Linux-Binaries im Cursor-Terminal beim nächsten `npm run dev` automatisch nachgezogen.

---

### Wichtig: Cursor Terminal ≠ `quasar.app`-Container

Das Cursor IDE Terminal hat **keinen** Zugriff auf das isolierte Docker-Volume des `quasar.app`-Services. Für den Web-Dev-Server gilt:

- **Empfohlen:** `docker-compose up -d quasar.app` → App läuft unter `app.thats-me.test` (isoliertes Volume, kein Konflikt)
- **Alternativ:** `npm run dev` direkt im Cursor-Terminal (teilt node_modules mit dem Mac, aber Fix 3 gleicht das aus)

---

### Workflow: iOS-Build auf dem Mac

Nach einem `npm install` im Linux-Kontext (Cursor oder Docker) müssen auf dem Mac die node_modules neu installiert werden:

```bash
cd ~/Sites/thats-me.local/frontend
rm -rf node_modules && npm install
npx quasar build -m capacitor -T ios --ide
```

---

## Allgemeiner Projekt-Stand

- **Backend:** Laravel 12, API-Routes unter `api.thats-me.test`, OAuth2 via Passport
- **Frontend:** Quasar v2 SPA, offline-first mit Dexie.js (IndexedDB)
- **Mobile:** Capacitor für iOS/Android (in `frontend/src-capacitor/`)
- **Neue Komponenten:**
  - `AppSettingsModal.vue`, `ModalCard.vue`, `UserMenu.vue`, `ZoomControl.vue`
  - `frontend/src/composables/`, `frontend/src/db/`, `frontend/src/services/`
  - Backend API-Controller + Requests + Resources in `backend/app/Http/`
  - Event-Model + Migrations + Factory

---

## Wichtige Domains (lokale Entwicklung)

| Domain | Zweck |
|---|---|
| `app.thats-me.test` | Quasar Frontend (Quasar Dev-Server) |
| `api.thats-me.test` | Laravel REST API |
| `portal.thats-me.test` | Admin Panel |
| `thats-me.test` | Landingpage |
| `assets.thats-me.test` | Vite HMR (Laravel Backend Assets) |

## Services & Ports

| Service | Port | Purpose |
|---|---|---|
| `quasar.app` | 9000 | Quasar Frontend Dev-Server |
| `mysql` | 33070 | MySQL Datenbank |
| `mailpit` | 8028 | E-Mail Testing Dashboard |
| `redis` | 6383 | Cache & Queue |
| `laravel.test` | 5180 | Vite Dev-Server (HMR) |