Commit c69120f4845a13d0b1cc155995859957935f9007 | the-knife

author	Kriday Dave <technocratix902@gmail.com> 2026-07-15 14:24:40+05:30
committer	GitHub <noreply@github.com> 2026-07-15 10:54:40+02:00
log	c69120f4845a13d0b1cc155995859957935f9007
tree	a6df852ec8f86946eec4f652113ffdd2770d0582
parent	7b928d54886742737851af1d6c68d70c90b4cc28
signature	Signed by PGP key B5690EEEBB952194

fix(docs): repair broken source links in architecture overview (#3991)

1 files changed, 18 insertions(+), 26 deletions(-)

docs
- architecture
  - overview.md

docs/architecture/overview.md+18-26

...	...	@@ -60,11 +60,11 @@ sequenceDiagram
60	60	Transport-->>Browser: Hydrate initial state
61	61	```
62	62
63		1. The browser boots [`WsTransport`][1] and registers typed listeners in [`wsNativeApi`][2].
64		2. The server accepts the connection in [`wsServer`][3] and brings up the runtime graph defined in [`serverLayers`][7].
65		3. [`ServerReadiness`][4] waits until the key startup barriers are complete.
66		4. Once the server is ready, [`wsServer`][3] sends `server.welcome` from the contracts in [`ws.ts`][6] through [`ServerPushBus`][5].
67		5. The browser receives that ordered push through [`WsTransport`][1], and [`wsNativeApi`][2] uses it to seed local client state.
	63	1. The browser boots `WsTransport` and registers typed listeners in `wsNativeApi`.
	64	2. The server accepts the connection in `wsServer` and brings up the runtime graph defined in `serverLayers`.
	65	3. `ServerReadiness` waits until the key startup barriers are complete.
	66	4. Once the server is ready, `wsServer` sends `server.welcome` from the contracts in `ws.ts` through `ServerPushBus`.
	67	5. The browser receives that ordered push through `WsTransport`, and `wsNativeApi` uses it to seed local client state.
68	68
69	69	### User turn flow
70	70
...	...	@@ -90,12 +90,12 @@ sequenceDiagram
90	90	Push-->>Browser: Typed push
91	91	```
92	92
93		1. A user action in the browser becomes a typed request through [`WsTransport`][1] and the browser API layer in [`nativeApi`][12].
94		2. [`wsServer`][3] decodes that request using the shared WebSocket contracts in [`ws.ts`][6] and routes it to the right service.
	93	1. A user action in the browser becomes a typed request through `WsTransport` and the browser API layer in `nativeApi`.
	94	2. `wsServer` decodes that request using the shared WebSocket contracts in `ws.ts` and routes it to the right service.
95	95	3. [`ProviderService`][8] starts or resumes a session and talks to `codex app-server` over JSON-RPC on stdio.
96	96	4. Provider-native events are pulled back into the server by [`ProviderRuntimeIngestion`][9], which converts them into orchestration events.
97	97	5. [`OrchestrationEngine`][10] persists those events, updates the read model, and exposes them as domain events.
98		6. [`wsServer`][3] pushes those updates to the browser through [`ServerPushBus`][5] on channels defined in [`orchestration.ts`][11].
	98	6. `wsServer` pushes those updates to the browser through `ServerPushBus` on channels defined in [`orchestration.ts`][11].
99	99
100	100	### Async completion flow
101	101
...	...	@@ -123,21 +123,13 @@ sequenceDiagram
123	123	2. These flows run as queue-backed workers using [`DrainableWorker`][16], which helps keep side effects ordered and test synchronization deterministic.
124	124	3. When a milestone completes, the server emits a typed receipt on [`RuntimeReceiptBus`][15], such as checkpoint completion or turn quiescence.
125	125	4. Tests and orchestration code wait on those receipts instead of polling git state, projections, or timers.
126		5. Any user-visible state changes produced by that async work still go back through [`wsServer`][3] and [`ServerPushBus`][5].
127
128		[1]: ../apps/web/src/wsTransport.ts
129		[2]: ../apps/web/src/wsNativeApi.ts
130		[3]: ../apps/server/src/wsServer.ts
131		[4]: ../apps/server/src/wsServer/readiness.ts
132		[5]: ../apps/server/src/wsServer/pushBus.ts
133		[6]: ../packages/contracts/src/ws.ts
134		[7]: ../apps/server/src/serverLayers.ts
135		[8]: ../apps/server/src/provider/Layers/ProviderService.ts
136		[9]: ../apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts
137		[10]: ../apps/server/src/orchestration/Layers/OrchestrationEngine.ts
138		[11]: ../packages/contracts/src/orchestration.ts
139		[12]: ../apps/web/src/nativeApi.ts
140		[13]: ../apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
141		[14]: ../apps/server/src/orchestration/Layers/CheckpointReactor.ts
142		[15]: ../apps/server/src/orchestration/Layers/RuntimeReceiptBus.ts
143		[16]: ../packages/shared/src/DrainableWorker.ts
	126	5. Any user-visible state changes produced by that async work still go back through `wsServer` and `ServerPushBus`.
	127
	128	[8]: ../../apps/server/src/provider/Layers/ProviderService.ts
	129	[9]: ../../apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts
	130	[10]: ../../apps/server/src/orchestration/Layers/OrchestrationEngine.ts
	131	[11]: ../../packages/contracts/src/orchestration.ts
	132	[13]: ../../apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
	133	[14]: ../../apps/server/src/orchestration/Layers/CheckpointReactor.ts
	134	[15]: ../../apps/server/src/orchestration/Layers/RuntimeReceiptBus.ts
	135	[16]: ../../packages/shared/src/DrainableWorker.ts