# 4proj-le-projet-d-une-vie/supmap-navigation architecture

> Architecture diagram of the GitHub repository 4proj-le-projet-d-une-vie/supmap-navigation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/4proj-le-projet-d-une-vie/supmap-navigation
- Repository: https://github.com/4proj-le-projet-d-une-vie/supmap-navigation

## Overview

##### Project type and purpose
- This is a standalone Go microservice (“supmap-navigation”) dedicated to real-time navigation: managing WebSocket connections, tracking positions, multicasting incidents and triggering dynamic route recalculations.
- It integrates with Redis (cache & Pub/Sub), a GIS service for routing, and an Incidents service.

##### File structure
- Top-level:
- cmd/main.go – service entry point
- internal/api – HTTP server & WebSocket handler
- internal/ws – WebSocket client & manager
- internal/cache – Redis session cache
- internal/subscriber – Redis Pub/Sub subscriber
- internal/incidents – incident multicaster
- internal/gis – GIS HTTP client & polyline utilities
- internal/navigation – domain models (Session, Route, Position)
- Configuration & Docker/CI manifests at root (.env, Dockerfile, GH Actions).

##### Key insights from README
- One primary `/ws` endpoint exposing WebSockets.
- Redis used both as a session cache and as a Pub/Sub broker for incoming incidents.
- External dependencies: supmap-incidents (publishes to Redis channel), supmap-gis (HTTP route recalculations).

a. Clients (mobile/Web)
b. API / WebSocket Manager
c. WebSocket Client instances
d. Session Cache (Redis – storage of session state)
e. Subscriber (Redis Pub/Sub)
f. Multicaster (incident router & route recalculation orchestrator)
g. GIS HTTP Client
h. External services: supmap-incidents, supmap-gis
i. Infrastructure: Redis instance(s)

##### Relationships & data flows
- Clients ↔ WebSocket Manager: bidirectional real-time messages (`init`, `position`, `incident`, `route`).
- Manager ↔ Redis Cache: read/write session state on every message.
- Subscriber ← Redis Pub/Sub: receives incident events from supmap-incidents.
- Subscriber → Multicaster → WebSocket Manager: multicast to affected clients.
- Multicaster → GIS Client → supmap-gis → Multicaster: route recalculation when needed → update cache & push to clients.

##### Architectural patterns & design principles
- Layered internal modularization (API, WS, cache, subscriber, incidents, GIS, domain models).
- Pub/Sub asynchronous event handling for incident notifications.
- Manager/Client pattern for WebSocket lifecycle and message dispatch.
- Cache-aside pattern with Redis for session persistence.
- Single-responsibility principle: each package has a focused role.

##### Technologies & frameworks
- Go modules, Go standard library (net/http, context).
- gorilla/websocket (or equivalent) for real-time connections.
- go-redis/v9 for cache & Pub/Sub.
- Docker & GitHub Actions for container build & CI/CD.

