Skip to content

Developer Setup

Bosaj edited this page Oct 18, 2026 · 3 revisions

🛠️ Developer Setup & Architecture Guide

Welcome to the technical implementation guide for L7OT (الحوت).


💻 Tech Stack & Dependencies

  • Frontend Framework: React 19 + TypeScript 5
  • Build Tooling: Vite 8.x + Rollup
  • Styling Engine: Tailwind CSS v4 + @tailwindcss/vite
  • Typography: @fontsource/amiri, @fontsource/ibm-plex-sans-arabic, @fontsource-variable/fraunces, @fontsource-variable/jetbrains-mono
  • Iconography: lucide-react
  • Testing: Vitest 5.x + @testing-library/react + jsdom
  • PWA: vite-plugin-pwa (offline caching and service workers)

🚀 Local Development Setup

1. Clone Repository

git clone https://github.com/Bosaj/l7ot.git
cd l7ot

2. Install Packages

npm install

3. Run Development Server

npm run dev

The server will start at http://localhost:5173/.

4. Running the Test Suite

L7OT maintains complete unit and integration test coverage:

# Run all tests once
npm run test

# Run tests in watch mode
npm run test:watch

5. Typecheck & Verification

# Strict TypeScript validation
npm run typecheck

# Full production build
npm run build

📁 Repository Directory Structure

l7ot/
├── src/
│   ├── components/
│   │   ├── AgreementsAndMarket.tsx    # International treaties & trade maps
│   │   ├── ChefL7ot.tsx               # Charmoula spice calculator
│   │   ├── CleaningTutorialModal.tsx  # Video filleting guides
│   │   ├── FishCard.tsx               # Species card with audio & regional badges
│   │   ├── FishModal.tsx              # Deep specimen modal + science APIs tab
│   │   ├── FishScanner.tsx            # Camera AI fish identification
│   │   ├── Header.tsx                 # Telemetry ticker, language & port GPS
│   │   ├── MarineWeatherAndApis.tsx   # Live waves & 8-API directory explorer
│   │   ├── MarketGuide.tsx            # 5-senses freshness test & landing ports
│   │   ├── NutritionCalculator.tsx    # Protein & Omega-3 100g/1kg calculator
│   │   ├── PriceBadge.tsx             # BiDi RTL/LTR natural currency component
│   │   ├── RecipeCard.tsx             # Coastal recipe cards
│   │   ├── RecipeModal.tsx            # Full recipe modal with video player
│   │   └── SoukBasketAndComparator.tsx# Head-to-head comparator & Kessal cart
│   ├── data/
│   │   ├── agreements.ts              # 10 International fisheries treaties
│   │   ├── fish.ts                    # 32 Moroccan marine species
│   │   ├── recipes.ts                 # 16 coastal Moroccan recipes
│   │   └── types.ts                   # Strict TypeScript contracts
│   ├── hooks/
│   │   └── useUserPortLocation.ts     # GPS Haversine port detector
│   ├── i18n/
│   │   └── strings.ts                 # Tri-lingual localization dictionary
│   ├── lib/
│   │   ├── charmoula.ts               # Gram-level spice ratios
│   │   ├── moroccanRegions.ts         # Port GPS coordinates & price multipliers
│   │   └── speech.ts                  # Moroccan Darija pronunciation engine
│   └── services/
│       └── marineApis.ts              # Real Open-Meteo, WoRMS, OBIS, FishBase clients
└── .github/
    └── workflows/
        ├── ci.yml                     # TypeScript + Vitest + Vite build
        ├── codeql.yml                 # CodeQL static analysis
        └── release.yml                # Automated GitHub release packaging

🧪 Testing Guidelines

When adding a new fish species, recipe, or API service:

  1. Ensure the species satisfies the Fish interface in src/data/types.ts.
  2. Provide all 4 regional dialects (chamal, oriental, centre, sud).
  3. Run npm run typecheck to confirm 0 compilation errors.
  4. Run npm run test to verify Vitest assertions.

Clone this wiki locally