# worldfishcenter/tracks-explorer architecture

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

- Interactive diagram: https://gitdiagram.com/worldfishcenter/tracks-explorer
- Repository: https://github.com/worldfishcenter/tracks-explorer

## Overview

##### Project type and purpose
- This is a full-stack, single-page web application (“PESKAS Tracks Explorer”) for viewing and analyzing vessel-tracking data on an interactive map.
- The frontend is built with React (TypeScript), Vite, and Mapbox GL. The backend is an Express.js server (for local/dev) and a set of Vercel Serverless Functions (for production), persisting data in MongoDB.

##### File structure
- Top-level:
- src/ – React app source
- public/ – static assets (favicon, manifest, service worker)
- server/ – Express server entry point for local development
- api/ – Vercel Serverless Function handlers (e.g. api/auth/login.js)
- scripts/, docs/, config files (tsconfig, vite.config, eslint.config, .env.example)
- Patterns:
- src/api – client-side API service wrappers
- src/components, src/pages, src/layouts – React component hierarchy (map, dashboard, login)
- src/hooks, src/contexts – state management (AuthContext, custom hooks)
- src/i18n – localization support
- Configuration: package.json scripts to run dev:all (Vite + Express concurrently), dev:server (Express only), and deploy via Vercel.

##### README insights
- Confirms two servers: Vite frontend (port 5173) + Express backend (port 3001) in dev.
- Production uses Vercel Hosting: static build for frontend, Serverless for API.
- MongoDB authentication (using IMEI as username), Mapbox token for maps.

##### Final recommendations
- Don’t omit details like environment‐variable configuration or build process (Vite build → static bundle).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer" 
        direction TB
        ReactMain["main.tsx"]:::frontend
        ReactApp["App.tsx"]:::frontend
        subgraph "Layouts & Pages"
            MainLayout["MainLayout.tsx"]:::frontend
            Dashboard["Dashboard.tsx"]:::frontend
            Login["Login.tsx"]:::frontend
        end
        Components["src/components"]:::frontend
        subgraph "State Management & Hooks"
            AuthContext["AuthContext.tsx"]:::frontend
            UseTripData["useTripData.ts"]:::frontend
            UseLiveLocations["useLiveLocations.ts"]:::frontend
            UseLanguage["useLanguage.ts"]:::frontend
            UseMobileDetection["useMobileDetection.ts"]:::frontend
            UseVesselSelection["useVesselSelection.ts"]:::frontend
        end
        subgraph "Localization (i18n)"
            I18nIndex["index.ts"]:::frontend
            LocaleEN["en.json"]:::frontend
            LocaleSW["sw.json"]:::frontend
        end
        subgraph "Config & Utils"
            MapConfig["mapConfig.ts"]:::frontend
            MapData["mapData.ts"]:::frontend
        end
        subgraph "Styles & Assets"
            Styles["src/styles"]:::frontend
            PublicAssets["public"]:::frontend
        end
    end

    %% Client-side API Services
    subgraph "Client-side API Services"
        direction TB
        AuthService["authService.ts"]:::api
        PelagicDataService["pelagicDataService.ts"]:::api
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        direction TB
        DevServer["Express Server"]:::backend
        ProdServerless["Serverless: auth/login.js"]:::backend
    end

    %% Database
    MongoDB["MongoDB Atlas"]:::database

    %% External Services
    Mapbox["Mapbox API"]:::external

    %% Connections
    ReactApp -->|"uses"| AuthService
    ReactApp -->|"uses"| PelagicDataService
    ReactApp -->|"requests tiles"| Mapbox
    AuthService -->|"HTTP/HTTPS"| DevServer
    PelagicDataService -->|"HTTP/HTTPS"| DevServer
    AuthService -->|"HTTP/HTTPS"| ProdServerless
    PelagicDataService -->|"HTTP/HTTPS"| ProdServerless
    DevServer -->|"queries"| MongoDB
    ProdServerless -->|"queries"| MongoDB

    %% Click Events
    click ReactMain "https://github.com/worldfishcenter/tracks-explorer/blob/main/src/main.tsx"
    click ReactApp "https://github.com/worldfishcenter/tracks-explorer/blob/main/src/App.tsx"
    click MainLayout "https://github.com/worldfishcenter/tracks-explorer/blob/main/src/layouts/MainLayout.tsx"
    click Dashboard "https://github.com/worldfishcenter/tracks-explorer/blob/main/src/pages/Dashboard.tsx"
    click Login "https://github.com/worldfishcenter/tracks-explorer/blob/main/src/pages/Login.tsx"
    click Components "https://github.com/worldfishcenter/tracks-explorer/tree/main/src/components"
    click AuthContext "https://github.com/worldfishcenter/tracks-explorer/blob/main/src/contexts/AuthContext.tsx"
    click UseTripData "https://github.com/worldfishcenter/tracks-explorer/blob/main/src/hooks/useTripData.ts"
    click UseLiveLocations "https://github.com/worldfishcenter/tracks-explorer/blob/main/src/hooks/useLiveLocations.ts"
    click UseLanguage "https://github.com/worldfishcenter/tracks-explorer/blob/main/src/hooks/useLanguage.ts"
    click UseMobileDetection "https://github.com/worldfishcenter/tracks-explorer/blob/main/src/hooks/useMobileDetection.ts"
    click UseVesselSelection "https://github.com/worldfishcenter/tracks-explorer/blob/main/src/hooks/useVesselSelection.ts"
    click I18nIndex "https://github.com/worldfishcenter/tracks-explorer/blob/main/src/i18n/index.ts"
    click LocaleEN "https://github.com/worldfishcenter/tracks-explorer/blob/main/src/i18n/locales/en.json"
    click LocaleSW "https://github.com/worldfishcenter/tracks-explorer/blob/main/src/i18n/locales/sw.json"
    click MapConfig "https://github.com/worldfishcenter/tracks-explorer/blob/main/src/config/mapConfig.ts"
    click MapData "https://github.com/worldfishcenter/tracks-explorer/blob/main/src/utils/mapData.ts"
    click Styles "https://github.com/worldfishcenter/tracks-explorer/tree/main/src/styles"
    click PublicAssets "https://github.com/worldfishcenter/tracks-explorer/tree/main/public"
    click DevServer "https://github.com/worldfishcenter/tracks-explorer/blob/main/server/server.js"
    click ProdServerless "https://github.com/worldfishcenter/tracks-explorer/blob/main/api/auth/login.js"
    click EnvExample "https://github.com/worldfishcenter/tracks-explorer/blob/main/.env.example"
    click ViteConfig "https://github.com/worldfishcenter/tracks-explorer/blob/main/vite.config.ts"
    click VercelConfig "https://github.com/worldfishcenter/tracks-explorer/blob/main/vercel.json"
    click TsConfig "https://github.com/worldfishcenter/tracks-explorer/blob/main/tsconfig.json"
    click TsConfigApp "https://github.com/worldfishcenter/tracks-explorer/blob/main/tsconfig.app.json"
    click PackageJSON "https://github.com/worldfishcenter/tracks-explorer/blob/main/package.json"
    click PackageLock "https://github.com/worldfishcenter/tracks-explorer/blob/main/package-lock.json"

    %% Styles
    classDef frontend fill:#D6EAF8,stroke:#21618C,color:#1B4F72
    classDef api fill:#D1F2EB,stroke:#148F77,color:#0E6251
    classDef backend fill:#D5F5E3,stroke:#239B56,color:#196F3D
    classDef database fill:#FCF3CF,stroke:#B7950B,color:#7D6608
    classDef external fill:#E5E8E8,stroke:#85929E,color:#566573
```
