Multi-Modality Architecture Note¶
This note describes the implementation methodology for OpenETR as a single core system delivered through four modalities:
- a web application for human use
- a CLI for human use
- a CLI for agent use
- an API for agent use
The purpose of this note is not to freeze a final code structure.
Its purpose is to define the architectural direction that should guide ongoing refactoring and feature development.
Status¶
Draft.
Objective¶
OpenETR should behave as one system with multiple delivery surfaces, not as several independent applications that happen to share a repository.
That means the business logic for querying, issuing, transferring, validating, and publishing should live in the openetr module, while each delivery surface should be a thin adapter around that shared core.
The goal is equivalence of behavior across modalities, with differences only where the interaction model requires them.
The same OpenETR component should also be usable in two integration styles:
- embedded directly into another application runtime, where the host application imports and calls
openetrservices; - exposed by a running OpenETR instance, where another system calls REST APIs over HTTP.
Both styles should route through the same object/service layer.
The Four Modalities¶
1. Web Application¶
The web application exists for interactive human use.
Its responsibilities are:
- collect input through forms and navigation
- manage session state
- present results in HTML
- present warnings and confirmations as pages
It should not become the place where core OpenETR rules are reimplemented.
The preferred web application style is hypermedia-first.
OpenETR web flows should follow a HATEOAS-oriented philosophy:
- server-rendered pages and fragments represent the current application state
- forms and links express the actions that are available from that state
- the server returns the next useful representation after each action
- client-side JavaScript is kept to a minimum
- htmx may be used to improve responsiveness while preserving ordinary HTML form semantics
In this model, htmx is a progressive enhancement over server-rendered HTML, not a separate client application. A profile switch, issue action, query, transfer, or confirmation should still be understandable as a form submission or link traversal. The browser may update a page fragment in place, but the state transition remains owned by the server and the shared openetr services.
1a. Web REST/API Mode¶
The same running web application may also expose REST-style endpoints for agents, scripts, services, and external product systems.
Its responsibilities are:
- accept structured requests, including uploads, object identifiers, profile references, and control-action parameters
- return structured JSON responses
- surface guard warnings, confirmation requirements, and policy failures as machine-readable results
- preserve the same OpenETR behavior used by the human web pages
The REST/API mode should be understood as an adapter over the OpenETR component, not as a separate policy implementation.
2. CLI for Human Use¶
The human CLI exists for operators, testers, and developers who want direct terminal workflows.
Its responsibilities are:
- parse command-line options
- prompt for confirmation where needed
- render readable terminal output
- provide operator-friendly warnings and diagnostics
It should remain friendly and expressive, but should rely on shared openetr services for the actual workflow semantics.
3. CLI for Agent Use¶
The agent CLI exists for deterministic invocation by scripts, agents, orchestration systems, and automated pipelines.
Its responsibilities are:
- accept explicit machine-oriented arguments
- avoid interactive prompts unless explicitly enabled
- return stable, structured output
- expose failure conditions clearly and predictably
This does not necessarily require a completely separate executable.
The preferred approach is that the existing CLI supports an agent-oriented mode through flags such as:
--json--no-input--confirm--quiet
In the current implementation, --json is the primary boundary for agent-friendly command output. Commands using --json should return structured success, warning, confirmation-required, and error responses rather than human-only terminal text.
4. API for Agent Use¶
The API exists for programmatic use over HTTP.
Its responsibilities are:
- accept structured requests
- return structured JSON responses
- expose the same guard and validation semantics as the CLI
- provide stable request and response shapes suitable for automation
The API should not diverge semantically from the CLI and web app.
Runtime And Service Integration¶
OpenETR can be integrated in two complementary ways.
Embedded Component¶
An application runtime can import the OpenETR component and call its service layer directly.
This is useful when the host application wants OpenETR behavior inside its own process, account model, job queue, transaction logging, custody model, or workflow engine.
In this mode, the host application supplies its own surrounding concerns:
- user authentication
- authorization
- tenant or organization structure
- UI and workflow
- storage caches or indexes
- domain-specific policy selection
The OpenETR component supplies the control-layer behavior:
- digest and object-id handling
- identifier resolution
- baseline or custom guard evaluation
- event construction
- signing
- relay publication and query
- verifier result construction
Running OpenETR Service¶
An application may instead call a running OpenETR instance over REST APIs.
This is useful when the host system is not Python-based, wants a process boundary, wants centralized relay/profile management, or wants a shared OpenETR service for several applications.
In this mode, the OpenETR service acts as an HTTP adapter over the same component.
The integration choice is therefore:
host app imports openetr
or
host app calls OpenETR REST API
↓
same OpenETR component/service layer
↓
canonical identifiers
baseline or custom policy guards
signed event publish/query
structured verifier output
Core Architectural Principle¶
The governing principle is:
One domain core, multiple adapters.
In OpenETR, the openetr package should become the application core.
That core should own:
- digest and object-identifier handling
- relay interactions
- signer resolution
- profile resolution
- guard evaluation
- issue, query, transfer, and profile-publish workflows
- result construction
- validation and policy semantics
The adapters should own only the modality-specific concerns.
In compact form:
Human web UI
Agent REST/API
Human CLI
Agent CLI with --json
Embedded application runtime
↓
OpenETR component/service layer
↓
identifier resolution
baseline or custom policy guards
event construction / query
verification / structured result
What Belongs in openetr¶
The openetr module should contain reusable services or use cases for operations such as:
query_etrissue_etrpublish_profiletransfer_initiatetransfer_accepttransfer_terminateevaluate_issue_guardevaluate_transfer_guard
These services should return structured results rather than printing directly.
That allows:
- the web app to render HTML
- the human CLI to render readable text
- the agent CLI to emit JSON
- the API to return JSON
without changing the underlying behavior.
What Belongs in Adapters¶
Web Adapter¶
The web app should handle:
- routes
- session cookies
- form parsing
- Jinja templates
- browser-oriented confirmation flows
- hypermedia controls, including links, forms, and htmx-enhanced fragments
Human CLI Adapter¶
The human CLI should handle:
clickparsing- terminal prompts
- human-readable formatting
- operator-facing warnings
Agent CLI Adapter¶
The agent CLI should handle:
- machine-friendly flags
- non-interactive execution
- structured serialization
- explicit exit semantics
API Adapter¶
The API should handle:
- HTTP routing
- request validation
- authentication or session policy as needed
- JSON response serialization
Equivalent Semantics Across Modalities¶
The four modalities should not invent separate rules.
They should share:
- the same validation guards
- the same object lookup rules
- the same profile-merge rules
- the same transfer resolution logic
- the same current-controller or current-title determination
- the same warning conditions
Where interaction differs, the semantics should remain the same while the presentation changes.
For example:
- human CLI warning: interactive terminal confirmation
- web warning: confirmation page
- agent CLI warning: structured guard result and non-zero exit unless explicitly confirmed
- API warning: structured response indicating confirmation is required
The user experience changes.
The rule does not.
Structured Results as the Boundary¶
To make this architecture work, shared services should return structured result objects.
Examples include:
- query results
- publish results
- guard results
- evidence-event validation results
- profile publish results
These may initially be dictionaries.
Over time, OpenETR should consider moving toward explicit dataclasses or Pydantic models for stronger contracts and easier reuse across CLI, web, and API layers.
Root Key Separation¶
OpenETR should maintain a strict separation between the administrative root key and operational profile identities.
The root_nsec is intended to manage relay-backed configuration and profile control data, including:
- the relay-backed profiles index
- relay-backed profile configuration records
- relay-backed encrypted profile signer secrets
It is not intended to act as a public-facing user identity.
As a design rule, the root key should:
- not publish a profile
- not serve as an operational signer for normal ETR workflows
- not be treated as a user-facing identity in the web app or CLI
The purpose of this separation is to reduce attack surface and preserve cleaner key hygiene.
Operational profile signers may publish profiles and perform public or transactional actions.
The root key should remain an administrative control and recovery key only.
Web Login Semantics¶
The web app should distinguish between:
- recovery of an existing relay-backed identity
- creation of a brand-new identity
The intended semantics are:
-
Login with nsecThis is a recovery path for an existing relay-backed identity. The suppliednsecshould only be accepted when the selected bootstrap relay set can actually recover relay-backed configuration for that root identity. -
Generate New nsecThis is a creation path for a brand-new identity. The app may generate a fresh root key, establish the browser session, and begin using the selected bootstrap relay set for new relay-backed state.
This distinction avoids treating every arbitrary nsec as an already valid OpenETR root identity.
It also preserves an important operational boundary:
- manual login means “recover an existing identity”
- generated login means “bootstrap a new identity”
The browser session may retain session-local state such as the currently selected profile, but successful recovery of durable state should depend on relay-backed configuration discoverable from the root key and bootstrap relay set.
Recommended Repository Shape¶
The following direction is recommended:
openetr/The domain and application core.openetr/services/Shared workflows and service-layer logic.openetr/commands/Human CLI adapters built on top of services.app/Human-oriented FastAPI and Jinja web application.app/routers/or similar JSON API routes for agent use when the API surface grows.docs/specs/Design notes, protocol notes, and architecture notes such as this one.
This note does not require the repository to be rearranged immediately.
It defines the intended direction for future refactoring.
Methodology for New Features¶
New features should be developed in the following order whenever practical:
- Define or refine the workflow in
openetr. - Return a structured result from that workflow.
- Adapt that shared workflow to the human CLI.
- Adapt the same workflow to the web app.
- Expose the same workflow through agent-oriented CLI or API surfaces.
This order helps prevent presentation layers from becoming the de facto source of business logic.
Current Refactoring Direction¶
The repository has already begun moving in this direction.
Examples include:
- shared query logic in
openetr.services.query_etr - shared issue guard logic in
openetr.guards - shared issue publish logic in
openetr.services.issue_etr - shared profile publish logic in
openetr.services.profile_publish
This direction should continue until the major workflows are owned by openetr and the adapters become progressively thinner.
Human vs Agent Experience¶
The human and agent modalities should differ primarily in ergonomics, not in substantive behavior.
Human-oriented surfaces should prefer:
- richer explanatory text
- prompts and confirmations
- visually readable output
Agent-oriented surfaces should prefer:
- stable schemas
- deterministic output
- explicit status handling
- prompt-free execution by default
This distinction is important because it allows OpenETR to support both operator usability and automation reliability without splitting the domain logic into parallel implementations.
Design Significance¶
OpenETR is intended to operate as an open system rather than a closed platform.
That makes consistency across modalities especially important.
If the web app, CLI, API, and agent flows disagree about what an operation means, the system becomes harder to trust, harder to test, and harder to evolve.
By concentrating the logic in openetr, OpenETR can:
- reduce duplication
- reduce semantic drift
- improve testability
- support automation more safely
- preserve consistent behavior across human and machine interfaces
Working Rule¶
The working rule for future development should be:
If a rule matters to more than one modality, it belongs in
openetr.
That rule should guide both feature implementation and ongoing refactoring.