# High-Level Architecture (Reference Map)

This document is the canonical index for StellaOps architecture.
It is intentionally a map, not a full re-statement of every module dossier.

If you want a short walkthrough, start with `docs/40_ARCHITECTURE_OVERVIEW.md`.

## How the docs are organized

StellaOps documentation is two-level:
- High-level, canonical docs live in `docs/*.md`
- Detailed references live under `docs/**` (module dossiers, API contracts, runbooks, schemas)

Entry points:
- Full technical index: `docs/technical/README.md`
- Platform architecture index: `docs/technical/architecture/README.md`

## Guiding principles (stable)

- Deterministic outputs: stable ordering, stable identifiers, UTC ISO-8601 timestamps, canonical hashing where applicable.
- Offline-first posture: the workflow must run connected or air-gapped using Offline Kit bundles and locally verifiable signatures.
- Evidence-linked decisions: every decision should link back to concrete evidence (SBOMs, observations, reachability, attestations).
- Aggregation-not-merge for upstream evidence: preserve provenance and conflicts rather than silently collapsing them.

## Architecture views (authoritative)

These documents are the authoritative detailed views used by module dossiers and runbooks:

- Platform topology: `docs/technical/architecture/platform-topology.md`
- Infrastructure dependencies: `docs/technical/architecture/infrastructure-dependencies.md`
- Request and data flows: `docs/technical/architecture/request-flows.md`
- Data isolation model: `docs/technical/architecture/data-isolation.md`
- Security boundaries: `docs/technical/architecture/security-boundaries.md`

## Modules (authoritative dossiers)

The per-module dossiers (architecture + implementation plan + operations) are indexed here:
- `docs/technical/architecture/README.md`

Use module dossiers as the source of truth for:
- APIs and storage schemas owned by the module
- lifecycle, trust boundaries, and failure modes
- determinism rules and offline expectations

## Identity, tenancy, and headers

Tenancy and identity context are part of the platform contract:

- Gateway tenant auth and ABAC contract: `docs/api/gateway/tenant-auth.md`
- Gateway identity header policy (spoofing prevention + migration rules): `docs/modules/gateway/identity-header-policy.md`
- Authority service dossier: `docs/modules/authority/architecture.md`
- Claims and headers index: `docs/claims-index.md`

## APIs and CLI reference

Canonical entry points:
- API and CLI reference hub: `docs/09_API_CLI_REFERENCE.md`
- API conventions (headers, errors, pagination, determinism): `docs/api/overview.md`
- API contracts and samples: `docs/api/`
- CLI command guides: `docs/modules/cli/guides/commands/`

## Offline, verification, and operations

Canonical entry points:
- Offline Kit: `docs/24_OFFLINE_KIT.md`
- Security hardening: `docs/17_SECURITY_HARDENING_GUIDE.md`
- Installation guide: `docs/21_INSTALL_GUIDE.md`
- Ops and runbooks: `docs/operations/`, `docs/modules/*/operations/`

## Data and schemas

Use these as the canonical map for schemas and contracts:
- Data schemas (high-level index): `docs/11_DATA_SCHEMAS.md`
- Database specifications: `docs/db/`
- Events (schemas + samples): `docs/events/`

## Related high-level docs

- Product overview: `docs/overview.md`
- Key features: `docs/key-features.md`
- Roadmap (internal): `docs/05_ROADMAP.md`
- Glossary: `docs/14_GLOSSARY_OF_TERMS.md`