# 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

- [Admin guide](/guides/admin/): Administering an Omniglass platform: the people who can sign in, the access they carry, the audit trail, and the config and credentials that resolve down the estate.
- [Roles, groups, and grants](/guides/admin/access/): Giving a user access: the built-in roles, user groups as shared grant anchors, and the grant builder that assigns a role at a scope.
- [The audit trail](/guides/admin/audit/): The read-only record of every privileged action and every sign-in, including who acted behind an impersonation.
- [Capabilities](/guides/admin/capabilities/): The Capabilities catalog: the vocabulary of what a component can do, the product default and the component's own additions and suppressions over it, and how a system role requires them.
- [Drivers](/guides/admin/drivers/): The Drivers catalog: the implementations that get, emit, and set a product's signals (id, display name, version), seed-owned official rows read-only, admin-gated custom ones.
- [Files](/guides/admin/files/): The Files directory under Values: upload, find, download, and delete the opaque bytes kept with an estate, deduplicated and content-addressed, with a sensitive tier for confidential ones.
- [Products](/guides/admin/products/): The Products catalog: a concrete SKU binding a vendor, a driver, a kind, and the capabilities it provides; a component points at the product it is; seed-owned official rows read-only, admin-gated custom ones.
- [Properties](/guides/admin/properties/): The Properties catalog and the values behind it: the canonical typed names, the contract a product, standard, or location type declares, and the value a component, system, or location sets.
- [Secrets](/guides/admin/secrets/): Encrypted-at-rest credentials owned at one scope and resolved down the cascade: the directory, create, reveal, and rotate.
- [Standards](/guides/admin/standards/): The Standards catalog: the blueprint a system conforms to, its variants, the properties it declares, and the roles a conforming system must staff; shipped standards are yours to edit, not read-only seed content.
- [Tags](/guides/admin/tags/): The Tags directory: mint the governed key vocabulary, set what each key applies to and whether it cascades, and edit or delete a key.
- [Types](/guides/admin/types/): The Types catalog: a segmented tab per kind across the location and secret type registries, each tab its own directory, with CRUD and a property contract on the writable kind.
- [Manage users](/guides/admin/users/): The principal directory: create a human, edit and rename, the disable-archive-purge lifecycle, admin password reset, and profile pictures.
- [Variables](/guides/admin/variables/): Plaintext typed free values owned at one scope and resolved down the cascade: the directory, create, and edit.
- [Vendors](/guides/admin/vendors/): The Vendors catalog: the organizations behind products (id, display name, kind of manufacturer/integrator/developer, icon, support phone, website), seed-owned official rows read-only, admin-gated custom ones.
- [The CLI](/guides/cli/): The omniglass CLI: a generated client of the HTTP API, with a stable seam for hand-written commands.
- [Container image](/guides/container-image/): The published Omniglass container image: what it contains, where it ships, and how to run it.
- [Deployment](/guides/deployment/): Standing an Omniglass platform up: the single binary, the container image, the Helm chart, and per-PR preview environments.
- [Deploying with Helm](/guides/helm/): The Omniglass Helm chart: install, values, and the bundled-Postgres preview mode versus BYO-Postgres production.
- [Install](/guides/install/): Download a prebuilt Omniglass binary for your OS and architecture, or run the container image.
- [Operator guide](/guides/operator/): Operating an Omniglass estate day to day: signing in, finding things, working with entities, and the scope that decides what you see.
- [Nodes and reachability](/guides/operator/collection/): Enrolling a collection node, adding a protocol-named interface to a component, and reading the per-interface reachability and the log events a node reports.
- [Work with an entity](/guides/operator/entities/): Opening an entity's blade, drilling into its children, and creating, editing, or deleting through the footer action bar.
- [Find things in your estate](/guides/operator/inventory/): The inventory pages, the chip filter, and the tree, list, and column controls for locating a location, system, or component.
- [Sign in and your profile](/guides/operator/sign-in/): Getting into the console with a password or a bearer token, and managing your own display name, picture, and password.
- [PR preview environments](/guides/pr-previews/): How a pull request gets a live, isolated preview of the console, and how it is torn down.
- [CLI reference](/reference/cli/): Every omniglass CLI command, generated from the live command tree so it never drifts from the binary.

## 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.
- [Decision log](/architecture/decisions/): The dated history of architectural calls: reversals, settled open questions, and where the build currently diverges from the present-tense design.
- [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 verdict rolled up from alarms through capabilities and roles, recorded as a transition so the edges are accurate, plus the KPIs every estate should track 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.
- [Roadmap](/architecture/roadmap/): The directional layer: the epics and the architectural arc ahead, and how forward-looking work converges into the spine as it ships.
- [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.
- [Settings](/architecture/settings/): A cascade-resolved, lockable settings engine: ordered layers merged into an effective document, with per-key provenance, top-down locks, and a platform-versus-profile domain split.
- [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.
- [Tags](/architecture/tags/): A governed key vocabulary and per-entity value bindings that resolve union-on-key, override-on-value down the cascade.
- [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, secrets, and variables](/architecture/variables/): Three kinds of operator-set value resolved by one cascade: config keyed to a signal, secrets encrypted at rest, 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 config-driven ListView shell over a generated typed client.
- [Docs with everything](/contributing/docs-with-everything/): A feature is not done until the docs that teach it ship in the same PR.
- [Labels](/contributing/labels/): The fixed label taxonomy: what is a native Issue Type, what is a Project field, and what stays a label.
- [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.
- [Release and CI](/contributing/release-ci/): The CI gates on every PR and the manual semantic-release versioning cut from main.
- [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.