Files

root 632b730fff chore: migrate GRACE-Poly anchors to hierarchical dotted naming

Systematic rename of all semantic anchors (#region, [DEF], @RELATION)
across 1400+ files — backend Python, frontend Svelte/TS, specs, docs:
- Flat anchors become Namespace.Module.Entity
- @RELATION references updated to match new anchor paths
- Zero business logic changes

2026-07-22 11:48:15 +03:00

1.9 KiB

Raw Blame History

[DEF:Doc.Adr.ADR0015:ADR]

@STATUS ACCEPTED

@PURPOSE Define package and Docker boundaries for the standalone conversational agent and its shared utilities.

@RELATION SUPERSEDES -> [Doc.Adr.ADR0014:ADR]

@RELATION BINDS_TO -> [agent/pyproject.toml]

@RELATION BINDS_TO -> [shared/pyproject.toml]

@RELATION BINDS_TO -> [docker/Dockerfile.agent]

@RATIONALE The agent has a different Python runtime and dependency surface from the FastAPI backend. Keeping it under `backend/src` made Docker copy rules fragile and coupled agent imports to backend internals.

@REJECTED Copying selected `backend/src/core` modules into the agent image — rejected because package extraction provides explicit dependencies and makes the container build reproducible.

@REJECTED Copying the complete backend into the agent image — rejected because it expands the dependency and security surface without a runtime need.

Decision

The conversational agent and common lightweight utilities are independent Python packages:

agent/                       # ss-tools-agent, Python >=3.11
shared/                      # ss-tools-shared, Python >=3.11
backend/                     # FastAPI application, its own runtime boundary
docker/Dockerfile.agent      # installs shared first, then agent

docker/Dockerfile.agent copies and installs shared/ and agent/ as editable packages. It must not copy backend/src to satisfy agent imports. Shared code is limited to utilities that have no dependency on backend API, models, database, or service layers. Dependencies required only by the agent belong in agent/.

Consequences

Agent dependencies can evolve independently from the backend image.
Imports between agent and backend require an explicit API or shared-package contract; direct imports across those boundaries are forbidden.
A change to the agent Docker build must be verified with docker build using the repository root as build context.

[/DEF:Doc.Adr.ADR0015:ADR]

1.9 KiB Raw Blame History