## Architecture

### High-level map (modules and relationships)

- **Inventory**: `inventories/production/`
  - `hosts`: groups like `dev`, `desktop`, `services`, `qa`, `ansible`, `tailscale`, `local`
  - `group_vars/all/main.yml`: shared configuration (including `app_projects`)
  - `group_vars/all/vault.yml`: encrypted secrets (Ansible Vault)
  - `host_vars/*`: per-host overrides (some encrypted)

- **Playbooks**: `playbooks/`
  - `playbooks/site.yml`: dispatcher (imports other playbooks)
  - `playbooks/servers.yml`: baseline for servers (`services:qa:ansible:tailscale`)
  - `playbooks/workstations.yml`: baseline for `dev:desktop:local` + desktop apps for `desktop` group only
  - `playbooks/development.yml`: dev machines baseline (no desktop apps)
  - `playbooks/local.yml`: localhost baseline (no desktop apps)
  - `playbooks/app/*`: Proxmox app-project provisioning/configuration suite

- **Roles**: `roles/*`
  - Baseline/security: `base`, `user`, `ssh`
  - Dev tooling: `development`, `datascience`, `docker`
  - Shell: `shell` (minimal aliases-only)
  - Monitoring split:
    - `monitoring_server` (fail2ban + sysstat)
    - `monitoring_desktop` (desktop-oriented monitoring tooling)
  - Proxmox guests: `proxmox_vm`
  - App guest configuration: `base_os`, `app_setup`, `pote`

### Proxmox “app projects” flow (data model + execution)

- **Data model**: `app_projects` in `inventories/production/group_vars/all/main.yml`
  - Defines projects and per-env (`dev/qa/prod`) guest parameters (ip, branch, vmid, etc.)

- **Provision**: `playbooks/app/provision_vms.yml`
  - Loops `app_projects` → envs → calls `role: proxmox_vm` to create LXC guests
  - Adds dynamic inventory groups:
    - `app_all`
    - `app_<project>_all`
    - `app_<project>_<env>`

- **Configure**: `playbooks/app/configure_app.yml`
  - Builds a dynamic inventory from `app_projects` (so it can run standalone)
  - Applies:
    - `role: base_os` (baseline OS for app guests)
    - `role: app_setup` (deploy + systemd) or `role: pote` for the POTE project

### Boundaries

- **Inventory/vars** define desired state and credentials.
- **Playbooks** define “what path to run” (role ordering, target groups, tags).
- **Roles** implement actual host configuration (idempotent tasks, handlers).

### External dependencies

- **Ansible collections**: `collections/requirements.yml`
- **Ansible Vault**: `inventories/production/group_vars/all/vault.yml`
- **Proxmox API**: used by `community.proxmox.*` modules in provisioning

### References

- Playbook execution graphs and tags: `docs/reference/playbooks-and-tags.md`
- Legacy pointer (do not update): `docs/reference/architecture.md` → `project-docs/architecture.md`