# 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.
- [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.
- [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.
- [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 (name, 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.
- [Deployment](/guides/deployment/): Standing an Omniglass platform up: the single binary, the container image, the Helm chart, and per-PR preview environments.
- [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.
- [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.
- [Build log](/architecture/build-log/): The slice-by-slice build history: one entry per merged vertical slice, oldest first.
- [Calculations](/architecture/calculations/): The rule families that run server-side over typed samples, 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 model](/architecture/data-model/): The platform entity-relationship diagram, generated from the live schema by make gen: every table, its keys, and its foreign keys, grouped by subsystem.
- [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.
- [Expressions](/architecture/expressions/): Omniglass expressions: one engine built on Expr and extended with Omniglass functions, behind every operator-authored expression leaf.
- [Glossary](/architecture/glossary/): The authoritative glossary: every official term in the architecture, defined once.
- [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.
- [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.
- [Templates](/architecture/templates/): Example configurations an operator clones. Forking is one-time and leaves no link back, which is exactly why a template can be improved in any release without migrating anyone.
- [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.
- [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, config-driven ListShell pages (with FlatList / TreeList bodies) 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.
- [Feature loops](/contributing/feature-loops/): How a body of work ships through an agent loop: a prose definition approved once, slices cascading on an integration branch, and one rollup PR the architect merges.
- [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.