# cook1ek1w1/waypoint-maker architecture

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

- Interactive diagram: https://gitdiagram.com/cook1ek1w1/waypoint-maker
- Repository: https://github.com/cook1ek1w1/waypoint-maker

## Overview

##### Project Type and Purpose
- Waypoint Maker is a full‑stack Next.js web application for building, validating, and organizing waypoint missions for UAVs.
- It combines a rich React‑based frontend (pages, layouts, map and editing UI) with server‑side API routes and a database layer (Prisma).

##### File Structure
- src/app/… contains Next.js pages and API routes (including auth at src/app/api/auth).
- src/components/… hosts React UI components (dashboard, map layers, modals, toolbars, editors).
- src/lib/… implements core mission‑generation logic (dubins curves, optimisation, I/O routines).
- src/util/… houses utility modules (authentication client, context providers for map/waypoints/vehicle).
- prisma/schema.prisma defines the DB schema.
- Configuration files (next.config.js, postcss.config.js, tailwind.config.ts) set up build and styling.

##### README
- Confirms tech stack: Bun runtime, Next.js, Prisma.
- Outlines features: grouping, validation, layer toggling.
- Mentions environment variables and typical dev/test/build commands.

##### Main Components
a. Frontend Layer
- Next.js React UI (pages, components, contexts)
- Rendering module (Leaflet or custom mapController + layers)
- State management (React Contexts: WaypointContext, MapContext, VehicleTypeContext)
b. API Layer
- Next.js server‑side API routes (src/app/api/auth, other REST or RPC endpoints)
- Authentication handler (session, token verification)
c. Business Logic Layer
- Core libraries in src/lib: waypoint generation, optimisation algorithms, file import/export (missionIO)
- Utility modules for geometry, maths, data conversion
d. Persistence Layer
- Prisma ORM connected to a relational database (PostgreSQL, MySQL, etc.)
- prisma/schema.prisma defines entities (Waypoint, Mission, User, etc.)
e. External Services
- OAuth or external auth provider used by the auth API
- Optional “cloud sync” storage endpoint for mission I/O
f. Development Tooling & CI
- Bun runtime, build scripts, CI workflow (.github/workflows/bun-test.yml)

##### Relationships and Data Flows
- User → Browser → Next.js Frontend
- Frontend dispatches actions (create/edit waypoints, validate, group) → calls API routes
- API routes invoke business logic modules (lib/dubins, lib/optimisation, lib/missionIO)
- Business logic reads/writes via Prisma to the database
- Frontend subscribes to state via React Contexts, re‑renders map and UI
- External auth service is called during login flows
- Cloud sync endpoints are invoked from modal I/O components

