HausApp/CLAUDE.md

HaushaltsApp — Claude Instructions

Projektübersicht

Mobile-SaaS App für Haushaltsverwaltung: Haushaltsbuch, Urlaubsbudget, Echtzeit-Einkaufsliste.

Stack:

• Monorepo: Bun Workspaces + Turborepo
• Backend: Hono (Bun) — apps/server/
• Mobile: React Native + Expo + expo-router — apps/native/
• Web (Dashboard): React + TanStack Router + Vite — apps/web/
• Database: PostgreSQL + Drizzle ORM — packages/db/
• Auth: Better Auth — packages/auth/
• Shared Types/Schemas: Zod — packages/shared/
• UI (Web): shadcn/ui (base-lyra) — packages/ui/
• UI (Native): HeroUI Native + Uniwind

Architektur-Entscheidungen

• Multi-Tenant via householdId: Jeder Haushalt ist ein Tenant. Alle Daten (Transaktionen, Einkaufslisten etc.) sind an eine householdId gebunden. householdId wird via x-household-id HTTP-Header übergeben.
• Subscription Plans: free, pro, family — Feature-Gates in plan.middleware.ts, Definitionen in packages/shared/src/constants/plans.ts.
• Better Auth übernimmt User/Session-Management. Die packages/auth/ enthält die Server-seitige Konfiguration.
• Shared Package (@haushaltsApp/shared): Zod-Schemas und TypeScript-Types werden im shared package definiert und sowohl vom Backend als auch vom Frontend verwendet.
• Drizzle Schema: Alle App-Tabellen in packages/db/src/schema/app.ts, Auth-Tabellen in packages/db/src/schema/auth.ts.

Development starten

# Alle Services starten
bun run dev

# Einzelne Services
bun run dev:server   # API auf http://localhost:3000
bun run dev:web      # Web auf http://localhost:3001
bun run dev:native   # Expo (Metro Bundler)

# Datenbank
bun run db:start     # PostgreSQL via Docker starten
bun run db:generate  # Drizzle Migrationen generieren
bun run db:migrate   # Migrationen anwenden
bun run db:studio    # Drizzle Studio öffnen

Testing-Konventionen

Backend (apps/server/)

• Framework: bun:test (built-in, kein extra Package)
• Ort: apps/server/src/__tests__/routes/ und apps/server/src/__tests__/services/
• Konvention: Route-Tests testen den HTTP-Layer direkt via app.request(). Services werden unit-getestet.
• Ausführen: bun run test:api oder bun test apps/server/src/__tests__

// Beispiel Route-Test
import { describe, expect, it } from "bun:test";
import app from "../../index";

describe("GET /health", () => {
  it("returns 200 with status ok", async () => {
    const res = await app.request("/health");
    expect(res.status).toBe(200);
  });
});

Mobile (apps/native/)

• Framework: bun:test — kein Jest/Babel/jest-expo (Jest + Bun's .bun/ Store sind inkompatibel mit RN's ESM setup files)
• Was wird getestet: Stores, Hooks, Utils, API-Client — reine Business Logic, kein React Native Rendering
• Was NICHT getestet wird: UI-Komponenten, Screens — Rendering wird manuell via Expo Go verifiziert
• Ort: apps/native/src/__tests__/ spiegelt apps/native/src/ Struktur
• Ausführen: bun run test:mobile oder bun test apps/native/src/__tests__

// Beispiel Store-Test
import { describe, expect, it, beforeEach } from "bun:test";
import { useAuthStore } from "../../stores/auth.store";

describe("authStore", () => {
  beforeEach(() => {
    useAuthStore.setState({ user: null, token: null, isAuthenticated: false });
  });

  it("setUser authenticates the user", () => {
    useAuthStore.getState().setUser({ id: "1", name: "Test", email: "t@t.com" });
    expect(useAuthStore.getState().isAuthenticated).toBe(true);
  });
});

Coding-Konventionen

Allgemein

• TypeScript strict mode überall — kein any, kein type-casting ohne Kommentar
• Zod-first: Alle API-Inputs werden mit Zod-Schemas aus @haushaltsApp/shared validiert
• Named exports bevorzugen (default exports nur bei Expo/React Router Screens)

