# Architecture Notes

## Repository layout

- `cli/` - Python CLI application source code
  - `cli/core/` - core runtime packages
  - `cli/modules/` - technology-specific module registrations
  - `cli/__main__.py` - CLI entry point; discovers modules and registers commands
- `tests/` - automated tests
- `docs/` - developer documentation
- `scripts/` - helper scripts, including installer tooling
- `library/` - legacy in-repo template content for versions older than `0.2.0`; do not treat it as the canonical template library for modern work
- `.github/` - workflows, templates, and repository automation

## Supported kinds

The supported kinds are the registered modules in `cli/modules/`. Prefer this code-level list over legacy content in `library/`.

Current kinds:

- `ansible`
- `bash`
- `compose`
- `helm`
- `kubernetes`
- `packer`
- `python`
- `static`
- `swarm`
- `terraform`

## Module system

Modules subclass `Module` from `cli/core/module/` and register themselves with the central registry.

Minimal module example:

```python
from ...core.module import Module
from ...core.registry import registry


class ExampleModule(Module):
    name = "example"
    description = "Manage example templates"


registry.register(ExampleModule)
```

Discovery and registration flow:

1. `cli/__main__.py` imports module packages/files from `cli/modules/`.
2. Each module calls `registry.register(ModuleClass)` at import time.
3. The registry stores module classes by module name.
4. The CLI framework creates standard commands for every registered module.
5. Modules are instantiated on demand when commands run.

Benefits:

- No central manual registration for new kinds
- Modules are self-contained
- Registry validation catches invalid module classes early

## Core components

Important packages/files:

- `cli/core/module/` - base module class and standard command implementations
- `cli/core/template/` - template manifest parsing, variable normalization, rendering, and validation
- `cli/core/config/` - user configuration loading, saving, validation, and migration
- `cli/core/library.py` - template discovery across git/static libraries
- `cli/core/repo.py` - repository/library management commands
- `cli/core/registry.py` - module registry
- `cli/core/display/` - centralized CLI output rendering; see `docs/display.md`
- `cli/core/validation/` - dependency matrix and kind-specific rendered-file validators
- `cli/core/validators.py` - generic content validators such as YAML and Docker Compose validation
- `cli/core/exceptions.py` - custom exceptions; prefer these for user-facing errors

## Prompt/input flow

Interactive prompting is implemented with Rich-based input helpers under `cli/core/input/`.

Prompt support includes:

- text input
- password/secret input
- yes/no confirmation
- numbered choice selection
- defaults from template/config/CLI sources
- autogenerated secret placeholders

Use `--no-interactive` to skip prompts and use defaults, config values, CLI overrides, or empty values as appropriate.