Developer Guidelines

Developer Guidelines:

This page outlines the standards for working on the CrewSplit codebase.

Essential Commands

• npm start: Start development server.
• npm test: Run all tests.
• npm run type-check: Run TypeScript compiler check.
• npm run lint: Run ESLint.
• npm drizzle-kit generate: Generate migrations.

Project Setup

Installation

npm install

Development

# Start Expo development server
npm start

# Run on iOS/Android
npm run ios
npm run android

Testing

npm test

Architecture Principles

1. Module Colocation

Each domain module is fully colocated under src/modules/<domain>/:

• repository/: Database access (Local Data Engineer)
• hooks/: React hooks (UI Integration)
• screens/: UI Screens (UI/UX Engineer)
• types.ts: Domain types

2. Settlement Module Layering

The settlement module strictly separates concerns:

1. Pure Math Layer: (Modeler) Zero dependencies, integer math (cents).
2. Service Layer: (Integration) Loads data, calls pure functions. Operates on convertedAmountMinor.
3. Hooks Layer: (UI) Consumes services for React components.

3. Multi-Currency Data Model

• Trip: Has a single currency.
• Expense: Stores originalAmountMinor (entry) and convertedAmountMinor (normalized to trip currency).
• Settlement: Only uses convertedAmountMinor.

Testing Strategy

• Determinism: Same data must always produce the same output.
• Edge Cases: Test for zero amounts, single participants, etc.
• Conservation: Net positions must sum to zero.
• Integer Math: All amounts in cents to avoid floating-point errors.

Database Migrations

• Modify schema files in src/db/schema/.
• Generate migrations with Drizzle Kit.
• Never manually wipe the database in production code.
• Prefer additive changes.

Common Gotchas

• No Participants: If an expense exists but no participants, preserve data but return empty settlements.
• Sorting: Always sort by ID for determinism (localeCompare).
• Rounding: Use the largest remainder method for cent distribution.