Naming

• Files: kebab-case.ts / PascalCase.tsx für React-Komponenten
• Variables/Functions: camelCase
• Types/Interfaces: PascalCase
• Database tables: snake_case (Drizzle convention)
• Zod schemas: camelCaseSchema (z.B. createTransactionSchema)
• Route files: feature.routes.ts
• Middleware files: feature.middleware.ts
• Service files: feature.service.ts

API-Design

• Alle Endpoints unter /api/ prefix
• Auth-Check via authMiddleware + requireAuth
• Tenant-Check via tenantMiddleware + requireHousehold
• Plan-Gates via requireFeature('featureName')
• HTTP-Status-Codes: 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found

Ordnerstruktur (Backend)

apps/server/src/
├── routes/         # HTTP-Layer, minimale Logik
├── services/       # Business Logic, kein direkter DB-Code in routes
├── middleware/     # Auth, Tenant, Plan Feature Gates
├── websocket/      # WebSocket Handler
├── lib/            # DB-Instance, Utilities
└── __tests__/      # Tests spiegeln src/-Struktur

State Management (Mobile)

• Zustand für globalen Client-State (User, aktueller Haushalt)
• TanStack Query für Server-State (Daten aus der API)
• Kein direktes Fetch in Komponenten — immer Custom Hooks oder TanStack Query

Known Constraints

React Native Testing

Jest + Bun's Content-Addressable Store (.bun/) sind strukturell inkompatibel für RN Rendering-Tests. jest-expo setzt setupFiles mit absoluten .bun/ Pfaden — kein Resolver oder transformIgnorePatterns kann das abfangen.

Entscheidung: bun:test für Business Logic (Stores, Hooks, Utils, Services). Rendering wird via Expo Go verifiziert. Rendering-Tests werden nachgereicht wenn Bun/jest-expo das nativ lösen.

Web App (apps/web)

TanStack Router generiert routeTree.gen.ts erst bei vite dev. check-types für web daher nur nach einmaligem dev-Run aussagekräftig.

Better Auth Mobile Setup

• bearer Plugin ist Pflicht in packages/auth/src/index.ts
• Mobile Clients nutzen Authorization: Bearer <token> Header
• Ohne bearer Plugin: getSession() gibt null zurück für alle Mobile Requests — stiller Auth-Fehler, alle Requests landen als 401

Expo Router — Redirect Pattern (FINAL)

FALSCH: Session-Guards in mehreren Layouts gleichzeitig → Ping-Pong Loop zwischen (auth) und (app) Layout

RICHTIG:

• index.tsx: statischer <Redirect href="/(auth)/login" /> — kein useSession, kein useEffect
• (auth)/_layout.tsx: KEIN Guard, nur Stack-Definition
• (app)/_layout.tsx: EINZIGER Guard
  • kein session → /(auth)/login
  • kein householdId → /(auth)/onboarding
  • sonst: render children

Ein Guard, eine Quelle der Wahrheit.

Household / Organization Bridge

• households.id === Better Auth organization.id (gleiche UUID)
• Reihenfolge beim Onboarding:
  1. organization.create() → organizationId
  2. INSERT INTO households { id: organizationId, ... } (via /api/households/setup)
  3. seedDefaultCategories(organizationId)
• Kein harter DB-FK von households zu organization — application-level check reicht, Better Auth Schema ist extern

Projektstand

Phase	Status	Details
Phase 1 — Foundation	✅	Monorepo, DB Schema, Shared Types, Stubs
Phase 2 — Auth Flow	✅	Better Auth, Organization Plugin, Apple, Auth Screens
Phase 3 — Transactions Full Stack	✅	9 API Tests, 7 Mobile Tests, Tenant Isolation bestätigt
Phase 4 — Dashboard	⬜
Phase 5 — Urlaubsbudget	⬜
Phase 6 — OCR Scanner	⬜
Phase 7 — Einkaufsliste (WebSockets)	⬜

Skills

Projekt-spezifische Skills unter apps/api/.agents/skills/ (noch leer, wird befüllt).

@apps/api/.agents/skills/