- Clear component labels and grouping (by package/function).
- Arrowheads indicating request vs. response.
- Boundaries distinguishing “supmap-navigation” from external services & infrastructure.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    Clients["Clients (mobile/Web)"]:::external
    supmap_incidents["supmap-incidents"]:::external
    supmap_gis["supmap-gis"]:::external
    Redis["Redis"]:::infra

    %% Service Boundary
    subgraph "supmap-navigation service"
        direction TB
        Main["cmd/main.go"]:::core
        Config["config loader\n(internal/config/config.go)"]:::core
        Server["HTTP/WebSocket Server\n(internal/api/server.go)"]:::core
        Handler["WebSocket Handler `/ws`\n(internal/api/handler.go)"]:::core
        Manager["WS Manager\n(internal/ws/manager.go)"]:::core
        ClientInst["WS Client Instances\n(internal/ws/client.go)"]:::core
        Cache["Session Cache Adapter\n(internal/cache/redis.go)"]:::core
        Subscriber["Redis Pub/Sub Subscriber\n(internal/subscriber/subscriber.go)"]:::core
        SubTypes["Subscriber Types\n(internal/subscriber/types.go)"]:::core
        Multicaster["Incident Multicaster\n(internal/incidents/multicaster.go)"]:::core
        IncTypes["Incident Types\n(internal/incidents/types.go)"]:::core
        GISClient["GIS HTTP Client\n(internal/gis/routing/client.go)"]:::core
        RoutingTypes["GIS Routing Types\n(internal/gis/routing/types.go)"]:::core
        Polyline["GIS Polyline Utils\n(internal/gis/polyline.go)"]:::core
        SessionModel["Domain Model: Session\n(internal/navigation/session.go)"]:::core
    end

    %% External to Service
    Clients -->|WebSocket `/ws` upgrade| Server
    supmap_incidents -->|Pub/Sub publish| Redis
    supmap_gis -->|HTTP requests| GISClient

    %% Internal flows
    Main --> Config
    Main --> Server
    Server --> Handler
    Handler -->|register/unregister| Manager
    Handler -->|incoming messages: init, position| Manager
    Manager --> ClientInst
    Manager -->|read/write session| Cache
    Manager -->|push updates| ClientInst

    Redis -->|subscribe channel| Subscriber
    Subscriber --> SubTypes
    Subscriber -->|incident events| Multicaster
    Multicaster --> IncTypes
    Multicaster -->|multicast to clients| Manager
    Multicaster -->|cache update| Cache
    Multicaster -->|route recalculation| GISClient
    GISClient --> RoutingTypes
    GISClient -->|HTTP request| supmap_gis
    GISClient -->|response| Multicaster
    Multicaster -->|new route| Manager

    %% Cache Pub/Sub connections
    Cache --> Redis

    %% Click Events
    click Main "https://github.com/4proj-le-projet-d-une-vie/supmap-navigation/blob/master/cmd/main.go"
    click Server "https://github.com/4proj-le-projet-d-une-vie/supmap-navigation/blob/master/internal/api/server.go"
    click Handler "https://github.com/4proj-le-projet-d-une-vie/supmap-navigation/blob/master/internal/api/handler.go"
    click Manager "https://github.com/4proj-le-projet-d-une-vie/supmap-navigation/blob/master/internal/ws/manager.go"
    click ClientInst "https://github.com/4proj-le-projet-d-une-vie/supmap-navigation/blob/master/internal/ws/client.go"
    click Cache "https://github.com/4proj-le-projet-d-une-vie/supmap-navigation/blob/master/internal/cache/redis.go"
    click Subscriber "https://github.com/4proj-le-projet-d-une-vie/supmap-navigation/blob/master/internal/subscriber/subscriber.go"
    click SubTypes "https://github.com/4proj-le-projet-d-une-vie/supmap-navigation/blob/master/internal/subscriber/types.go"
    click Multicaster "https://github.com/4proj-le-projet-d-une-vie/supmap-navigation/blob/master/internal/incidents/multicaster.go"
    click IncTypes "https://github.com/4proj-le-projet-d-une-vie/supmap-navigation/blob/master/internal/incidents/types.go"
    click Polyline "https://github.com/4proj-le-projet-d-une-vie/supmap-navigation/blob/master/internal/gis/polyline.go"
    click GISClient "https://github.com/4proj-le-projet-d-une-vie/supmap-navigation/blob/master/internal/gis/routing/client.go"
    click RoutingTypes "https://github.com/4proj-le-projet-d-une-vie/supmap-navigation/blob/master/internal/gis/routing/types.go"
    click SessionModel "https://github.com/4proj-le-projet-d-une-vie/supmap-navigation/blob/master/internal/navigation/session.go"
    click Config "https://github.com/4proj-le-projet-d-une-vie/supmap-navigation/blob/master/internal/config/config.go"

    %% Styles
    classDef external fill:#cccccc,stroke:#333,stroke-width:1px;
    classDef infra fill:#ccffcc,stroke:#333,stroke-width:1px;
    classDef core fill:#cce0ff,stroke:#333,stroke-width:1px;
```
