13 KiB
Web Client architecture
English | 中文
The Web Client is a browser-side Cordis application assembled from independently loaded plugins. Its architecture has four reusable foundations: Client Modules loads the plugin graph, the API Gateway provides typed Host communication, Slots composes React UI, and Conversation turns a Session history window into target-owned views. This page connects those systems and defines where Client models and feature packages belong.
Layers and ownership
| Layer | Main owners | Responsibility |
|---|---|---|
| Host application | business services and packages/api/*-controller Host entries |
Own authoritative state, persistence, mutation ordering, access policy, and stream production. |
| Transport and API assembly | client/connection, api/gateway, api/remotes |
Establish a Client generation, expose generated ctx.remote methods and streams, forward selected Cordis events, and carry cancellation and results. |
| Client models | api/session-controller/client, api/workspace-controller/client |
Maintain React-free mirrors of Host state, resolve stream/unary races, own object identities and subscriptions, and expose narrow command services. |
| UI adapters | client/ui-session, client/ui-workspace |
Convert model observables into root or Session-scoped standard Slot sources without taking ownership of business state. |
| Conversation data | client/ui-conversation, target packages such as ui-chat and ui-trajectory |
Assemble standard events and compact historical Assistant runs into independent target snapshots and own the shared conversation shell and input flow. |
| Composition and rendering | client/ui-slots, client/ui-renderer, client/ui-layout, feature UI packages |
Declare extension locations, derive component props, bind observables to React hooks, and mount the final tree. |
The dependency direction is Host state → Remote transport → Client model → UI adapter → Conversation or presentation → Slots → React. User actions travel back through callbacks that close over an injected Client service or generated Remote namespace. A presentation component never receives Cordis ctx, a transport object, or another feature plugin's implementation.
Browser boot
The Host writes the composed WebBootGraph to window.__DSH_BOOT__ and installs the browser module-loader facade before parser-preloaded scripts execute. The module system is a lazy CommonJS table: loading a bundle registers its factory, while materializing an entry runs the factory with synchronous require over platform modules and declared dynamic dependencies.
The Web boot kernel creates the module system, prefetches immediately entries, mounts the vendored Cordis Loader, and creates every graph entry. Cordis service injection determines activation; module graph order determines only whether synchronous imports can be materialized. After the complete roster reaches a settled state, ui-renderer hydrates the framework-free boot DOM and calls the sole context-level renderSlot('root') operation. Client Modules owns the graph, bundle route, cache revision, and loader details.