/home/mrjunejune/zenbu: hg-web/README.md annotate

annotate hg-web/README.md @ 218:921ca3086879 hg-web

[hg-web] Add architecture wiki tree

author	MrJuneJune <me@mrjunejune.com>
date	Sun, 02 Aug 2026 08:34:28 -0700
parents	b818a4561a3c
children	ce7f4400c2de

rev	line source
192 b818a4561a3c Added AI genreated README.md. Needed to be read. MrJuneJune <me@mrjunejune.com> parents: diff changeset	1 # hg-web
b818a4561a3c Added AI genreated README.md. Needed to be read. MrJuneJune <me@mrjunejune.com> parents: diff changeset	2
218 921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	3 A custom Mercurial forge and repository browser. The application keeps the
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	4 networking and HTTP stack in C with Seobeo, while the hand-drawn web interface
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	5 is implemented in React and TypeScript.
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	6
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	7 ## Wiki tree
192 b818a4561a3c Added AI genreated README.md. Needed to be read. MrJuneJune <me@mrjunejune.com> parents: diff changeset	8
218 921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	9 ```text
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	10 hg-web
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	11 ├── Runtime
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	12 │ ├── hg_web_server :6970
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	13 │ │ ├── React application and static assets
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	14 │ │ ├── repository browsing API
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	15 │ │ ├── commit graph API
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	16 │ │ └── Mercurial wire-protocol proxy
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	17 │ └── hg serve :4444
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	18 │ ├── repository files and graph data
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	19 │ └── Mercurial pull/push protocol
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	20 ├── Backend
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	21 │ ├── main.c
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	22 │ └── ../seobeo
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	23 │ ├── s_network.c
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	24 │ ├── s_web.c
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	25 │ ├── s_http_client.c
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	26 │ └── s_ssl.c
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	27 ├── Frontend
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	28 │ └── src
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	29 │ ├── main.tsx
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	30 │ ├── components
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	31 │ │ ├── app.tsx
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	32 │ │ ├── directory-browser.tsx
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	33 │ │ ├── graph.tsx
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	34 │ │ ├── header.tsx
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	35 │ │ ├── footer.tsx
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	36 │ │ ├── theme.tsx
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	37 │ │ └── repo-browser.tsx
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	38 │ ├── index.html
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	39 │ ├── index.css
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	40 │ ├── base.css
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	41 │ └── custom pencil, panda, icon, and background assets
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	42 ├── Build
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	43 │ ├── BUILD
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	44 │ ├── ../gui_ze/gui_ze.bzl
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	45 │ ├── ../markdown_converter
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	46 │ └── ../third_party/highlight
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	47 └── Operations
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	48 └── deploy.sh
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	49 ```
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	50
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	51 `repo-browser.tsx` is an older standalone browser implementation. The active
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	52 entry point is `main.tsx`, which renders `app.tsx`; `app.tsx` embeds
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	53 `directory-browser.tsx`.
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	54
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	55 ## Runtime topology
192 b818a4561a3c Added AI genreated README.md. Needed to be read. MrJuneJune <me@mrjunejune.com> parents: diff changeset	56
218 921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	57 ```text
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	58 Browser
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	59 \|
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	60 \| HTTPS
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	61 v
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	62 nginx
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	63 \|
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	64 \| HTTP :6970
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	65 v
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	66 hg_web_server (main.c + Seobeo)
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	67 \|
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	68 \| HTTP :4444
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	69 v
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	70 hg serve (Zenbu Mercurial repository)
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	71 ```
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	72
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	73 The C server owns the public routes. It serves the application shell and
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	74 assets, translates browser API requests into `hg serve` requests, and streams
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	75 Mercurial wire-protocol traffic without routing bundle data through the normal
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	76 buffered HTTP response path.
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	77
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	78 ## Request flows
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	79
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	80 ### Application shell
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	81
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	82 ```text
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	83 GET /, /directories, or /graph
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	84 -> GetReactHome
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	85 -> hg-web/src/index.html
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	86 -> /page.js
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	87 -> src/main.tsx
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	88 -> components/app.tsx
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	89 ```
192 b818a4561a3c Added AI genreated README.md. Needed to be read. MrJuneJune <me@mrjunejune.com> parents: diff changeset	90
218 921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	91 ### Repository browser
192 b818a4561a3c Added AI genreated README.md. Needed to be read. MrJuneJune <me@mrjunejune.com> parents: diff changeset	92
218 921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	93 ```text
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	94 directory-browser.tsx
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	95 -> GET /api/repo/list?path=...
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	96 -> ApiListDirectory
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	97 -> GET hg-serve/file/tip/<path>?style=json
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	98
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	99 file or README selection
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	100 -> GET /api/repo/file?path=...
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	101 -> ApiGetFile
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	102 -> GET hg-serve/raw-file/tip/<path>
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	103 -> highlight.js or markdown_converter WASM
192 b818a4561a3c Added AI genreated README.md. Needed to be read. MrJuneJune <me@mrjunejune.com> parents: diff changeset	104 ```
218 921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	105
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	106 ### Commit graph
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	107
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	108 ```text
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	109 graph.tsx
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	110 -> GET /api/graph/<revision>?graphtop=...&style=json
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	111 -> ApiGetGraph
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	112 -> GET hg-serve/graph/<revision>?...
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	113 -> React rows + custom pencil/panda canvas
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	114 ```
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	115
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	116 ### Mercurial clone, pull, and push
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	117
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	118 ```text
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	119 Mercurial client
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	120 -> GET or POST /repo
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	121 -> StreamHgWireProtocol
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	122 -> hg serve /?cmd=...
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	123 -> binary-safe streamed response
192 b818a4561a3c Added AI genreated README.md. Needed to be read. MrJuneJune <me@mrjunejune.com> parents: diff changeset	124 ```
b818a4561a3c Added AI genreated README.md. Needed to be read. MrJuneJune <me@mrjunejune.com> parents: diff changeset	125
218 921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	126 ## Route map
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	127
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	128 \| Method \| Route \| Owner \| Purpose \|
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	129 \| --- \| --- \| --- \| --- \|
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	130 \| `GET` \| `/` \| `GetReactHome` \| Application shell \|
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	131 \| `GET` \| `/directories` \| `GetReactHome` \| Legacy application-shell route \|
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	132 \| `GET` \| `/graph` \| `GetReactHome` \| Commit graph application route \|
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	133 \| `GET` \| `/api/repo/list` \| `ApiListDirectory` \| Directory listing JSON \|
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	134 \| `GET` \| `/api/repo/file` \| `ApiGetFile` \| Raw tracked file \|
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	135 \| `GET` \| `/api/repo/readme` \| `ApiGetReadme` \| Alias of the raw-file handler \|
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	136 \| `GET` \| `/api/graph/:graph_id` \| `ApiGetGraph` \| Mercurial graph JSON \|
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	137 \| `GET`, `POST` \| `/repo` \| `StreamHgWireProtocol` \| Mercurial wire protocol \|
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	138
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	139 ## Frontend ownership
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	140
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	141 \| File \| Responsibility \|
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	142 \| --- \| --- \|
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	143 \| `src/components/app.tsx` \| Client-side routes, landing page, tabs, and history \|
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	144 \| `src/components/directory-browser.tsx` \| Breadcrumbs, listings, prefetch, file modals, README rendering \|
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	145 \| `src/components/graph.tsx` \| Graph fetching, pagination, canvas edges, panda nodes \|
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	146 \| `src/components/theme.tsx` \| Stored light/dark preference and system-theme integration \|
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	147 \| `src/components/header.tsx` \| Forge identity and theme control \|
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	148 \| `src/components/footer.tsx` \| Shared footer \|
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	149 \| `src/index.css`, `src/base.css` \| Custom visual language and layout \|
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	150
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	151 Keep the custom assets and visual language in this package. New forge screens
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	152 should reuse the existing CSS variables, typography, textures, and components
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	153 instead of introducing a generic design system.
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	154
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	155 ## Build and local run
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	156
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	157 Build the server and deployable bundle from the repository root:
192 b818a4561a3c Added AI genreated README.md. Needed to be read. MrJuneJune <me@mrjunejune.com> parents: diff changeset	158
b818a4561a3c Added AI genreated README.md. Needed to be read. MrJuneJune <me@mrjunejune.com> parents: diff changeset	159 ```bash
218 921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	160 bazel build //hg-web:hg_web_server
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	161 bazel build //hg-web:hg_web_server_bundle
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	162 ```
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	163
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	164 Run the Mercurial backend:
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	165
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	166 ```bash
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	167 hg serve -a 127.0.0.1 -p 4444
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	168 ```
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	169
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	170 Run the deployable bundle from its own directory so the static root resolves:
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	171
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	172 ```bash
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	173 cd bazel-bin/hg-web/hg_web_server_bundle
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	174 ./hg_web_server
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	175 ```
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	176
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	177 The bundle contains `hg_web_server` and `hg-web/src/`, including generated
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	178 `page.js`, markdown WASM, highlight.js, styles, and image assets.
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	179
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	180 ## Deployment contract
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	181
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	182 The expected production layout is:
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	183
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	184 ```text
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	185 nginx
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	186 -> hg_web_server.service
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	187 -> /opt/hg_web_server_bundle_active/hg_web_server
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	188 -> working directory: /opt/hg_web_server_bundle_active
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	189 -> hg serve service on 127.0.0.1:4444
192 b818a4561a3c Added AI genreated README.md. Needed to be read. MrJuneJune <me@mrjunejune.com> parents: diff changeset	190 ```
b818a4561a3c Added AI genreated README.md. Needed to be read. MrJuneJune <me@mrjunejune.com> parents: diff changeset	191
218 921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	192 `deploy.sh` currently builds an optimized bundle, copies it to `/opt`, swaps
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	193 the active directory, changes ownership to `hg_web_server:zenbu_team`, and
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	194 restarts `hg_web_server.service`.
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	195
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	196 ## Forge capability tree
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	197
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	198 ```text
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	199 Zenbu Forge
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	200 ├── Repository
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	201 │ ├── File and directory browsing available
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	202 │ ├── Syntax highlighting available
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	203 │ ├── README rendering available
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	204 │ ├── Commit graph available
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	205 │ ├── Changeset detail and diff planned
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	206 │ ├── Branches, bookmarks, and tags planned
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	207 │ ├── File history and blame planned
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	208 │ └── Search planned
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	209 ├── Collaboration
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	210 │ ├── Authentication and authorization planned
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	211 │ ├── Changeset review planned
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	212 │ ├── Issues planned
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	213 │ └── Releases and artifacts planned
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	214 └── Automation
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	215 ├── Mercurial incoming/changegroup hook planned
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	216 ├── Durable SQLite job queue planned
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	217 ├── Isolated Bazel runner planned
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	218 ├── Live logs and job status API planned
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	219 ├── Forge status and log screens planned
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	220 ├── Artifact retention planned
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	221 └── Atomic deploy, health check, rollback planned
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	222 ```
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	223
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	224 ## Automation data flow
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	225
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	226 The Actions-like subsystem should extend the existing server rather than
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	227 replace it:
192 b818a4561a3c Added AI genreated README.md. Needed to be read. MrJuneJune <me@mrjunejune.com> parents: diff changeset	228
218 921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	229 ```text
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	230 hg push
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	231 -> Mercurial hook records repository + revision
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	232 -> small enqueue command writes a SQLite job
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	233 -> runner service claims one queued job
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	234 -> isolated shared checkout updates to the exact revision
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	235 -> Bazel build and test steps stream logs
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	236 -> job result and artifacts are recorded
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	237 -> hg-web status API exposes the result
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	238 -> custom React screens render runs, steps, logs, and artifacts
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	239 -> successful protected jobs may call atomic deployment
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	240 ```
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	241
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	242 Start with one runner on the same host. Keep the hook fast, never execute build
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	243 steps inside the Mercurial request, and make the queue durable before adding
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	244 parallel or remote runners.
192 b818a4561a3c Added AI genreated README.md. Needed to be read. MrJuneJune <me@mrjunejune.com> parents: diff changeset	245
218 921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	246 ## Safe extension order
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	247
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	248 1. Harden proxy errors, path validation, response headers, and timeouts.
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	249 2. Add changeset detail and diff APIs, then wire graph clicks to those screens.
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	250 3. Make deployment atomic with health checks and rollback.
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	251 4. Add the hook, SQLite queue, single runner, and retained logs.
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	252 5. Add run/status/log pages using the existing custom UI.
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	253 6. Add authentication and authorization before accepting public pushes or
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	254 user-defined automation.
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	255
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	256 ## Invariants
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	257
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	258 - Keep public application code on Seobeo APIs.
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	259 - Decode and validate every path before forwarding it to Mercurial.
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	260 - Keep `/repo` binary-safe; bundle data can contain null bytes.
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	261 - Do not buffer large wire-protocol responses through the regular HTTP client.
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	262 - Keep backend route names synchronized with frontend fetch and navigation code.
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	263 - Preserve accurate status codes, content lengths, and content types.
921ca3086879 [hg-web] Add architecture wiki tree MrJuneJune <me@mrjunejune.com> parents: 192 diff changeset	264 - Keep secrets in service-owned environment files, not in source or job logs.

Mercurial

annotate hg-web/README.md @ 218:921ca3086879 hg-web