Gateway Architecture

The SCS gateway platform uses a serverless-first Cloudflare backend, a Next.js portal, and a lightweight Go gateway agent.

flowchart LR
  subgraph Site["Site LAN"]
    Agent["Go gateway agent"]
    Queue["SQLite offline queue"]
    Linux["Linux gateway host"]
    Cameras["IP cameras"]
    NVRs["NVRs"]
  end

  subgraph Cloudflare["SCS Cloudflare account"]
    Worker["Worker API"]
    DO["Durable Object command sessions"]
    CFQueue["Cloudflare Queue"]
    D1["D1 database"]
    R2["R2 artifact storage"]
    KV["KV cache"]
    Pages["Pages portal"]
  end

  Linux --> Agent
  Cameras --> Agent
  NVRs --> Agent
  Agent --> Queue
  Agent -->|"HTTPS ingest and artifacts"| Worker
  Agent <-->|"WebSocket or polling commands"| DO
  Worker --> CFQueue
  CFQueue --> D1
  Worker --> D1
  Worker --> R2
  Worker --> KV
  Pages --> Worker

Device Model

The implementation uses the existing Sensor table as the common inventory model:

Device class	Sensor type	Relationship
Gateway	EDGE_CONTROLLER	Parent site/gateway device
Camera	CAMERA	Can be linked to a gateway through parentSensorId
NVR	NVR	Can be linked to a gateway through parentSensorId
Field device	Radar/ANPR/other existing types	Can report directly or through parent gateway scope

Command Model

Commands use a shared LwM2M-style registry with:

• command type
• object path
• operation
• timeout
• safety metadata
• parameter schema

The TypeScript registry in @smart-city/shared is the source of truth. The Go gateway-agent consumes generated command metadata from gateway-agent/internal/agent/command_registry_gen.go.

Metrics Model

The Go gateway agent reports to Worker ingest. Worker/D1 is the canonical storage path for portal metrics:

• gateway metrics
• camera metrics
• NVR metrics
• ingest receipts
• command audit
• command artifacts metadata

VictoriaMetrics is not required for the active SCS client/server flow.

Artifact Model

Large command outputs use R2-backed artifacts:

1. Gateway creates or receives a file such as a log bundle or NVR clip.
2. Gateway uploads it to the Worker command artifact endpoint.
3. Worker writes metadata to D1 and object bytes to R2.
4. Portal/clients use a tokenized download URL.
5. Command result stores artifact metadata, not binary payload bytes.