# thenilimnetwork/leafletint architecture

> Architecture diagram of the GitHub repository thenilimnetwork/leafletint, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thenilimnetwork/leafletint
- Repository: https://github.com/thenilimnetwork/leafletint

## Overview

##### Project Type and Purpose
- This is a full-stack, route-planning web application.
- Frontend: Next.js (app directory), React/TypeScript, Tailwind CSS, a library of UI components.
- Backend: Standalone Node.js microservice (“airport-backend”) serving airport data and lookup APIs.
- AI module: In‐repo “src/ai” flows that call an external LLM (“GEMINI_API_KEY”) for terrain suitability checks or guidance.
- External services: OpenRouteService, AirportDB, and Gemini LLM.

##### File Structure
- Top-level
– next.config.ts, tailwind.config.ts, tsconfig.json → Next.js/TypeScript config.
– apphosting.yaml → GCP App Engine deploy manifest for frontend or backend.
- airport-backend/
– server.js → Express (or vanilla) server exposing REST endpoints.
– data/airports.csv → Local CSV airport database.
– package.json → Node.js microservice dependencies.
- src/
– app/… → Next.js app-router pages & server actions (e.g., getRoute.ts).
– components/… → Reusable UI components (controls, map display, theming, plus a UI library under components/ui).
– ai/… → AI orchestration code: genkit.ts, flows/terrain-suitability-check.ts.
– lib/… → Utilities for airports, routing, generic helpers.
- Configuration files for Nix (.idx/dev.nix), VSCode, and environment variables (.env.local).

##### Key Architectural Patterns
- Full-stack separation: Next.js handles SSR/SSG and client-side UI, while the dedicated Node.js service handles raw data access.
- Modular AI flows: The “src/ai” layer abstracts calls to the LLM and implements domain-specific logic (terrain suitability).
- API layering: Frontend ↔ Next.js Server Actions ↔ airport-backend (or directly ↔ third-party APIs) ↔ External services.
- Shared utilities in “src/lib” to keep domain logic DRY.

##### Main Components and Their Interactions
a. Frontend (Next.js)
- React pages (src/app/page.tsx), components, hooks.
- Server Actions (getRoute) that can run on the server and call downstream APIs.
- UI layer issues calls to backend or AI module.
b. Backend Service (airport-backend)
- REST endpoint(s) (e.g., /airports, /airport/:id).
- Reads airports.csv, responds with JSON.
c. AI Module (src/ai)
- Orchestrates calls to Gemini API and optionally to OpenRouteService for terrain data.
- Returns augmented route insights.
d. External Services
- OpenRouteService API (routing, distance, elevation).
- AirportDB API (if used, based on AIRPORTDB_API_KEY).
- Gemini LLM (for reasoning or terrain checks).
e. Deployment & Dev Environment
- .idx/dev.nix for reproducible development.
- apphosting.yaml for GCP deployment.