##### Architectural Patterns & Principles
- Separation of Concerns: UI vs. API vs. core logic vs. persistence
- Modular design: each feature set lives in its own directory (map layers, modals, waypointIO, optimisation)
- Context-based state management for global state (React Context Providers)
- API facades: Next.js Routes expose clean handlers that delegate to utility libraries

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        Pages["Next.js Pages"]:::frontend
        Layout["Next.js Layout"]:::frontend
        MissionPage["Mission Page"]:::frontend

        subgraph "Map Rendering Module"
            direction TB
            WaypointMap["WaypointMap"]:::frontend
            MapController["mapController"]:::frontend
            ActiveLayer["activeLayer"]:::frontend
            DubinsLayer["dubinsLayer"]:::frontend
            GeofenceLayer["geofenceLayer"]:::frontend
            MarkerLayer["markerLayer"]:::frontend
        end

        subgraph "React UI Components"
            direction TB
            DashboardComp["dashboard"]:::frontend
            MarkerComp["marker"]:::frontend
            ModalComp["modal"]:::frontend
            ToolBarComp["toolBar"]:::frontend
            UIComp["ui"]:::frontend
            VehicleTypeComp["vehicleType"]:::frontend
            WaypointEditorComp["waypointEditor"]:::frontend
            WaypointListComp["waypointList"]:::frontend
            SubMissionListComp["subMissionList"]:::frontend
        end

        subgraph "State Management (React Contexts)"
            direction TB
            MapCtx["MapContext & Provider"]:::frontend
            WaypointCtx["WaypointContext & Provider"]:::frontend
            VehicleCtx["VehicleTypeContext & Provider"]:::frontend
            CloudWaypointCtx["cloudWaypointProvider"]:::frontend
        end
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        AuthAPI["Auth Routes"]:::backend
        OtherAPI["Mission CRUD/Validation Routes"]:::backend
    end

    %% Business Logic Layer
    subgraph "Logic Layer"
        direction TB
        subgraph "Dubins Curve Generation"
            direction TB
            DubinsTS["dubins.ts"]:::backend
            DubinWaypoints["dubinWaypoints.ts"]:::backend
            GeometryDubins["geometry.ts"]:::backend
        end

        subgraph "Optimisation Algorithms"
            direction TB
            Genetic["genetic.ts"]:::backend
            Gradient["gradient.ts"]:::backend
            ParticleSwarm["particleSwarm.ts"]:::backend
        end

        subgraph "Mission I/O Routines"
            direction TB
            MissionCommon["common.ts"]:::backend
            WaypointToFile["waypointToFile.ts"]:::backend
        end

        subgraph "Geometry & Maths Utilities"
            direction TB
            GeometryMath["geometry.ts"]:::backend
            Vector["vector.ts"]:::backend
            WorldConversion["conversion.ts"]:::backend
            WorldDistance["distance.ts"]:::backend
        end

        subgraph "Waypoint Collection Management"
            direction TB
            WaypointCollection["waypointCollection.ts"]:::backend
            Defaults["defaults.ts"]:::backend
            WaypointFns["fns.ts"]:::backend
        end
    end

    %% Persistence Layer
    subgraph "Data Layer"
        direction TB
        PrismaSchema["schema.prisma"]:::data
        PrismaClient["prisma.ts"]:::data
        Database[(Database)]:::data
    end

    %% External Services
    AuthProvider((External Auth Provider)):::external
    CloudSync((Cloud Sync Service)):::external

    %% Connections
    Pages -->|HTTP Request| AuthAPI
    Pages -->|HTTP Request| OtherAPI
    MissionPage -->|HTTP Request| OtherAPI

    AuthAPI -->|calls| DubinsTS
    OtherAPI -->|invokes| DubinsTS
    OtherAPI --> OptimisationGen[Optimisation Module]
    DubinsTS --> PrismaClient
    Genetic --> PrismaClient
    MissionCommon -->|read/write| PrismaClient
    PrismaClient -->|SQL| Database

    AuthAPI -->|OAuth| AuthProvider
    WaypointToFile -->|sync| CloudSync

    %% Arrows from API to logic groups
    AuthAPI --> DubinsTS
    OtherAPI --> DubinWaypoints
    OtherAPI --> MissionCommon
    OtherAPI --> Genetic

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef backend fill:#d4edda,stroke:#28a745,color:#000;
    classDef data fill:#fff3cd,stroke:#ffcc00,color:#000;
    classDef external fill:#f8d7da,stroke:#dc3545,color:#000;

    class Pages,Layout,MissionPage,WaypointMap,MapController,ActiveLayer,DubinsLayer,GeofenceLayer,MarkerLayer,DashboardComp,MarkerComp,ModalComp,ToolBarComp,UIComp,VehicleTypeComp,WaypointEditorComp,WaypointListComp,SubMissionListComp,MapCtx,WaypointCtx,VehicleCtx,CloudWaypointCtx frontend;
    class AuthAPI,OtherAPI,DubinsTS,DubinWaypoints,GeometryDubins,Genetic,Gradient,ParticleSwarm,MissionCommon,WaypointToFile,GeometryMath,Vector,WorldConversion,WorldDistance,WaypointCollection,Defaults,WaypointFns backend;
    class PrismaSchema,PrismaClient,Database data;
    class AuthProvider,CloudSync external;

    %% Click Events
    click Pages "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/app/page.tsx"
    click Layout "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/app/layout.tsx"
    click MissionPage "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/app/m/[missionid]/page.tsx"
    click WaypointMap "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/components/map/WaypointMap.tsx"
    click MapController "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/components/map/mapController.tsx"
    click ActiveLayer "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/components/map/activeLayer.tsx"
    click DubinsLayer "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/components/map/dunbinsLayer.tsx"
    click GeofenceLayer "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/components/map/geofenceLayer.tsx"
    click MarkerLayer "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/components/map/markerLayer.tsx"
    click DashboardComp "https://github.com/cook1ek1w1/waypoint-maker/tree/main/src/components/dashboard"
    click MarkerComp "https://github.com/cook1ek1w1/waypoint-maker/tree/main/src/components/marker"
    click ModalComp "https://github.com/cook1ek1w1/waypoint-maker/tree/main/src/components/modal"
    click ToolBarComp "https://github.com/cook1ek1w1/waypoint-maker/tree/main/src/components/toolBar"
    click UIComp "https://github.com/cook1ek1w1/waypoint-maker/tree/main/src/components/ui"
    click VehicleTypeComp "https://github.com/cook1ek1w1/waypoint-maker/tree/main/src/components/vehicleType"
    click WaypointEditorComp "https://github.com/cook1ek1w1/waypoint-maker/tree/main/src/components/waypointEditor"
    click WaypointListComp "https://github.com/cook1ek1w1/waypoint-maker/tree/main/src/components/waypointList"
    click SubMissionListComp "https://github.com/cook1ek1w1/waypoint-maker/tree/main/src/components/subMissionList"
    click MapCtx "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/util/context/MapContext.tsx"
    click MapCtx "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/util/context/MapProvider.tsx"
    click WaypointCtx "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/util/context/WaypointContext.tsx"
    click WaypointCtx "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/util/context/WaypointProvider.tsx"
    click VehicleCtx "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/util/context/VehicleTypeContext.tsx"
    click VehicleCtx "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/util/context/VehicleTypeProvider.tsx"
    click CloudWaypointCtx "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/util/context/cloudWaypointProvider.tsx"
    click AuthAPI "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/app/api/auth/[...all]/route.ts"
    click DubinsTS "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/lib/dubins/dubins.ts"
    click DubinWaypoints "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/lib/dubins/dubinWaypoints.ts"
    click GeometryDubins "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/lib/dubins/geometry.ts"
    click Genetic "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/lib/optimisation/genetic.ts"
    click Gradient "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/lib/optimisation/gradient.ts"
    click ParticleSwarm "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/lib/optimisation/particleSwarm.ts"
    click MissionCommon "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/lib/missionIO/common.ts"
    click WaypointToFile "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/lib/missionIO/waypointToFile.ts"
    click GeometryMath "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/lib/math/geometry.ts"
    click Vector "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/lib/math/vector.ts"
    click WorldConversion "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/lib/world/conversion.ts"
    click WorldDistance "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/lib/world/distance.ts"
    click WaypointCollection "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/lib/waypoints/waypointCollection.ts"
    click Defaults "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/lib/waypoints/defaults.ts"
    click WaypointFns "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/lib/waypoints/fns.ts"
    click PrismaSchema "https://github.com/cook1ek1w1/waypoint-maker/blob/main/prisma/schema.prisma"
    click PrismaClient "https://github.com/cook1ek1w1/waypoint-maker/blob/main/src/util/prisma.ts"
```
