How sdil/goakt-realtimemap works
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.