##### Important Design Principles
- Separation of concerns: UI vs. business logic vs. data access vs. AI orchestration.
- Modularity: “src/components”, “src/lib”, “src/ai” layers.
- Scalability: The airport-backend can be containerized and autoscaled; Next.js can be deployed serverlessly.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser
    Browser["Browser/Client"]:::frontend

    %% Next.js App
    subgraph "Next.js App"
        Page["Page & Layout"]:::frontend
        Action["Server Action: getRoute"]:::frontend
        Controls["Controls Panel"]:::frontend
        MapDisplay["Map Display"]:::frontend
        ThemeProvider["Theme Provider"]:::frontend
        UILib["UI Library"]:::frontend
        HookMobile["use-mobile Hook"]:::frontend
        HookToast["use-toast Hook"]:::frontend
        UtilAirport["airportUtils"]:::backend
        UtilRoute["routeUtils"]:::backend
        UtilGeneric["utils"]:::backend
    end

    %% AI Module
    subgraph "AI Module"
        Genkit["genkit.ts"]:::backend
        DevConfig["dev.ts"]:::backend
        TerrainFlow["terrain-suitability-check.ts"]:::backend
    end

    %% Airport Backend Service
    subgraph "Airport-Backend Service"
        Server["server.js"]:::backend
        Package["package.json"]:::backend
        CSV[(airports.csv)]:::datastore
    end

    %% External Services
    subgraph "External Services"
        ORS["OpenRouteService API"]:::external
        AirportDB["AirportDB API"]:::external
        Gemini["Gemini LLM"]:::external
    end

    %% Connections
    Browser -->|"HTTP/SSR/CSR"| Page
    Page -->|"calls"| Action
    Page -->|"renders"| Controls
    Page -->|"renders"| MapDisplay
    Page -->|"wraps"| ThemeProvider
    Action -->|"uses"| UtilAirport
    Action -->|"uses"| UtilRoute
    Action -->|"uses"| UtilGeneric
    Action -->|"REST/JSON"| Server
    Action -->|"invokes"| Genkit
    Genkit -->|"orchestrates"| TerrainFlow
    Genkit -->|"loads configs"| DevConfig
    TerrainFlow -->|"HTTP/JSON (ENV: GEMINI_API_KEY)"| Gemini
    TerrainFlow -->|"HTTP/JSON (ORS_API_KEY)"| ORS
    Server -->|"reads CSV"| CSV
    Server -->|"responds REST/JSON"| Action
    AirportDB -->|"(optional) HTTP/JSON (AIRPORTDB_API_KEY)"| Server

    %% Click Events
    click Page "https://github.com/thenilimnetwork/leafletint/blob/main/src/app/page.tsx"
    click Action "https://github.com/thenilimnetwork/leafletint/blob/main/src/app/actions/getRoute.ts"
    click Controls "https://github.com/thenilimnetwork/leafletint/blob/main/src/components/controls-panel.tsx"
    click MapDisplay "https://github.com/thenilimnetwork/leafletint/blob/main/src/components/map-display.tsx"
    click ThemeProvider "https://github.com/thenilimnetwork/leafletint/blob/main/src/components/theme-provider.tsx"
    click UILib "https://github.com/thenilimnetwork/leafletint/tree/main/src/components/ui/"
    click HookMobile "https://github.com/thenilimnetwork/leafletint/blob/main/src/hooks/use-mobile.tsx"
    click HookToast "https://github.com/thenilimnetwork/leafletint/blob/main/src/hooks/use-toast.ts"
    click UtilAirport "https://github.com/thenilimnetwork/leafletint/blob/main/src/lib/airportUtils.ts"
    click UtilRoute "https://github.com/thenilimnetwork/leafletint/blob/main/src/lib/routeUtils.ts"
    click UtilGeneric "https://github.com/thenilimnetwork/leafletint/blob/main/src/lib/utils.ts"
    click Genkit "https://github.com/thenilimnetwork/leafletint/blob/main/src/ai/genkit.ts"
    click DevConfig "https://github.com/thenilimnetwork/leafletint/blob/main/src/ai/dev.ts"
    click TerrainFlow "https://github.com/thenilimnetwork/leafletint/blob/main/src/ai/flows/terrain-suitability-check.ts"
    click Server "https://github.com/thenilimnetwork/leafletint/blob/main/airport-backend/server.js"
    click Package "https://github.com/thenilimnetwork/leafletint/blob/main/airport-backend/package.json"
    click CSV "https://github.com/thenilimnetwork/leafletint/blob/main/airport-backend/data/airports.csv"
    click ORS "https://github.com/thenilimnetwork/leafletint/blob/main/apphosting.yaml"
    click DevConfig "https://github.com/thenilimnetwork/leafletint/blob/main/.idx/dev.nix"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0277BD,stroke-width:2px
    classDef backend fill:#E0F2F1,stroke:#00796B,stroke-width:2px
    classDef external fill:#FFF3E0,stroke:#F57C00,stroke-width:2px
    classDef datastore fill:#ECEFF1,stroke:#546E7A,stroke-width:2px,stroke-dasharray: 3 3
```
