# Omniglass

> Open, AV-native observability and control plane for AV and IT estates: one Go binary over PostgreSQL. A proposed, forward-looking architecture, published ahead of the code.

The full documentation as one file: [/llms-full.txt](/llms-full.txt).

## Overview

- [The CLI](/guides/cli/): The omniglass CLI: a generated client of the HTTP API, with a stable seam for hand-written commands.

## Architecture

- [Why Omniglass](/architecture/why/): What Omniglass is, what it is for, and why AV needs its own observability platform instead of an IT monitoring tool.
- [Architecture](/architecture/): The architecture told as one journey, following a single reading from the gear through its whole life to the answer and the action on it.
- [AI](/architecture/ai/): AI as a governed capability acting through the same API, permission, and scope seams as any caller, marked and audited, with human-in-the-loop gating.
- [Alarms and actions](/architecture/alarms-actions/): How Omniglass detects a condition with a stateful alarm and responds with an action, which is a flow when it has more than one step.
- [API](/architecture/api/): The API contract: AIP-style resources and :verb methods, cursor lists, a problem+json error envelope, idempotent writes, and long-running operations carried by the action row.
- [Audit](/architecture/audit/): The who-did-what record, written once in the same transaction as the change it describes.
- [Calculations](/architecture/calculations/): The rule families that run server-side over typed datapoints, and calc_rule in detail: cross-key and system-level derivation.
- [Cascade](/architecture/cascade/): How effective settings (config, variables, tags, rule-sets) are resolved for any entity and how the resolve view explains why a given value won.
- [Data collection](/architecture/collection/): Data collection is built from functions: a versioned component template declares interfaces and a set of functions, each a trigger plus a DAG of steps that runs at the edge and parses on the spot.
- [Core entities](/architecture/core-entities/): The estate model: component, system, location, and node as the structural entities, the variable-depth trees, and the exclusive-arc owner.
- [Datapoints](/architecture/datapoints/): The core data model: datapoints and their three kinds, provenance, the registries, key scope, divergence, fusion, and how a value reads back.
- [Events](/architecture/events/): Events: our semantic assertion that something happened, the event_type registry, and the four ways an event arrives.
- [Expressions](/architecture/expressions/): Omniglass expressions: one engine built on Expr and extended with Omniglass functions, behind every operator-authored expression leaf.
- [Files and blobs](/architecture/files/): A searchable file handle over a content-addressed blob store, behind the Storage Gateway.
- [Glossary](/architecture/glossary/): The authoritative glossary: every official term in the architecture, defined once.
- [Groups](/architecture/groups/): Named sets of component, system, location, or principal: static or dynamic membership, weighted, a cascade overlay and an access scope.
- [Health, KPIs, and service levels](/architecture/health/): Health as a first-class state rolled up to a global estate top, the KPIs every estate should track (availability, utilization), and SLI / SLO / SLA.
- [Identity and access](/architecture/identity-access/): How principals authenticate, how grants combine roles with scopes, and how the app enforces capability at the route and ABAC scope in the Storage Gateway.
- [Messaging](/architecture/messaging/): The internal and edge NATS subject contract, the sibling to the public API: JetStream streams and consumers, the two lanes, request-reply, KV, the live UI relay, and per-tenant subject isolation.
- [Nodes](/architecture/nodes/): How the edge runtime pulls its worklist, runs tasks and commands, manages sessions, gates reachability, and ships telemetry.
- [Scaling and deployment](/architecture/scaling/): One binary that runs a laptop demo or a Kubernetes fleet: two run modes, embedded Postgres and NATS, the CDC bridge, horizontal scale, high availability, platform configuration, and per-database multi-tenancy.
- [Storage](/architecture/storage/): How storage works: the Storage Gateway, views by default, per-database isolation, append-only partitioning and tiering, and the on-row lineage pattern.
- [Templates](/architecture/templates/): The immutable, versioned shapes that instances pin: the component_template (the device shape) and the system_template (the composition shape with its frozen BOM).
- [Time](/architecture/time/): The one primitive that manufactures events from the passage of time, so the rest of the pipeline stays purely event-driven.
- [UI](/architecture/ui/): The operator console: one renderer library in two composition modes, reads through views, and an identity-based information architecture.
- [Config, credentials, and variables](/architecture/variables/): Three kinds of operator-set value resolved by one cascade: config keyed to a signal, credentials with a lifecycle, and free variables.
- [Views](/architecture/views/): The read side: a view is a named, parameterized, scope-checked query returning a uniform ViewResult, the backend-for-frontend every read goes through.
- [Workers](/architecture/workers/): One worker machinery over several JetStream consumers, plus the backtest capability and the reconcile desired-state loop.

## Contributing

- [API first](/contributing/api-first/): The Go API is the single integration contract; the SPA, CLI, and YAML tooling are generated clients of it.
- [UI and the design system](/contributing/design-system/): The SolidJS and daisyUI console, a generated typed client over the ViewResult renderer contract.
- [Docs with everything](/contributing/docs-with-everything/): A feature is not done until the docs that teach it ship in the same PR.
- [The learning-tool restriction](/contributing/learning-tool/): Every operator surface should also teach the concept it operates on, against real or simulated data.
- [Primitive first](/contributing/primitive-first/): Build the reusable primitive, then consume it. The shared engines (expression, ViewResult, gateway, cascade, timer) the rest of the system is written against.
- [Slice workflow](/contributing/slice-workflow/): How a feature ships: one vertical slice per PR, through a fixed lifecycle of define, build test-first, document, validate, review, and a ship-review the architect approves.
- [Test-driven, always](/contributing/test-driven/): Build the failing test before the feature; each change carries the tier that proves it.