ChristianLempa_Boilerplates/docs/architecture.md

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:

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.