Architecture Charter

Architecture Charter

Principles that govern every design decision. Implementation details belong in module-level documentation.

Identity

dsh-edge is an adapter layer, not a fork. It runs published upstream packages on Cloudflare Workers. Upstream owns all business logic. Edge owns only the transport and storage that make those packages work in a serverless environment.

The application logic stays identical; only the plumbing changes.

Principles

Maximize upstream leverage

If upstream provides a plugin, install it. If upstream provides an extension point, use it. If upstream provides an abstract class, implement it. Never reimplement what upstream already ships. If you're writing business logic in Edge code, you're probably doing it wrong.

Bridge, don't rebuild

Upstream was designed for a single process — services call each other in memory, clients read state directly. Edge's only job is to add network transport where upstream assumes locality. Every Edge-owned component falls into exactly one of three categories:

• Direct reuse — upstream plugin installed as-is, zero Edge code.
• Minimal replacement — platform-specific implementation of an upstream seam (abstract class or capability interface).
• Transport bridge — forwarding in-process signals over the network, containing zero business logic.

Two buses, one wire

Upstream runs two cordis Contexts in one process — server-side and client-side — connected by in-process plugins. Edge separates them into two physical runtimes connected by WebSocket and HTTP. The architecture is unchanged; only the communication medium is different.

Patch discipline

A patch is a last resort. Every retained patch needs a version-bound filename, a failing-without-it test, a rationale, and a documented removal condition. Composition and extension points are always preferred.

Decision Priority

1. Install the upstream plugin. Check its inject requirements — if all dependencies are satisfiable, install it directly. This is the default and requires no justification.
2. Implement an upstream seam. When upstream provides an abstract class or capability seam that needs a platform-specific backend, write the smallest conforming implementation.
3. Add a transport bridge. When upstream assumes in-process communication, capture the signal through an upstream extension point and forward it over the network. The bridge should contain zero business logic.
4. Patch upstream. When none of the above can work due to a hard platform incompatibility. Document the removal condition — every patch should be deletable when upstream evolves.

Ownership Boundary

Edge owns: Platform entry points. Durable Object lifecycle. Network transport between server and browser. Storage backends. File system delegation. Owner authentication. HTTP route dispatch.

Upstream owns: Agent behavior. Tool definitions. System prompts. Model orchestration. Session event format. Goal tracking logic. Compaction strategy. All user-facing interaction design. All client-side UI plugins.

When a new upstream capability arrives, the first question is not "how do we implement this" but "what prevents this from working as-is?" The answer is almost always one of: missing storage backend, missing network transport, or a Node.js API unavailable in Workers. Fix that specific gap — nothing more.