Feature Module Pattern

types.ts (feature-local barrel)

Each feature may include types.ts that re-exports entity types from @/core/db/types and defines local types (e.g. MealType, CalorieEntryTotals in features/calories/types.ts). Screens import from ./types, not from @/core/db/types directly, unless there is a deliberate exception.

{featureName}.data.ts — rules

• Imports: getDatabase from core/db/client, createId from lib/id, nowIso/toDateKey from lib/time, syncEngine from core/sync
• All functions are async
• All functions start with: const db = await getDatabase()
• SELECT queries always include: WHERE deleted_at IS NULL
• DELETE operations always use soft delete (set deleted_at)
• Every write calls syncEngine.enqueue() after the DB operation
• Returns typed objects using types from core/db/types.ts
• No UI imports, no React imports

{featureName}.domain.ts — rules

• Pure TypeScript only — no DB imports, no React imports, no side effects
• Takes typed inputs, returns typed outputs
• Fully unit-testable (no mocking needed)
• Houses calculations, transformations, validations, state machines
• Examples from existing features:
  • habits.domain.ts: calculateStreak(), isCompletedToday(), groupByCategory()
  • pomodoro.domain.ts: nextPomodoroState(), PomodoroState type (Vitest-covered; screen may wire labels through this helper)

{featureName}Screen.tsx — rules

• Imports data functions from .data.ts
• Imports pure logic from .domain.ts
• Imports shared UI from core/ui/ (Button, Card, TextField, etc.)
• Local state with useState for UI state only
• Calls data functions directly (no React Query hooks currently)
• Refresh pattern: call load function after every mutation
• Uses NativeWind className for styling (Tailwind utility classes)
• Wraps content in <Screen> component from core/ui/Screen.tsx

Route file (app/(tabs)/{name}.tsx) — rules

• ONLY renders the Screen component
• No logic, no state, no imports from data/domain
• Example: import { WorkoutScreen } from "@/features/workout/WorkoutScreen"; export default function WorkoutTab() { return <WorkoutScreen />; }

Shared UI components (core/ui/)

• Button: variants = "primary" | "ghost" | "danger"
• Card: container with standard padding/shadow
• TextField: labeled text input
• NumberStepperField: numeric input with +/− stepper
• Screen: SafeAreaView wrapper with optional ScrollView
• SectionTitle: section heading with optional subtitle

DO NOT create one-off styled containers in screen files. Extend core/ui/ instead, or use NativeWind className directly on View/Text.

Existing features — quick reference