PMA is built from nine cooperating pillars. None of them is special on its own; the value is in how they compose. This page is the bird's-eye map.
For the full 680-line treatment see docs/framework/ARCHITECTURE.md in
the asd-pma repo. This page is the navigable summary.
Read this as: a new service starts as an Install Skill session (formal
AI-agent protocol) which produces a Package. The Package is consumed by
five layers (Framework, Testing, Contract, MCP gateway, PMA UI), each of
which produces its own artefacts. Enforcement (Rule Engine + CI) guards
those artefacts. Release rolls them out.
| Pillar | Role | Lives at |
|---|---|---|
| Install Skill | Genesis. The formal protocol AI agents follow to add a new service. Phase model with regression requirements. | .claude/commands/install-service.md |
| Package | Core unit. Self-contained directory: manifest, compose, hooks, scripts. The Framework treats each Package as a black box defined by its manifest. | packages/<svc>/ |
| Framework | Generic activation layer. Reads manifests, runs lifecycle (start/stop/restart), takes backups, configures SSO. Contains NO service-specific code. | scripts/, Justfile, *.just |
| Testing | Dynamic per-service checks. Test files don't enumerate services — they iterate based on the active profile. | scripts/test/, e2e/ |
| Contract | In-memory snapshot of every command + package. Pre-commit / pre-push / CI run drift checks. | scripts/contract/ |
| MCP gateway | AI-agent operator surface. Per-service tools (Redmine/Zammad/n8n/...) with structured input + attribution. | packages/mcp-server/ |
| PMA UI | Operator dashboard (terminal-based). just dashboard + status views. |
scripts/dashboard.ts |
| Enforcement | Hooks that block PR / commit / tool-call on rule violations (.asd/ edits, hardcoded service names, ports in asd.yaml, …). |
.claude/hooks/, .claude/settings.json |
| Release | Atomic rollout. release-run four-phase orchestrator. |
scripts/release/run.sh, releases/*.sh |
DECLARATIONS ACTIVATIONS AUDIT
───────────── ────────────── ─────
manifest.yaml ─→ Framework recipes ─→ Contract
net.manifest.yaml ─→ asd routes ─→ Enforcement
tpl.env ─→ .env populated ─→ CI checks
services.yaml ─→ Profile activation ─→ skill-state
You declare in YAML in packages/<svc>/. You activate via just
recipes that read those manifests. You audit via Contract + Enforcement
which read the activated state and verify it matches the declaration.
Never the other way around. The framework does not write back to manifests;
manifests are the source of truth.
| Task | Layer | How |
|---|---|---|
| Start / stop a service | Framework | just start <svc> reads manifest, runs compose |
| Add a new service | Package | New packages/<svc>/ directory with manifest |
| Configure SSO | Framework + Package | sso.type dispatches to scripts/sso/setup-<type>.py |
| Take a backup | Framework | Generic logic, branches on backup.type |
| Run a release | Release | Four-phase orchestrator, halt-on-failure between phases |
| Validate config | Contract + Enforcement | just contract-validate |
| AI agent operates the stack | MCP gateway | Structured tool calls + attribution |
| Block a forbidden operation | Enforcement | PreToolUse hook in .claude/settings.json |
The architecture is held together by hard rules. Two of the most load-bearing:
Golden Rule 12 — Package as Unit of Functionality. ALL service-specific
logic lives in packages/<svc>/. Framework code (scripts, Justfile,
bootstrap) MUST be generic. Hardcoded service names in framework code is a
blocked pattern.
Golden Rule 13 — Release Orchestrator is Atomic. All deploys go via
just release-run TICKET — the four-phase orchestrator. Manual git ops on
prod before release-run break the BASE_SHA capture and are blocked / detected.
Full rules: CLAUDE.md in the asd-pma repo (the 17 Golden Rules).
PMA is built on top of asd (the underlying CLI). The split is strict:
PMA declares WHAT: manifests, recipes, SSO setup, bootstrap, docker compose.
ASD CLI executes HOW: Caddy routes / admin API, tunnel registry,
template expansion, schema.
PMA must never:
asd net apply.registry.json.Full split: docs/framework/EDGE-AUTH-ARCHITECTURE.md in the asd-pma repo,
or /asd/internals/architecture from the
asd side.
/pma/internals/package-system — the Package pillar in depth./pma/internals/release-orchestrator — the Release pillar./pma/internals/mcp-gateway — the MCP pillar./pma/internals/contract-system — the Contract pillar./asd/internals — the layer PMA is built on.