Glossary¶

Domain and platform terms used throughout this site.

Domain¶

Term	Meaning
Track	One continuous recording session by a single vehicle. Identified by a UUIDv7 (so the ID encodes its creation timestamp). Has a route polyline, device info, frame count, and status.
Frame	One image extracted from the recording at a fixed cadence. Has a location (lat/lon/altitude), captured-at timestamp, sensor data (azimuth, speed, accuracy), and an H3 cell. Lives in S3; metadata in ClickHouse.
Frame batch	A group of frames committed together. Postgres table `FrameBatch` tracks lifecycle (`pending` → `committed`).
Detection	An ML-produced annotation on a frame: class (e.g. `pothole_v1`), bounding box, confidence.
Detour task	An assigned route segment a driver is asked to capture. Has a status state machine (`AVAILABLE` → `IN_PROGRESS` → `COMPLETED` → `VERIFIED` / `REJECTED` / `CANCELED`).
Territory	A geographic region used to scope detour tasks and coverage views.
Project	A higher-level grouping of territories with deadlines and progress.
Hold	A point-of-interest pin on the map (e.g. "verify this sign").
Coverage	The set of H3 cells touched by recorded frames within a window. Rendered as a PMTiles layer on the Planner map.
Custom layer	An admin-supplied vector layer (e.g. priority polygons, regional boundaries) sourced from an external RDBMS, rendered as PMTiles.
Reference item	An enum-like catalog entry (detector classes like `pothole_v1`, categories) backing API drop-downs.

Term	Meaning
Organization (Org)	The tenant boundary. Every domain entity is org-scoped.
OpenFGA	Relationship-based authorization engine. Models permissions as tuples like `(user:alice, can_view, track:abc)`.
BatchCheck	One OpenFGA call that resolves many permission lookups at once — used to avoid N+1 authz round-trips on list endpoints.
Permission	A check name in the FGA model. System-scoped: `CanManageOrganizations`, `CanManageRoles`. Org-scoped: `CanViewOrgTracks`, `CanManageUsers`, `CanManageTasks`, `CanManageProjects`.

Term	Meaning
Sense	The data-collection product (mobile + planner web + Sense API + Sense Worker).
Gen	The analytics product (gen web + Gen API).
Sense API	Dual-port .NET service (REST 8080 + gRPC 8081). Track lifecycle, frame metadata, task management, audit.
Sense Worker	.NET service running KafkaFlow consumers and Hangfire jobs. Recognition response handling, audit batching, PMTiles generation, Citylens sync.
Gen API	.NET service (REST 5501 + gRPC 5502). Dashboards, widgets, federated data sources.
Operations layer	The `IOperation<TParam, TResult>` pattern used in both Sense and Gen for business logic — keeps controllers thin.
HostBinding	Marker that picks which DI registrations belong to API vs. Worker (lets one `Core` project serve both processes).
Outbox	Daily-partitioned table in Postgres holding events to be relayed to Kafka. (Citylens-side only at present.)

Term	Meaning
`axion_sense`	Main Postgres database. Schemas: `public`, `road_data`, `planner`, `external`.
`axion_sense_tasks`	Separate Postgres database holding Hangfire job state and worker-only tables.
`axion_sense` (CH)	ClickHouse database. Tables `tracks`, `frames`, `detections`, `audit_log`.
`pg_partman`	Postgres extension that partitions large tables by time and prunes old partitions. We partition `TrackLogs` and `FrameBatches` monthly; Outbox-style tables daily.
PostGIS	Postgres spatial extension. Used for `geometry(PointZ, 4326)` on frame locations and GiST indexes.
H3	Uber's hexagonal hierarchical geospatial index. We index frames at resolution 9 and 12.
PMTiles	Single-file vector tile format (protomaps.com/docs/pmtiles) — efficient HTTP range reads from S3, no tile server needed.
`tippecanoe`	CLI that builds PMTiles from FlatGeobuf. Run inside the Worker pod (CPU-heavy).

Term	Meaning
KafkaFlow	.NET Kafka client framework with middleware pipeline. We use it for both producers and consumers.
Short-name header	KafkaFlow's mechanism for typed deserialization: messages carry a `message-type` header (e.g. `frame`, `track`, `recognition-request`) that maps to a CLR type.
Batch middleware	Singleton consumer middleware that creates an async DI scope per Kafka batch — needed because EF Core `DbContext` is scoped.

Term	Meaning
OTLP	OpenTelemetry Protocol. Both APIs and the Worker export traces, logs, and metrics over OTLP to the SigNoz collector.
SigNoz	Self-hosted observability platform (traces + logs + metrics + alerts) deployed via Helm.
Hangfire telemetry filter	Custom filter that emits OpenTelemetry spans for Hangfire job state changes.
Langfuse	Separate LLM-specific observability service used only by Gen Web's AI agent.