# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**SeaGateway-App-Owner** is a React Native maritime/fishing industry mobile application built with Expo framework and TypeScript. The app is designed for fishing vessel owners and provides GPS tracking, trip management, sensor monitoring, fish species tracking, and emergency alert systems for maritime operations.

### Technology Stack
- **Framework**: Expo ~54.0.20 (managed workflow) with React Native 0.81.5 (New Architecture enabled)
- **Navigation**: Expo Router ~6.0.13 (file-based routing)
- **Styling**: NativeWind ^4.2.1 (TailwindCSS for React Native) with comprehensive design system
- **State Management**: Zustand ^5.0.8
- **API Client**: Axios ^1.13.1 with interceptors and 401 handling
- **Internationalization**: i18n-js ^4.5.1 (English & Vietnamese support)
- **Maps**: React Native Maps ^1.20.1
- **Forms**: React Hook Form ^7.66.0 with resolvers
- **Animations**: React Native Reanimated ~4.1.0, @legendapp/motion ^2.5.3

## Development Commands

### Core Commands
```bash
# Start development server
npm start
# or npx expo start

# Platform-specific builds
npm run android    # Build for Android
npm run ios        # Build for iOS
npm run web        # Build for web

# Code quality
npm run lint       # Run ESLint

# Reset to blank template
npm run reset-project
```

### Build and Deployment
The app is configured for EAS (Expo Application Services) with auto-increment versioning for production builds. Add `eas.json` to root for EAS configuration.

## Architecture & File Structure

### Directory Layout
```
SeaGateway-App-Owner/
├── app/                    # File-based routing (Expo Router)
│   ├── _layout.tsx        # Root layout with providers stack
│   ├── (tabs)/            # Main tab navigation screens
│   │   ├── index.tsx      # Home/Monitor screen
│   │   ├── tripInfo.tsx   # Trip information
│   │   ├── diary.tsx      # Diary/journal
│   │   ├── sensor.tsx     # Sensor data
│   │   └── setting.tsx    # Settings
│   ├── auth/login.tsx     # Authentication
│   └── modal.tsx          # Modal screens
├── components/            # Reusable UI components
│   ├── ui/                # Base UI components
│   ├── themed-*.tsx       # Themed components
│   └── [various components] # Feature-specific components
├── controller/            # Business logic layer (MVC pattern)
│   ├── AuthController.ts  # Authentication logic
│   ├── DeviceController.ts # Device management
│   ├── FishController.ts  # Fish-related operations
│   ├── MapController.ts   # Map functionality
│   └── TripController.ts  # Trip management
├── services/              # External service integrations
│   ├── map_service.ts     # Map services
│   ├── device_events.ts   # Device event handling
│   └── toast_service.tsx  # Toast notifications
├── state/                 # Zustand state stores
│   ├── use-trip.ts        # Trip state management
│   ├── use-banzones.ts    # Ban zone state
│   └── use-fish.ts        # Fish data state
├── hooks/                 # Custom React hooks
│   ├── use-i18n.ts        # Internationalization hook
│   ├── use-theme-context.tsx # Theme management
│   └── use-app-theme.ts   # Theme utilities (recommended)
├── config/                # Configuration files
│   ├── axios.ts           # API client with interceptors
│   ├── auth.ts            # Authentication configuration
│   └── localization/      # i18n setup
├── constants/             # App constants and API endpoints
├── utils/                 # Utility functions
├── locales/               # Translation files (en.json, vi.json)
└── assets/                # Static assets (images, fonts)
```

### Key Architecture Patterns

**MVC Structure**: Controllers handle business logic, state is managed separately, and components focus on UI.

**Service Layer**: External API integrations (maps, device events, notifications) are abstracted into services.

**File-based Routing**: Uses Expo Router's file system for automatic route generation.

**Theme System**: Sophisticated theme management with light/dark/system modes and comprehensive design tokens.

## Theme System

The app features an advanced theme system with **3 modes**: Light, Dark, and System (automatic). Theme preferences are persisted in AsyncStorage and synchronized with system changes.

### Theme Hooks (Usage Priority)
1. **`useAppTheme()`** (Recommended) - Full theme utilities with pre-built styles
2. **`useThemeContext()`** - Full control (themeMode, setThemeMode, colors)
3. **`useColorScheme()`** - Quick light/dark detection
4. **`useThemeColor()`** - Color overrides

### Themed Components
Use **ThemedView** and **ThemedText** for automatic theme application:
```tsx
import { ThemedText } from "@/components/themed-text";
import { ThemedView } from "@/components/themed-view";

<ThemedView>
  <ThemedText type="title">Title Text</ThemedText>
  <ThemedText type="subtitle">Subtitle</ThemedText>
  <ThemedText type="default">Regular Text</ThemedText>
  <ThemedText type="link">Link Text</ThemedText>
</ThemedView>
```

