OpenSRE architecture
How the OpenSRE codebase is structured: the seven first-party packages, what each is responsible for, and which may depend on which. These dependency rules are CI-enforced (make check-imports), so they are real invariants rather than
aspirations.
The layer stack
The packages sit in four tiers. Higher tiers may import lower tiers; a lower tier may never import a higher one. Packages on the same tier are peers — the last column says whether peers may import each other.
The shortcut: dependencies point downward only. A surface can reach all the
way down;
config can reach nothing. The single deliberate exception is
core ⟷ infrastructure, a mutually-dependent pair by design (see below).
The arrows show edges between adjacent tiers to keep the diagram readable.
The actual rule is broader: a tier may import any tier below it, not only
the one directly beneath — so a surface may import config directly, and a
tool may import infrastructure. Refer to the “May import” column above for the
complete set of allowed edges.
The layers in detail
Tier 1 — surfaces and gateway
The entry points a human or an external system talks to. Nothing first-party
may import from here, so a surface can be added or removed without touching the
layers below it.
surfaces/— one folder per UI/client:surfaces/cli(the statelessopensre <command>runner),surfaces/interactive_shell(the stateful REPL), andsurfaces/sharedfor code two or more surfaces use. A surface owns its own I/O, prompts, and presentation, and composes lower layers to do the actual work. The two terminal surfaces are peers and do not import each other (tests/shared/test_surface_border.pypins both directions at zero); what both need lives insurfaces/shared—terminal/(output tracking, tables, prompts, banner, health and feedback rendering),llm_setup/,error_handling/— or a lower layer.surfaces/entrypoint.pyis theopensreconsole script: it hands the CLI aCliHost(how to open the shell, how to run the gateway attached), so composition happens in one place above both. Slack is not a surface: its inbound transport lives ingateway/transports/slack, outbound delivery inintegrations/slack.gateway/— the standalone messaging gateway for inbound chat platforms (gateway/transports/{telegram,slack,discord,buzz}), plus the FastAPIgateway/web/surface (health, alert intake) and the shared per-turn machinery ingateway/core/{session,storage,middleware}(middleware/holds the inbound-decision, identity, and approval steps every transport composes). A peer ofsurfaces, not a child.
Process boot and capability wiring
Hosts cannot import each other, andtools / integrations are peers that
must not import each other — yet a process needs both capability packages
registered before its first turn. Each capability package owns its own
registration: integrations/harness_adapters.py, tools/harness_adapters.py,
integrations/scheduled_delivery.py, and the scheduler runners in
integrations/scheduled_agent_bootstrap.py. Only a host may import both, so
each host names those registrars once, as CAPABILITY_REGISTRARS in
surfaces/shared/process_boot.py and gateway/core/process/boot.py.
tests/infrastructure/process/test_capability_registrars.py fails if the two
differ or a third copy appears — do not add registration anywhere else.
Every entrypoint boots through its host’s configure_process(<profile>),
which runs boot_process from infrastructure/process/boot.py: a profile
(CLI, gateway, web, scheduler worker, scheduled command, embedded) selects
which boot steps run, and the step order is fixed there — profiles cannot
invent a different sequence. Embedded Python callers use
surfaces.embedded.start_embedded_session.
Host-owned concerns stay out of process boot: CLI/gateway logging, Rich
product ports, CLI’s update-tolerant Sentry init.
Tier 2 — tools and integrations
The capability layer — “do a thing against the outside world” — split by
responsibility:
integrations/— the boundary for user config and external clients: per-vendor config normalization, verification (verifier.py), API clients (client.py), the store/catalog that resolves credentials, and integration-local helpers. One folder per vendor (integrations/datadog,integrations/grafana,integrations/github, …) plus cross-cutting pieces likeintegrations/llm_cli.tools/— the vendor-neutral agent-callable boundary: the registry, interactive-shell tool framework,tools/system/for capabilities with no vendor in their domain purpose, and the narrowtools/cross_vendor/bucket for capabilities that genuinely span vendors. A tool tied to one vendor belongs underintegrations/<vendor>/tools/, beside that vendor’s client and configuration. See tool-placement-policy.md.
tools and integrations are peers, so neither may import the other in new
code. The exceptions in .importlinter are tracked migration debt, not
precedent: they cover the existing cross-vendor tools and a few incidental
credential/client edges. Single-vendor tools avoid the peer edge entirely by
living inside their owning integrations/<vendor>/ package. Process boot
registers both tool families into the core.tool registry.
Do not reintroduce top-level vendors/ or services/ packages.
Tier 3 — core and infrastructure
The shared runtime and cross-cutting services the capability layer is built on.
core/— the provider-agnostic agent runtime: the think → call tools → observe loop (core.agent.Agent), agent state (core/state) and context-budget enforcement (core/context_budget.py), tool contracts, schema, registry ports, execution, and error reporting (core/tool), tool authoring helpers (core/tool_framework), shared LLM clients (core/llm), agent-harness session handling (core/agent_harness), and pure domain rules (core/domain).infrastructure/— cross-cutting services with no agent logic of their own: guardrails, masking, sandbox, analytics, auth, notifications, observability, scheduler, deployment, and the shared turn host (turn_host) — the singleTurnRunnerthe interactive shell and every gateway transport run turns through, so the two entry paths cannot drift. Deploy-time assets live underinfrastructure/deployment/(EC2/packaging Python tooling plus thecloudflare_install_proxyedge worker); these are not imported by the app.
core reaches infrastructure
for guardrails, masking, observability, and evidence/log compaction, while
infrastructure reaches back into core for the shared state and session types
(core.state, core.agent_harness.session). Splitting them into
separate tiers would forbid that edge, so they share a tier as siblings.
Tier 4 — config
The floor: shared constants, prompts, and UI theme. Everything above may
read from config, but config
imports no other first-party package — keeping it a leaf means constants can be
imported anywhere without dragging runtime along.
Cross-layer flows
Two worked examples showing runtime control flow and how results return to the host. Dashed registry-dispatch arrows are callbacks installed at process boot; they do not represent static imports fromcore into capability packages.
A chat turn from the interactive shell
- The shell (or a gateway transport) hands the message to the shared agent
harness in
core/agent_harness— the surface never runs agent logic itself. - The harness runs the ReAct agent (
core/agent): think → call tools → observe, under the context budget. - Process boot has already registered vendor-neutral tools from
toolsand vendor-owned tools fromintegrations/<vendor>/toolsbehind the registry’scorecontract. Dispatch through that registry is a runtime callback, not a forbiddencoreimport of either capability package. - Vendor-owned tools use the client and resolved credentials in their own
integration package;
infrastructuresupplies guardrails, masking, and observability around calls. - The answer flows back up to the surface, which owns how it is presented or delivered.
An inbound gateway message
gateway receives a message, resolves session state from its own storage, then
uses the same boot-registered tier-3 capabilities as a surface — without ever
importing surfaces, since the two are independent tier-1 peers.
Related docs
AGENTS.md— repo map and per-area “files to touch” guides.