# Architecture

## Package layout

- `src/omni/client`: async core client + unified sync/async wrapper + singleton helpers
- `src/omni/config`: pydantic models and config loading precedence
- `src/omni/state`: SQLite-backed persistent preferences and cache storage
- `src/omni/http`: signed transport, retry policy, cache policy, stream parser
- `src/omni/auth`: service-account decode + request signing
- `src/omni/api`: service facades (`resources`, `management`, `oidc`, `auth`)
- `src/omni/generated`: generated RPC method registry and baseline models
- `src/omni/cli`: Typer/Rich CLI implementation

## Transport contracts

- Unary RPC: `POST /api/<service>/<method>` with JSON body
- Stream RPC: chunked grpc-gateway stream envelope parsing
- Signing headers for `/api/*`:
  - `Grpc-Metadata-x-sidero-timestamp`
  - `Grpc-Metadata-x-sidero-payload`
  - `Grpc-Metadata-x-sidero-signature`
- `/image/*` signing supported via HTTP message signature payload

## Model strategy

- Curated hand-authored models for DX-critical paths
- Generated baseline model fallback
- Dynamic permissive fallback for unknown payloads
