README
¶
OpsGrid
A multi-tenant, real-time field-service platform built to explore relational isolation, transactional correctness, asynchronous delivery, realtime synchronization, observability, and production failure handling.
Status: Gate 0 (Foundation) is complete (
gate-0-foundation). Gate 1 (identity and tenancy) is complete (gate-1-identity-tenancy) — BFF sessions,/v1/me, org membership gate, authz map, demo seed, and shell UX. The evidence ledger is the authority for what is proven versus still planned.Hosted GitHub Actions are on;
mainrequires the CI passed check. Local verify:make check/make test-e2e— see Continuous integration.
What it does
OpsGrid is aimed at this operating loop (each piece lands and is proven at its gate):
Dispatchers drag work orders onto technicians' schedules on a live board. The database proves the technician is free and the change commits atomically with its audit record and its outbound event. Every other connected session updates without a refresh, and background workers handle notifications and reports. Each organization's data is isolated at three layers: application authorization, relational constraints, and PostgreSQL Row-Level Security.
Engineering highlights (planned → proven)
| Capability | Mechanism | Gate |
|---|---|---|
| Tenant isolation | App authorization + composite tenant FKs + forced RLS | G1 |
| Work-order integrity | Domain state machine, per-command audit, org-scoped numbering | G2 |
| No double-booking | PostgreSQL exclusion constraint on tstzrange |
G3 |
| Safe concurrent edits | Versioned aggregates, ETag / If-Match, 412 + diff UI |
G4 |
| Safe retries | Idempotency-Key claimed inside the business transaction |
G4 |
| Live updates | Authorized WebSocket topics, bounded queues, reconnect convergence | G5 |
| Reliable events | Transactional outbox → Redis Streams, idempotent consumers, DLQ | G6 |
| Direct uploads | Tenant-authorized presigned object-storage URLs | G7 |
| End-to-end tracing | OpenTelemetry across HTTP, SQL, outbox, and workers | G8 |
| Verified security | Threat model + OWASP ASVS 5.0.0 mapping | G9 |
| Measured performance | k6 scenarios, failure injection, published results | G10 |
Stack
Go 1.27 · PostgreSQL 18 · Redis 8 · Keycloak (OIDC, BFF sessions) · Garage/R2 (S3) · React 19 + TypeScript · TanStack Router/Query · Tailwind CSS v4 · OpenAPI 3.1 · OpenTelemetry · Prometheus · Tempo · Loki · Grafana · Docker Compose · GitHub Actions
Local setup
Requirements: a Docker runtime (OrbStack, Docker Desktop, or Colima), Go 1.27+, Node 24 LTS, and pnpm 12. Run make doctor to check your machine.
git clone https://github.com/Tony5897/opsgrid.git && cd opsgrid
make setup # toolchain, dependencies, browsers
make dev # build and start the stack; waits until healthy
| Open | URL |
|---|---|
| OpsGrid (API serves the SPA) | http://localhost:8080 |
Hot-reload UI (make web-dev) |
http://localhost:5173 |
Component workbench (make storybook) |
http://localhost:6006 |
Grafana (make dev-obs) |
http://localhost:3000 |
| Keycloak | http://localhost:8180 |
| Mailpit | http://localhost:8025 |
The full guide — every service, credential, command, test layer, and troubleshooting step — is in docs/development.md.
Documentation
- Developer guide
- Implementation plan
- Architecture overview
- Architecture decision records
- Evidence ledger
- Contributing
- Security policy
Tradeoffs
OpsGrid is intentionally a modular monolith, runs on Docker Compose rather than Kubernetes, and uses Redis Streams rather than Kafka. Each choice and its "revisit if" conditions are recorded in the ADRs.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package apispec embeds the OpenAPI contract so tests can validate real responses against it.
|
Package apispec embeds the OpenAPI contract so tests can validate real responses against it. |
|
cmd
|
|
|
api
command
Command api serves the OpsGrid HTTP API, the realtime gateway and the embedded web UI.
|
Command api serves the OpsGrid HTTP API, the realtime gateway and the embedded web UI. |
|
healthcheck
command
Command healthcheck probes a local HTTP endpoint and exits 0 on 2xx.
|
Command healthcheck probes a local HTTP endpoint and exits 0 on 2xx. |
|
migrate
command
Command migrate applies the embedded database migrations as the schema owner role.
|
Command migrate applies the embedded database migrations as the schema owner role. |
|
relay
command
Command relay publishes committed outbox events (transactional outbox relay).
|
Command relay publishes committed outbox events (transactional outbox relay). |
|
seed
command
Command seed upserts deterministic demo tenants (Cascade / Northstar).
|
Command seed upserts deterministic demo tenants (Cascade / Northstar). |
|
worker
command
Command worker runs OpsGrid background job consumers.
|
Command worker runs OpsGrid background job consumers. |
|
Package db embeds the SQL migrations and bootstrap scripts so every binary and test harness applies exactly the reviewed files.
|
Package db embeds the SQL migrations and bootstrap scripts so every binary and test harness applies exactly the reviewed files. |
|
internal
|
|
|
api
Package api adapts the generated OpenAPI strict-server interface (internal/api/gen) to OpsGrid's HTTP platform: request decoding errors and handler errors become RFC 9457 problems through httpx.WriteError, and the generated routes mount on a standard ServeMux.
|
Package api adapts the generated OpenAPI strict-server interface (internal/api/gen) to OpsGrid's HTTP platform: request decoding errors and handler errors become RFC 9457 problems through httpx.WriteError, and the generated routes mount on a standard ServeMux. |
|
api/apitest
Package apitest validates HTTP exchanges against the OpenAPI contract.
|
Package apitest validates HTTP exchanges against the OpenAPI contract. |
|
api/gen
Package gen provides primitives to interact with the openapi HTTP API.
|
Package gen provides primitives to interact with the openapi HTTP API. |
|
app
Package app is the composition root: the only package that wires platform components and domain modules together.
|
Package app is the composition root: the only package that wires platform components and domain modules together. |
|
platform/apperr
Package apperr defines the typed errors that domain and application code return.
|
Package apperr defines the typed errors that domain and application code return. |
|
platform/authz
Package authz is the application authorization layer (IMPLEMENTATION_PLAN §4.4).
|
Package authz is the application authorization layer (IMPLEMENTATION_PLAN §4.4). |
|
platform/authz/cmd/genmatrix
command
Command genmatrix writes docs/security/permission-matrix.md and packages/api-client/permissions.json from the static authz role map.
|
Command genmatrix writes docs/security/permission-matrix.md and packages/api-client/permissions.json from the static authz role map. |
|
platform/buildinfo
Package buildinfo exposes the version and commit baked in at build time:
|
Package buildinfo exposes the version and commit baked in at build time: |
|
platform/config
Package config loads typed, validated process configuration from the environment.
|
Package config loads typed, validated process configuration from the environment. |
|
platform/database
Package database owns every PostgreSQL connection and transaction in OpsGrid.
|
Package database owns every PostgreSQL connection and transaction in OpsGrid. |
|
platform/health
Package health implements liveness and readiness endpoints.
|
Package health implements liveness and readiness endpoints. |
|
platform/httpx
Package httpx contains the HTTP plumbing shared by OpsGrid processes: the middleware pipeline, RFC 9457 problem responses, strict JSON decoding and server construction.
|
Package httpx contains the HTTP plumbing shared by OpsGrid processes: the middleware pipeline, RFC 9457 problem responses, strict JSON decoding and server construction. |
|
platform/redisx
Package redisx creates instrumented Redis clients.
|
Package redisx creates instrumented Redis clients. |
|
platform/seed
Package seed loads deterministic demo tenants for local development (G1).
|
Package seed loads deterministic demo tenants for local development (G1). |
|
platform/telemetry
Package telemetry wires OpenTelemetry tracing and metrics and the structured slog logger used by every OpsGrid process.
|
Package telemetry wires OpenTelemetry tracing and metrics and the structured slog logger used by every OpsGrid process. |
|
platform/webui
Package webui serves the built single-page application from the API binary (ADR-020): same origin as the API, so no CORS and simple cookies.
|
Package webui serves the built single-page application from the API binary (ADR-020): same origin as the API, so no CORS and simple cookies. |