# sdil/goakt-realtimemap architecture

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

- Interactive diagram: https://gitdiagram.com/sdil/goakt-realtimemap
- Repository: https://github.com/sdil/goakt-realtimemap

## Overview

##### Project type and purpose
- This is a full‑stack, real‑time Vehicle Tracking System written in Go.
- It provides a browser‑based UI (`index.html`) that displays vehicle positions on a map, real‑time updates over WebSockets, and a REST API to fetch the current position of any vehicle.
- The system employs the `goakt` actor framework to manage each vehicle as an actor, buffering updates in memory and persisting them to a SQLite database every minute.

##### File structure
Top‑level files and directories:
- main.go – application entry point: sets up HTTP routes, WebSocket handlers, actor system
- ingress.go – defines HTTP routing (REST endpoints + WebSocket upgrade)
- vehicle.go – implements the Vehicle actor behavior (update processing, buffering, flush to DB)
- index.html – frontend map UI + WebSocket client code
- migrations.sql – schema setup for SQLite (vehicle_position table)
- protos/vehicle/vehicle.proto – Protocol Buffers schema for vehicle messages
- pb/vehicle.pb.go – generated Go code from the `.proto`
- Dockerfile, docker‑compose.yaml, Earthfile – containerization & build automation
- buf.yaml, buf.gen.yaml – Protobuf linting & generation config

##### README for additional insights
- Tech stack: Go, SQLite, WebSockets, goakt actors, Protocol Buffers, vanilla HTML/JS.
- Endpoints:
- GET /vehicle?id={vehicle_id} → REST JSON response
- WS   /realtime-vehicle    → push updates to clients
- Persistence: buffered updates every 1 minute to reduce DB load.
- Cluster mode: containerized using Docker Compose for multi‑instance deployment.

a. Main components
- Frontend (Browser)
- HTTP/WebSocket Server
- goakt Actor System (Vehicle Actors)
- Persistence Layer (SQLite DB)
- Protocol Buffers (message serialization)
- Build & Deployment (Docker, Earthly, buf)

b. Relationships & interactions
1. Browser loads index.html via HTTP.
2. Browser opens WebSocket (`/realtime-vehicle`) to the HTTP server.
3. HTTP server routes incoming WebSocket messages (simulated “position updates”) into the Actor System.
4. Vehicle Actor buffers updates in memory.
5. Every minute, Persistence Manager flushes buffered updates to SQLite.
6. Actor System publishes updates back over WebSocket to all connected browsers.
7. Browser renders new positions on the map.
8. On-demand REST calls (GET /vehicle) query SQLite and return JSON.

c. Architectural patterns & design principles
- Actor Model (goakt) isolates per‑vehicle state, concurrency, and failure isolation.
- Layered separation:
– Transport layer (HTTP router, WebSocket handler)
– Business logic (actors)
– Data access (SQLite via migrations.sql)
- Buffering & batching (flush every 1 minute) to optimize persistence.
- Protocol Buffers for compact, language‑neutral message definitions.

d. Key technologies & frameworks
- Go 1.23+
- goakt actor framework
- Gorilla/WebSocket (or Go’s native upgrader)
- SQLite3
- Protocol Buffers + buf
- Docker, Docker Compose, Earthly

##### Essential Details
- Protocol Buffer process (vehicle.proto → `pb/vehicle.pb.go` → used by server & actors).
- Scale‑out: multiple Vehicle Actors running concurrently in the goakt system.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Browser["Browser"]:::frontend
        UI["index.html + JS WebSocket Client"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Service" 
        direction TB
        Entry["main.go (App Entry)"]:::backend
        Router["HTTP Router (ingress.go)"]:::backend
        REST["REST API Handler"]:::backend
        WS["WebSocket Handler"]:::backend
        ProtoGen["Protocol Buffers Module"]:::backend
        Actors["Actor System\n(vehicle.go)"]:::actor
        Persist["Persistence Manager\n(buffer flush every 1min)"]:::backend
    end

    %% Database Layer
    subgraph "Database"
        direction TB
        DB["SQLite DB"]:::db
        Migrations["migrations.sql"]:::db
    end

    %% Build & Deploy
    subgraph "Build & Deploy"
        direction TB
        Docker["Dockerfile"]:::build
        Compose["docker-compose.yaml"]:::build
        Earthly["Earthfile"]:::build
        BufLint["buf.yaml & buf.gen.yaml"]:::build
    end

    %% Protocol Buffers Flow
    ProtoDef["protos/vehicle/vehicle.proto"]:::backend
    ProtoCode["pb/vehicle.pb.go"]:::backend

    %% Connections
    Browser -->|"load index.html"| UI
    UI -->|"HTTP GET /"| Entry
    Entry --> Router
    Router --> REST
    Router --> WS
    WS -->|"ingest updates"| Actors
    REST -->|"query on-demand"| DB
    Actors -->|"batch flush every 1min"| Persist
    Persist -->|"write to DB"| DB
    Actors -->|"broadcast updates"| WS
    WS -->|"push via WebSocket"| UI
    ProtoDef --> ProtoCode
    ProtoCode --> Actors
    ProtoCode --> REST

    %% Build & Deploy arrows
    Entry --> Docker
    Docker --> Compose
    Compose --> Earthly
    Compose --> BufLint

    %% Click Events
    click UI "https://github.com/sdil/goakt-realtimemap/blob/main/index.html"
    click Entry "https://github.com/sdil/goakt-realtimemap/blob/main/main.go"
    click Router "https://github.com/sdil/goakt-realtimemap/blob/main/ingress.go"
    click Actors "https://github.com/sdil/goakt-realtimemap/blob/main/vehicle.go"
    click Migrations "https://github.com/sdil/goakt-realtimemap/blob/main/migrations.sql"
    click ProtoDef "https://github.com/sdil/goakt-realtimemap/blob/main/protos/vehicle/vehicle.proto"
    click ProtoCode "https://github.com/sdil/goakt-realtimemap/blob/main/pb/vehicle.pb.go"
    click Docker "https://github.com/sdil/goakt-realtimemap/tree/main/Dockerfile"
    click Compose "https://github.com/sdil/goakt-realtimemap/blob/main/docker-compose.yaml"
    click Earthly "https://github.com/sdil/goakt-realtimemap/tree/main/Earthfile"
    click BufLint "https://github.com/sdil/goakt-realtimemap/blob/main/buf.yaml"
    click BufLint "https://github.com/sdil/goakt-realtimemap/blob/main/buf.gen.yaml"

    %% Styles
    classDef frontend fill:#e0f7e9,stroke:#2e8b57,color:#145a32
    classDef backend fill:#d0e1f9,stroke:#2a4f7d,color:#112b4e
    classDef actor fill:#f3e5f5,stroke:#8e24aa,color:#4a148c
    classDef db fill:#ffe0b2,stroke:#f57c00,color:#e65100
    classDef build fill:#eceff1,stroke:#607d8b,color:#263238
```
