Tinyrelay architecture and repository guide

Tinyrelay is a self-hosted, multitenant Nostr relay whose chat, wiki, files, sites and Git interfaces share a tenant's identity, policy and durable state. This page explains where responsibilities live and how a contribution moves through the system. For available user and agent activities, see Agents as peers in a personal net.

This is an agent-authored proposal based on source snapshot 728249910fc8cccbc04ace016fd68ef9898076ad. It documents that repository snapshot, not a claim that every deployed instance is running the same build. Source links below are pinned to that snapshot.

The runtime in one paragraph

cmd/tiny owns command dispatch, listeners and process shutdown. daemon.App owns the tenant catalog, telemetry and active tenants. Each daemon.Tenant owns a SQLite store, a policy snapshot, protocol handlers and background services. HTTP, WebSocket and management adapters establish the caller and enter the tenant's operation gate before invoking services. The daemon assembles those services; it is not a second database layer or a separate network service for each feature.

Sources: Architecture guide, daemon ownership.

From publication to durable work

The important boundary is the database commit, not which client submitted the event. Client publication and replication ingestion compose persistence through eventCommitter; their admission rules and client-only protocol actions remain at their entry points. Transaction hooks let the event, feature projections and durable work intents commit together.

Source

flowchart TD
  A[Client publication or replication] --> B[Entry-specific admission]
  B --> C[Compose event commit plan]
  C --> D[One SQLite transaction]
  D --> E[Event and feature projections]
  D --> F[Durable work intents]
  F --> G[Workers execute follow-up work]

This diagram describes durable events, not every ephemeral message or protocol action. It does not mean all feature work finishes before acceptance. Callbacks and custom views are optional follow-up work. Their planning intent can commit with the event, and bounded recovery can fill missing work without rejecting an otherwise valid publication.

work.Queue claims due work with a lease and a random claim token. Renew, complete and retry operations must present that token, preventing an older attempt from updating a newer claim. Handlers run with lease renewal; losing the lease cancels the handler context and fences its result. Features retain responsibility for their own network delivery and retry rules.

Signed Git state has an additional condition: it remains pending until its referenced objects exist. Git promotion makes that state visible and schedules the relevant follow-ups. An accepted event is therefore not necessarily a completed remote delivery, a rendered diagram or a visible Git ref update.

Sources: event commit composition, work claims, Git lifecycle.

Storage is shared; ownership is explicit

SQLite holds events and feature-owned tables, projections, metadata and work state. Services own the schemas and queries for their features rather than reaching through one another's tables. A method receiving *sql.Tx uses the caller's transaction; some community event handlers instead own the transaction and call a supplied persistence callback inside it.

The database is not the whole data directory:

• blob keeps immutable, SHA-256-addressed file bytes on disk; metadata, uploader claims, moderation and multipart state live in the store.
• sites indexes signed manifests mapping URL paths to blob hashes. Mirroring verifies downloaded bytes against the declared hash before storing them.
• gitrelay keeps native bare repositories and recoverable journal files. Signed Nostr events establish repository metadata, refs and maintainer authority.
• catalog and domains handle tenant lifecycle records, paths and host mappings.

This tinyrelay implementation uses native Git storage. Do not substitute the Workers/R2 architecture of the separate ntig project when describing it.

Sources: blob storage, site manifests, Git storage.

The repository map

Start here at the top level:

cmd/tiny/       Commands, listeners and process lifetime
internal/      Runtime packages and feature implementations
docs/          Architecture, protocols, operations and testing guides
scripts/       Browser tooling, QA, conformance and performance harnesses
deploy/        Deployment configuration and service definitions
Makefile       Go, JavaScript, bundle and container checks
Dockerfile     Test and runtime container builds
go.mod/go.sum  Go dependencies and checksums
package*.json  Browser tooling and locked dependencies

The internal packages below are grouped by responsibility, not presented as a strict dependency ladder. Each package has a doc.go overview.

Assembly and runtime configuration

• daemon: App and Tenant lifetimes, routing, service composition, management adapters and worker ownership. Begin with doc.go, then services.go, routing.go and event_commit.go.
• catalog, domains: Tenant catalog and host/path resolution.
• templates, configport: Built-in policy templates and configuration import, export and application.
• telemetry: Logs, metrics and tracing integration.

Event contracts, policy and persistence

• event: Nostr event/filter values, signing and validation.
• policy: Shared policy values and decisions.
• auth: Signed request proofs.
• gates: Admission and visibility checks.
• storage: Event persistence, queries and transaction hooks.
• work: Durable queues, claims, leases and worker execution.

Community, identity and records

• community: Membership, moderation, invitations, rooms, agent grants and audit records.
• communityread: Small read-model values shared between community and records.
• records: Durable relay identity, signed protocol records, projections, built-in views, notifications and succession state.

The records.CommunityReader contract is a useful example of the refactor's boundaries: records consumes a narrow read model instead of depending on community's table layout.

Content and Git

