thats-me/DEV-NOTES.md

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:

# 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:

"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:

"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:

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)