Records the AWX pluggable-architecture and Ansible task-model inspiration thread verbatim, the verified current-vs-ideal coupling analysis (webui's in-process HTTP task-action detour, direct gateway internals access, shared config.Holder), the external service-discovery research (K8s-native primary + NATS fallback behind one ServiceRegistry seam), and a Proposed-status PRD recording the target service shape and open questions before any implementation work is filed.
11 KiB
Module reference: AWX decomposition / Ansible task model vs. Archie
Status: exploratory reference, not a design decision. Nothing here is
authoritative -- docs/architecture/ stays the source of truth. This exists
so a later PRD (if one gets written) doesn't have to re-derive "what do we
already have vs. what AWX/Ansible are describing." See
2026-09-05-awx-service-decomposition-and-ansible-task-model for the
source material this is built from.
Two follow-on artifacts extend this line of exploration:
- Two Archify diagrams contrasting current vs. an ideal service-oriented
shape:
/work/artefacts/archie-core-current-state-archify.htmland/work/artefacts/archie-core-ideal-state-archify.html. The current-state diagram is grounded in verified coupling (webui's task-action path routes through its own HTTP handler in-process; directgateway.SessionStore/Router/TurnHistoryaccess; a sharedconfig.Holder) -- not the "already split" claim this document's earlier draft mistakenly made. - service-discovery-research-2026-09-05 -- externally researched
comparison of service-discovery mechanisms for the ideal-state's "install
a service, the fleet auto-aligns" requirement. Recommends Kubernetes-native
discovery as primary (Helm chart + Operator on k3s / a real cluster) with
NATS-based discovery (already a hard dependency) as the built-in fallback
for no-K8s single-host installs, both behind one
ServiceRegistryinterface.
Reading the two source ideas separately
The AWX post and the Ansible Task paste are two different asks and should
stay two different tracks:
- AWX's decomposition tree is an argument for splitting a monolith
along service boundaries (Auth, Comms, Runtime, Content, ...) with a
pluggable communication mesh between them. Archie's six-domain split
(
docs/architecture/index.md) already is that argument, applied earlier and at a different grain (domain boundaries in one Go module + NATS transport, not separate deployable services). The gap isn't "do we need boundaries," it's "are the boundaries clean and are they enforced." - Ansible's
Task/module system is a request for a content format: let users write YAML tasks against a stable action vocabulary and have Archie interpret them, the way Ansible interprets- name: ... action: module: args. Archie has the skeleton of this already (EDA playbook engine, Module action position) but it's deliberately narrow today.
AWX decomposition tree -> Archie's existing domains
| AWX node | Archie equivalent today | Location |
|---|---|---|
| Auth (RBAC / SSO / Policy-ABAC) | internal/domain/binding (task-to-identity/config binding) + internal/policy (cross-cutting, zero internal imports) + forge/channel auth (Telegram pairing, webhook HMAC) |
internal/domain/binding/, internal/policy/, internal/pairing/, internal/webhookguard/ |
| Communication / Inter-Service | NATS (ARCHIE_TASKS JetStream work queue, core-NATS RPC via _INBOX.*) |
internal/infrastructure/eventbus/nats/, internal/natsrpc/, internal/eventbus/ (contract, zero internal imports) |
| Execution (mesh) | Container pool running isolated agent worktrees over NATS, not a mesh of remote execution nodes (Ansible's Receptor equivalent doesn't exist -- Archie's "remote execution" is a Docker container, not a fleet) | internal/container/pool.go, internal/agentexec/, internal/worktree/ |
| Runtime / Scheduler | internal/domain/scheduling (ticker contract) + cron-driven work intake |
internal/domain/scheduling/, internal/infrastructure/cronstore/ |
| Content / Projects | Nearest analogue is the EDA playbook + module system (below) plus internal/skill (skill catalog) -- Archie has no "project" = git-checkout-of-automation-content concept the way AWX does |
internal/domain/eda/playbook/, internal/domain/eda/module/, internal/skill/ |
| Telemetry | internal/logging (task sink, feed, registry) + internal/events |
internal/logging/, internal/events/ |
| Inventory | No direct equivalent. Closest is forge-side repo/identity config ([[identities]], internal/forge) -- Archie targets one identity acting across a small set of forge repos, not a dynamic inventory of managed hosts |
internal/forge/, internal/config/ |
| Credentials | internal/secret (engine host, env/age/sops/vault engines) |
internal/secret/, internal/secret/enginehost/ |
| Subscription/Billing | No equivalent -- Archie is self-hosted, single-tenant; this AWX node doesn't map to anything and shouldn't | -- |
| UI split from backend | Already true: internal/webui (Go API server) serves a separately built SPA from ui/dist (Vite/React-ish, ui/src/<feature>/) over HTTP/SSE. There is no shared-process coupling to undo. |
internal/webui/, ui/src/ |
Read on "reframe to capture market": the honest gap next to AWX/AAP isn't domain boundaries -- Archie already has those, arguably cleaner (env-enforced gates, one dependency direction, contracts with zero internal imports). The gap is (a) no content/inventory layer letting non-programmers hand Archie declarative automation the way an Ansible playbook does, and (b) everything still ships as one Go binary + one container image, not independently deployable/upgradable services. (a) is the more differentiated, more buildable opportunity given a one-person team; (b) is expensive AWX-style service splitting with limited payoff at Archie's current scale and should not be pursued for its own sake.
Ansible Task model -> Archie's EDA playbook/module system
Ansible's task.py is the runtime representation of one YAML task after
ModuleArgsParser resolves the legacy free-form shape and TemplateEngine
renders Jinja2. Archie's nearest shipped analogue is the EDA playbook engine,
which is intentionally much narrower right now:
| Ansible concept | Archie's current shape | Gap / what porting the idea would mean |
|---|---|---|
Task (one step, action + args) |
playbook.Action (internal/domain/eda/playbook/playbook.go) -- but exactly one action per playbook, position must be "workflow", hard-rejected at load otherwise |
Multi-action, multi-position playbooks are the literal ask ("use existing ansible playbooks... within archie") but are explicitly blocked today on unresolved execution-time gaps: mid-run failure semantics, idempotency for non-workflow actions (see the package doc comment and docs/architecture/plugins-and-extensions.md's Event sources section). This is a known, named boundary, not an oversight. |
Module (ansible.builtin.*, arbitrary Python) |
module.Kind registry, Yaegi-interpreted .go files against a generated per-kind symbol table (internal/domain/eda/module/) -- one shipped kind: log |
Ansible modules are dynamically loaded from a huge ecosystem; Archie's Module position is closed-registry-of-named-kinds, each with its own hand-written contract package (internal/domain/eda/module/<kind>). Adding "run a shell command," "call a forge API," "send a channel message" module kinds is possible under the existing pattern but each is new work, not automatic from having the mechanism. |
when: conditional |
Action.When, compiled CEL (internal/domain/eda/expr), not Jinja2 |
Already decided: CEL over Jinja2 (open question 1 in the playbook engine PRD, resolved). Don't reopen. |
register / fact accumulation across tasks |
Not present -- DispatchInput.Event is a flat map exposed to CEL, there's no cross-action result chaining because there's only one action |
Needed before multi-action playbooks are meaningful; tracked implicitly by the same "unresolved execution-time gaps" blocker above. |
loop / until/retries/delay |
Not present | Same -- follows from allowing more than one action per playbook. |
| Field-attribute inheritance (task -> block -> play) | No block/parent chain -- a playbook is flat: one Trigger + one Action |
Ansible's play/block/role hierarchy has no Archie counterpart yet; would only matter once multi-action/roles are in scope. |
| Roles (reusable task bundles) | Nearest is internal/skill (skill catalog, frontmatter, tool defs) -- conceptually closer to Claude Skills than Ansible roles |
Not a role system; skills are agent-facing capability bundles, not declarative task sequences. |
| Channel / Forge action positions | Named and designed but explicitly not implemented (docs/architecture/plugins-and-extensions.md: "Channel and Forge action positions are designed but not yet implemented," open investigation archie-core-t2db.19) |
This is the direct next step toward "playbooks that do things," independent of the Ansible-compatibility idea. |
What porting real Ansible playbooks would actually require, in rough dependency order, if this becomes a real proposal later:
- Lift the playbook engine's hard boundary: multi-action playbooks, which needs the mid-run failure/idempotency semantics the doc comment flags as the blocker today.
- A result-passing mechanism between actions (Ansible's
register) -- currently nothing carries one action's output into the next action'swhen/args. - Loop/retry primitives per action.
- A much larger Module
Kindregistry, or a deliberate decision to accept a narrower "Archie automation language inspired by Ansible's shape" rather than "runs unmodified Ansible YAML" -- the latter also drags in Jinja2, the module_utils Python runtime, and inventory/host-targeting concepts Archie has no use for (Archie targets git repos and forge issues, not fleets of managed hosts). Recommend treating "Ansible-inspired syntax, not Ansible-compatible execution" as the working assumption if/when a PRD gets written -- it avoids importing Ansible's inventory/host model, which doesn't fit Archie's single-repo-per-task execution shape at all.
On the multi-agent / Pi-harness-as-runner idea
Out of scope for this reference doc (it's an operating-model question, not a
module-mapping one) but noted since it was raised alongside the above: this
is a migration-decisions.md-track question (agent execution as a strict
data boundary is a named invariant in ARCHITECTURE.md), not something to
back into via the EDA/module work. Flag separately if it's worth pursuing.
Bottom line
- No code changes implied by this document. It's a map, not a proposal.
- The two ideas in Sam's message decompose cleanly: AWX's service-split
argument is mostly already satisfied by Archie's domain architecture; the
Ansible-playbook-content idea is a real, currently-blocked extension of
the EDA Module/Channel/Forge action positions, gated on the same
execution-semantics work already named in
plugins-and-extensions.md. - If this becomes a real initiative, it belongs in
docs/prds/as a decisive 1-pager perAGENTS.md's scope-discipline rule -- not as an elaboration of this file.