Ecosystem Overview¶
The Amadla ecosystem consists of 52+ repositories organized into seven categories. All repositories live under github.com/AmadlaOrg (public) with private services under github.com/AmadlaCom.
Repository Map¶
Core Tools¶
CLI applications that form the data pipeline.
| Repo | Purpose |
|---|---|
| hery | HERY data storage — entity management with schema validation, Git versioning, SQLite caching |
| doorman | Secrets management CLI — resolves secrets from Doorman plugins on demand |
| weaver | Template generator — renders config files using HERY entities and pluggable template engines |
| dryrun | Safely tests settings with auto-revert (e.g., prevents SSH lockout). Currently Python, may move to Go |
| judge | Validates merged entity state — checks requirements, cross-entity conflicts, drift detection (with unravel) |
| lay | Package/app installer — installs applications based on merged entity output |
| raise | Infrastructure provisioner — provisions cloud resources from entities via plugin system per cloud API |
| waiter | Deployment tool — blue-green, canary, rolling strategies with platform plugins |
| unravel | Discovery tool — discovers existing system state as entities. Wraps osquery + custom plugins (stateless, on-demand) |
| conduct | Multi-server orchestrator — coordinates waiter/lay across distributed nodes |
| lighthouse | Notification/alerting tool — sends via plugins (webhook, SMS, email, REST API) |
| garbage | Trash/uninstall tool — tracks and removes what's no longer needed |
| enjoin | System state configuration — users, services, cron, network, filesystem, firewall, IDS, certs, SELinux |
| amadla | Orchestrator — reads .hery entities, builds DAG from _requires, executes tools in parallel tiers |
Libraries¶
Shared Go libraries that provide common functionality.
| Repo | Purpose |
|---|---|
| LibraryUtils | Foundation utilities: git, file, database, IPC, encryption, configuration |
| LibraryFramework | CLI framework wrapper around Cobra with decorator pattern |
| LibraryPluginFramework | Plugin system framework for loading and communicating with external plugins |
| LibraryDoormanFramework | Specialization of plugin framework for Doorman (secret source) plugins |
| LibraryJudgeFramework | Specialization of plugin framework for Judge plugins |
| LibraryEnjoinFramework | Specialization of plugin framework for Enjoin (system state) plugins |
Doorman Plugins (Secret Sources)¶
Each plugin integrates doorman with a specific secret store.
| Repo | Integrates With |
|---|---|
| doorman-vault | HashiCorp Vault / OpenBao |
| doorman-aws | AWS Secrets Manager / SSM |
| doorman-keepassxc | KeePassXC password manager |
| doorman-keycloak | Keycloak identity server |
| doorman-bitwarden | Bitwarden password manager |
| doorman-sops | Mozilla SOPS encrypted files |
| doorman-digitalocean | DigitalOcean secrets |
| doorman-linode | Linode/Akamai secrets |
| doorman-vultr | Vultr secrets |
| doorman-ovh | OVH secrets |
| doorman-rackspace | Rackspace secrets |
| doorman-chrome | Chrome browser stored passwords |
| doorman-chromium | Chromium browser stored passwords |
| doorman-firefox | Firefox browser stored passwords |
| doorman-thunderbird | Thunderbird stored credentials |
| doorman-gnomekeyring | GNOME Keyring |
Judge Plugins¶
Each plugin checks a specific aspect of system compliance.
| Repo | Validates |
|---|---|
| judge-application | Whether required applications/packages are installed |
| judge-network | Network connectivity, DNS resolution, HTTP checks |
| judge-system | System-level requirements (OS, kernel, resources) |
Weaver Plugins (Template Engines)¶
Each weaver plugin provides a template rendering engine.
| Repo | Engine |
|---|---|
| weaver-go | Go text/template |
| weaver-jinja2 | Jinja2 (Python) |
| weaver-mustache | Mustache (Go) |
| weaver-qute | Qute (Java/GraalVM native) |
| weaver-freemarker | FreeMarker (Java/GraalVM native) |
Entity Definitions¶
JSON Schema definitions that describe the structure of HERY entities.
| Repo | Defines |
|---|---|
| Entity | Base HERY schema — common _type, _extends, _meta, _body, _requires structure |
| Application | Application requirements (packages, services, configurations) |
| System | System requirements (OS, kernel, resources) |
| Infrastructure | Infrastructure requirements (servers, networks, storage) |
| ProgrammingLanguage | Programming language runtime requirements |
| Container | Container/image definitions |
| Secret | Secret references and metadata |
| Judge | Audit rule definitions |
| Entities/Tools | Tool inventory and discovery configuration |
Other Repositories¶
| Repo | Purpose |
|---|---|
| common-json-schemas | Shared JSON Schema definitions |
| hery-playground | Web app for querying HERY entities (Gin + drag-drop YAML/SQLite) |
| hery-jetbrains-editor-plugin | JetBrains IDE plugin for HERY syntax |
| hery-code-editor-plugin | VS Code extension for HERY syntax |
| template-application-golang | Go project template with standard Makefile |
| GitHub-Actions | Shared CI/CD workflow templates |
| AmadlaOrg.github.io | GitHub Pages site |
How Components Connect¶
All Go projects use replace directives in go.mod to reference sibling directories during development: