docker/docs/infrastructure-inventory.md

# Infrastructure Inventory Model

This repository treats infrastructure inventory as first-class documentation.

## Intent

The goal is not only deployment configuration, but also a maintainable map of:

- what hosts/VMs exist,
- how they are identified,
- what selected runtime objects are mirrored into Terraform,
- what outputs can be consumed by docs and future tooling.

## Current inventory sources

### 1) Terraform Proxmox layer

`infrastructure/terraform/proxmox/` contains imported/reconciled VM resources and local metadata for physical hosts.

This is currently the most structured host/VM inventory in the repo.

### 2) Terraform Docker layer

`infrastructure/terraform/docker/` contains selective Docker container resources used as documentation-oriented mirrors.

These resources should match existing running containers, not redefine runtime composition strategy.

### 3) Compose runtime definitions

Compose files define intended service runtime composition, networking, labels, and integration.

### 4) Architecture docs

`docs/architecture.md` provides a human-readable topology view based on repository configuration and observed runtime signals.

## Output shaping expectations

When adding Terraform outputs for documentation/tooling:

- prefer concise inventory maps/lists,
- include stable identifiers and roles,
- avoid raw giant provider objects where possible,
- include descriptions so future consumers understand intent.

## Limitations today

- No full generated inventory document pipeline is present yet.
- Some Terraform files still include generated boilerplate comments requiring ongoing cleanup.
- Ansible/NixOS operational layers are not yet implemented in a way that provides authoritative inventory in this repo.

These limitations are expected for the current adoption stage.