API Gateway

Repository: RoamView-Technologies/roamview-api-gateway

The API Gateway is the single public entry point for the RoamView web and mobile clients. It runs on the always-on App server next to the IoT Gateway, Streaming Service and Ingestion Service (see the Deployment Diagram on the Software Architecture wiki page).

flowchart TB
    subgraph GW["«module» roamview-api-gateway"]
        direction TB
        MAIN["«package» cmd/gateway<br/>main: load config, start server,<br/>graceful shutdown on SIGTERM"]

        subgraph INT["«package» internal"]
            direction TB
            SRV["«package» server<br/>NewRouter() · New()<br/>route table, http.Server timeouts"]
            HND["«package» handlers<br/>Health · Ready · Version<br/>NotImplemented · WriteJSON"]
            MW["«package» middleware<br/>RequestID · Logging · Recover · Chain"]
            PRX["«package» proxy<br/>New(target, prefix)<br/>reverse proxy to internal services"]
            CFG["«package» config<br/>Load() from env vars"]
            VER["«package» version<br/>Version · Commit (ldflags)"]
        end
    end

    STD["«library» Go standard library<br/>net/http · httputil · log/slog"]

    MAIN -->|«import»| CFG
    MAIN -->|«import»| SRV
    MAIN -->|«import»| VER
    SRV -->|«import»| CFG
    SRV -->|«import»| HND
    SRV -->|«import»| MW
    SRV -->|«import»| PRX
    HND -->|«import»| VER
    INT -.->|«use»| STD
    MAIN -.->|«use»| STD

Loading

Packages

Package	Responsibility	Depends on
cmd/gateway	Entry point. Loads config, builds the server, handles SIGINT/SIGTERM and shuts down gracefully	config, server, version
internal/server	Owns the route table and wraps it in middleware. Sets HTTP server timeouts	config, handlers, middleware, proxy
internal/handlers	Endpoints the gateway answers itself: /healthz, /readyz, /version, and 501 placeholders for API routes still to be built	version
internal/middleware	Cross-cutting concerns applied to every request: request ID, structured logging, panic recovery	—
internal/proxy	Forwards /api/v1/streaming/*, /api/v1/iot/*, /api/v1/ingestion/* to the matching internal service, returns 502 when it is down	—
internal/config	Reads PORT, APP_ENV, SHUTDOWN_TIMEOUT and upstream URLs from the environment	—
internal/version	Build version and commit, injected at link time	—

Dependencies only point downward: cmd → server → leaf packages. Leaf packages do not import each other (except handlers → version), so each can be tested on its own. Everything under internal/ cannot be imported by other modules.

Planned packages (later tasks)

Package	Purpose	Related use cases
internal/auth	JWT verification and role checks (User / On-Site Admin / System Admin)	UC-GU02, UC-OA02
internal/store	PostgreSQL repository for sites, meshes, annotations, scheduled_inspections	UC-GU03–05, UC-GU11, UC-OA01
internal/objectstore	Issues short-lived signed URLs for roamview-assets and roamview-media	UC-GU03, UC-GU04