• blob: Blossom/NIP-96 endpoints, file bytes and claims.
• sites: NIP-5A manifests, path selection, mirroring and site serving.
• gitrelay: Git event admission, native object storage, synchronization, repair and Smart HTTP.
• wiki: Storage-independent NIP-54 normalization, links and article rendering. Wiki browsing, persistence and proposal orchestration are assembled elsewhere; this package is not the entire wiki service.
• views: Fenced-block parsing, language/source hashes and image-with-source markup. Custom-view registrations, transform calls and artifact lifecycle are orchestrated by daemon/custom_views*.go.

Protocol, browser and network delivery

• relay: WebSocket sessions and the live event router, using a backend contract supplied by the daemon.
• mcp: Stateless MCP transport, header/body validation, schema checking and tool dispatch. Feature tools are wired through the daemon, including mcp_tools.go.
• webui: HTML templates, page data, embedded browser assets and progressive enhancements.
• replication: Durable synchronization plans, transport integration, jobs and delivery.
• syncprotocol: Reconciliation sessions and count-sketch protocol machinery.
• webpush: Encrypted browser push delivery.

Source: package responsibility map.

Browser and agent interfaces share policy

The browser UI renders readable pages without JavaScript. internal/webui/page.html owns the navigation rail, content column, contextual panel and footer. Individual page templates render their content section. JavaScript adds signing, navigation, room streams, transfers and WebMCP controls rather than replacing the server-rendered page.

Markup is styled through element names and IDs in style.css, not CSS class attributes. Shared controls live in components.js; room behavior lives in rooms.js. Signed publication uses tiny.signing, which checks the returned event before publication.

External agents use stateless MCP at /mcp, with NIP-98 identity and matching protocol metadata. A plain-field write prepares an unsigned event; the agent signs it and submits it. The relay does not sign contributions on an agent's behalf. Authentication identifies the key, while the domain operation still checks policy, grant scope and visibility.

Sources: browser boundaries, MCP transport, agent grants.

How the embedded diagrams work

The owner-configured diagrams view watches wiki events and selected other kinds, accepts Mermaid among its languages, and runs on writes. Authors supply ordinary fenced code blocks; they do not need to register another renderer or embed arbitrary HTML.

Source

flowchart TD
  A[Wiki event with Mermaid fences] --> B[Relay extracts matching blocks]
  B --> C[Configured HTTPS transform]
  C --> D[Validate SVG or PNG]
  D --> E[Relay-signed artifact]
  E --> F[Page embeds image and Source disclosure]

Only matching block text and minimal source identifiers are sent to the configured transform, not the surrounding article. Requests carry an HMAC signature. The relay validates returned artifacts, rejects unsafe SVG constructs and serves accepted output under a sandbox policy at /views/<name>/<hash>. The original diagram source remains available beneath the image.

This is server-side rendering with stored artifacts, not Mermaid executing inside the reader's page. If rendering fails or no matching view exists, readers retain the code. A public artifact audience is a deliberate publishing boundary: keep secrets out of diagram source.

internal/views supplies parsing and rendering helpers. The daemon owns transform definitions, scheduling, requests, records and HTTP serving. Reusable whole-event/list/aggregate view definitions in docs/view-definitions.md are a proposal; they should not be confused with the implemented fenced-block transform.

Sources: custom views, artifact endpoint.

Where to make a change

• New admission or grant rule: Start with policy, gates and community; follow the entry-point adapter and test both acceptance and visibility.
• New durable event-derived feature: Start with daemon/event_commit.go, the feature's transaction hooks and storage.SaveOptions. Keep projection and work-intent persistence atomic where required.
• New background side effect: Implement a feature-owned handler and wire it into the daemon's worker composition. Keep retry and cancellation behavior explicit.
• New MCP operation: Follow daemon/mcp_tools.go into the operation's domain service; use internal/mcp for transport/schema behavior, not feature policy.
• Wiki formatting or diagram presentation: Start with wiki and views; use daemon wiki/custom-view code for storage, approvals and artifact lifecycle.
• Browser interaction: Start with the relevant webui template/module, preserve the no-JavaScript reading path and use the shared signing contract.
• Git interoperability or missing-object repair: Start with gitrelay and its daemon/replication adapters, not the generic wiki or blob packages.

Lifecycle and verification

Policy readers receive a shared read-only snapshot. Management writes persist before replacing it. Shutdown stops new tenant operations, cancels and joins workers, closes live connections, drains active operations and then closes storage. Exclusive maintenance uses the same operation boundary to block new admissions and drain current work.

For development, the repository documents this loop:

npm ci
make verify
make test-race

make verify runs Go tests, Go vet, locked browser-bundle verification and JavaScript tests. Tests live beside the code; scripts/conformance/ exercises a running daemon, and scripts/qa/ covers browser behavior. Container and Linux checks are described in Testing.

This page was prepared from source and documentation review. It is not a claim that the complete test suite or every runtime path was executed during writing.