### Pre-built Styles (from useAppTheme)
```tsx
const { styles, utils } = useAppTheme();

// Containers
styles.container     // Flex 1 with theme background
styles.surface       // Surface with padding, border radius
styles.card          // Card with shadow, elevation

// Buttons
styles.primaryButton          // Primary button colors
styles.secondaryButton        // Secondary button with border
styles.primaryButtonText      // White text for primary
styles.secondaryButtonText    // Theme text for secondary

// Status containers
styles.successContainer       // Success background with border
styles.warningContainer      // Warning background with border
styles.errorContainer        // Error background with border

// Utilities
utils.isDark                 // Boolean theme check
utils.toggleTheme()          // Toggle light ↔ dark
utils.getOpacityColor("primary", 0.1) // RGBA with opacity
```

## Internationalization (i18n)

Supports English (`en`) and Vietnamese (`vi`) with automatic device locale detection and persistent storage.

### Translation Hook
```tsx
import { useI18n } from "@/hooks/use-i18n";

const { t, locale, setLocale, isLoaded } = useI18n();

// Translations
t("auth.login")           // Simple key
t("auth.welcome", { name: "John" }) // With interpolation
```

### Translation Files
Located in `locales/`:
- `en.json` - English translations
- `vi.json` - Vietnamese translations

Structure uses nested keys for organization (e.g., `"auth.login.title"`).

## API & State Management

### API Configuration
Base URL: `https://sgw.gms.vn`
- Automatic JWT token handling via Axios interceptors
- 401 error handling with automatic logout
- Comprehensive error messaging with toast notifications
- 20-second timeout for all requests

### State Management (Zustand)
```tsx
// Trip state
import { useTrip } from "@/state/use-trip";

const { trip, getTrip, error, loading } = useTrip();
```

Key stores:
- **useTrip** - Trip data and operations
- **useBanzones** - Restricted area management
- **useFish** - Fish species data

### Authentication Flow
JWT-based with AsyncStorage persistence:
1. Login via `/api/tokens`
2. Token stored and auto-added to requests
3. 401 responses trigger automatic logout
4. Auth state managed through AuthController

## Maritime-Specific Features

### Core Functionality
- **GPS Tracking**: Real-time vessel position tracking
- **Trip Management**: Commercial fishing trip logging and monitoring
- **Sensor Data**: Various marine sensor integration
- **Ban Zones**: Restricted fishing area enforcement
- **Fish Species**: Catch logging with species identification
- **SOS System**: Emergency alert functionality
- **Map Integration**: Maritime charts and zone visualization

### API Endpoints
Key maritime APIs:
- `/api/sgw/gps` - GPS tracking data
- `/api/sgw/trip` - Trip management
- `/api/sgw/fishingLog` - Catch logging
- `/api/sgw/banzones` - Restricted zones
- `/api/sgw/sos` - Emergency alerts
- `/api/sgw/fishspecies` - Fish species data

## Development Setup & Configuration

### TypeScript Configuration
- Strict mode enabled
- Path aliases: `@/*` maps to root directory
- Extends Expo base TypeScript config

### TailwindCSS Configuration
- Comprehensive design system with CSS variables
- Custom color palette (primary, secondary, tertiary, error, success, warning)
- Custom font families (Inter, Jakarta Sans, Roboto, Source Code Pro)
- Custom shadow utilities and spacing
- Dark mode support via class-based switching

### Metro Bundler
- Custom metro.config.js with NativeWind integration
- Optimized for React Native with CSS-in-JS support

## Development Best Practices

### Component Development
- Use themed components for consistent theming
- Prefer `useAppTheme()` for UI components
- Leverage TailwindCSS for styling with NativeWind
- Follow file-based routing conventions

### State Management
- Use Zustand stores for complex state
- Keep controllers for business logic
- Use services for external integrations

### API Integration
- Use the configured Axios instance with interceptors
- Handle errors through the existing toast system
- Follow the established JWT authentication flow

### Theme Development
- Use the comprehensive theme system for all UI elements
- Test all theme modes (light/dark/system)
- Leverage pre-built styles from useAppTheme()
- Use opacity colors for subtle backgrounds and overlays

### Internationalization
- Always use the `t()` function for user-facing text
- Add translations to both en.json and vi.json
- Follow nested key structure for organization
- Test with both locales


## Build app

- Add eas.json file to root folder and add this:

```
{
  "cli": {
    "version": ">= 16.27.0",
    "appVersionSource": "remote"
  },
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal"
    },
    "preview": {
      "android": {
        "buildType": "apk"
      },
      "distribution": "internal"
    },
    "production": {
      "autoIncrement": true
    }
  },
  "submit": {
    "production": {}
  }
}

```