From 0737d4b6c45fbbc6bd53f3c4d22303d3f6812d10 Mon Sep 17 00:00:00 2001
From: Tiago Vier Preto <83984051+Tiago-Vier-Preto@users.noreply.github.com>
Date: Thu, 30 Apr 2026 23:00:34 +0000
Subject: [PATCH] docs: add implementation map for component layers in
 architecture documentation

---
 docs/architecture.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/docs/architecture.md b/docs/architecture.md
index 6c8337ef..2bce1693 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -39,6 +39,20 @@ human request
 - `DEPLOYMENT.md` — deployment notes.
 - `interdependent_way.md` — philosophical/source doctrine for project behavior and voice.
 
+## Where things live
+
+A short implementation map for the working component layers in this repo:
+
+- `a0 agent interface` → `client/` for the browser UI, `server/` for the Express proxy, and `python/routes/` for backend API endpoints.
+- `context / memory layer` → `python/engine/pcna.py` (PCNA engine and memory inference), with persisted state modeled in `python/models.py` and `python/storage/domain.py`.
+- `planner / policy layer` → `python/services/inference.py` for orchestration and `python/config/policy_loader.py` for policy config.
+- `provider routing layer` → `python/services/energy_registry.py` and `python/services/providers/` (including `python/services/providers/_resolver.py`).
+- `model call(s)` → `python/services/inference.py` plus provider implementations under `python/services/providers/`.
+- `tool execution layer` → `python/services/tool_executor.py` and tool handlers in `python/services/tools/`.
+- `audit / logging layer` → `python/logger.py` for log streams and audit plumbing in services such as `python/services/spawn_executor.py`.
+- `gating / access control` → `python/services/gating.py` (with explicit allowlist rules in `python/services/gating_allowlist.py`).
+- `agent runtime` → `python/main.py` for FastAPI startup, PCNA lifecycle, and route registration.
+
 ## AIMMH boundary
 
 AIMMH is expected to provide, or eventually provide, the multimodel/multimodal hub layer. The clean boundary still needs confirmation.