Quake Wallet Development Guide

Expert AI assistant for working with the Quake Wallet codebase — a React Native financial instruments mobile application built with Expo, TypeScript, Redux Toolkit, and React Navigation.

Project Context

**Quake Wallet** allows users to view financial instruments, manage their investment portfolio, and place buy/sell orders (market or limit). All prices are in Argentine pesos (ARS). The backend API is at `https://dummy-api-topaz.vercel.app`.

Core Instructions

1. Understand the Layer-First Architecture

Before making any changes, recognize that this codebase uses **layer-first** organization (not feature-first):

```

src/

├── screens/ # Top-level navigation screens

├── components/ # Reusable UI (domain-organized)

├── navigation/ # React Navigation config

├── store/ # Redux Toolkit (slices, hooks)

├── services/ # API client and endpoints

├── schemas/ # Zod validation schemas

├── types/ # TypeScript definitions

├── utils/ # Pure functions (calculations, formatters)

├── hooks/ # Custom React hooks

└── constants/ # App-wide constants

```

Place new code in the appropriate layer based on its technical responsibility.

2. State Management Pattern

All Redux slices follow this structure:

```typescript

interface SliceState<T> {

data: T | null;

loading: boolean;

error: string | null;

}

```

**Rules:**

3. API Integration Standards

4. Navigation Structure

```

Bottom Tabs Navigator

├── Instruments Tab → InstrumentsScreen

├── Portfolio Tab → PortfolioScreen

└── Search Tab → SearchScreen

Modal (overlay)

└── OrderModal (triggered from any screen)

```

5. Critical Business Logic

#### Calculation Functions (in `src/utils/calculations/`)

**Returns** (`returns.ts`):

```typescript

calculateReturn(lastPrice, closePrice)

// Formula: ((lastPrice - closePrice) / closePrice) * 100

```

**Portfolio** (`portfolio.ts`):

```typescript

calculateMarketValue(quantity, lastPrice)

// Formula: quantity × lastPrice

calculateProfit(quantity, lastPrice, avgCostPrice)

// Formula: (lastPrice - avgCostPrice) × quantity

calculateProfitPercentage(lastPrice, avgCostPrice)

// Formula: ((lastPrice - avgCostPrice) / avgCostPrice) × 100

```

**Orders** (`orders.ts`):

```typescript

calculateQuantityFromAmount(amount, price)

// Formula: Math.floor(amount / price)

// CRITICAL: No fractional shares allowed — always use Math.floor()

```

#### Order Types and Statuses

**Order Types:**

**Order Statuses:**

**Order Request Format:**

```typescript

// MARKET order

{

"instrument_id": 1,

"side": "BUY" | "SELL",

"type": "MARKET",

"quantity": 100

}

// LIMIT order

{

"instrument_id": 1,

"side": "BUY" | "SELL",

"type": "LIMIT",

"quantity": 100,

"price": 45.50 // Required for LIMIT only

}

```

6. Form Validation

7. TypeScript Standards

**Strict Mode Enabled:**

**Path Aliases:**

```typescript

import { Instrument } from '@/src/types';

import { formatCurrency } from '@/src/utils';

```

8. API Endpoints Reference

| Method | Endpoint | Description |

|--------|----------|-------------|

| GET | `/instruments` | List all available instruments |

| GET | `/portfolio` | User's current positions |

| GET | `/search?query={ticker}` | Search instruments by ticker |

| POST | `/orders` | Create buy/sell order |

9. Testing Requirements

**Unit Tests** (`__tests__/unit/`):

**Component Tests** (`__tests__/components/`):

**E2E Tests** (`e2e/`):

10. Critical Implementation Rules

1. **No Fractional Shares**: Always use `Math.floor()` when calculating quantity from amount

2. **Currency Formatting**: All amounts must be formatted as ARS (Argentine pesos)

3. **Error Handling**: Display user-friendly messages, never raw API errors

4. **Loading States**: Every async operation must show loading feedback

5. **Debouncing**: Search input uses 300ms debounce (see `src/hooks/useDebounce.ts`)

Common Workflows

Adding a New Screen

1. Create screen component in `src/screens/`

2. Add route to navigator in `src/navigation/`

3. If state management needed, create/update Redux slice in `src/store/slices/`

4. Add API calls in `src/services/api/` if needed

Adding a Calculation Function

1. Add pure function to appropriate file in `src/utils/calculations/`

2. Export from `src/utils/calculations/index.ts`

3. Write unit test in `__tests__/unit/calculations.test.ts`

4. Ensure proper TypeScript return types

Adding a New API Endpoint

1. Add function to relevant file in `src/services/api/`

2. Use `apiClient` from `client.ts`

3. Define TypeScript types in `src/types/`

4. Integrate into Redux slice if state management required

5. Handle loading/error states in UI

Development Commands

```bash

Start development server

npm start # or npx expo start

Platform-specific runs

npm run android # Android emulator

npm run ios # iOS simulator

npm run web # Web browser

Testing

npm test # Run all tests

npm test -- --watch # Watch mode

npm test -- __tests__/unit/calculations.test.ts # Specific file

Code quality

npm run lint

```

Key Documentation References

Execution Guidelines

When working on Quake Wallet:

1. **Read before modifying**: Always read existing files in the relevant layer before making changes

2. **Respect architecture**: Place code in the correct layer (screens, components, store, services, utils, etc.)

3. **Follow patterns**: Match existing patterns for Redux slices, API calls, and component structure

4. **Test calculations**: Any new calculation logic must have unit tests

5. **Type everything**: Maintain strict TypeScript typing throughout

6. **Handle edge cases**: Loading states, error messages, and validation for all user interactions

7. **No fractional shares**: Critical business rule — always floor quantity calculations

8. **Format currency**: All monetary values must display as ARS