title: Zenbu repository wiki status: canonical audience:

humans
AI agents last_reviewed: 2026-08-23 ---

Zenbu repository wiki

This page is the monorepo knowledge router. It explains what Zenbu contains and directs humans and agents to the smallest canonical documentation set needed for a task.

Reading protocol

repository index -> relevant project wiki -> BUILD graph -> source and tests

Do not scan every project document by default. Choose documentation from the routing table below. For cross-project work, inspect Bazel dependencies first, then read only the wikis owned by actual producers and consumers.

Documentation routing

Task paths or topic	Canonical documentation
`connectors/`, Google OAuth, Drive, Gmail, AI context tools	`connectors/wiki/README.md`
`design_system/`, shared components, tokens, HTML authoring	`design_system/wiki/README.md`
`seobeo/`, HTTP, TLS, servers, clients, SSE, WebSockets	`seobeo/README.md`, then only the relevant page in `seobeo/docs/`
`mrjunejune/`, personal site, auth UI, conversations, media	`mrjunejune/README.md`
`hg-web/`, Mercurial repository browser	`hg-web/README.md`
`yuu/`, spatial entities, rendering, context, persistence, hydration	`yuu/wiki/README.md`
`dowa/`, arenas, strings, arrays, hash maps, math	`dowa/README.md`
`deita/`, SQLite wrapper	`deita/README.md`
`s3/`, presigned uploads	Source header and `BUILD`; no dedicated wiki yet
`markdown_converter/`	Package `BUILD`, public headers, and tests
`gui_ze/`, asset bundling macros	`gui_ze/wiki/README.md`
Experiments and standalone prototypes	The package README when present, then its `BUILD`

Monorepo map

Shared foundations

dowa: core C types, arena allocation, strings, dynamic arrays/hash maps, and math.
deita: SQLite connection, prepared query, and result-set wrapper.
seobeo: networking, HTTP client/server, TLS, SSE, and WebSockets.
auth: Zenbu users, sessions, cryptography, and reusable HTTP auth.
config: Bazel platform configuration.

Services and applications

connectors: Google data connector service and AI tool boundary.
mrjunejune: personal website and production server.
hg-web: Mercurial repository browser.
npc: MCP-oriented C server experiment.
dictation, schwab_trader, yuu, and other package roots: focused applications or prototypes.

Web and asset systems

design_system: shared light-DOM Web Components and design tokens.
gui_ze: Bazel macros for asset copying, bundling, and transformations.
assets: shared icons and other reusable assets.
markdown_converter: C/WASM markdown conversion.
rich_editor and react_games: browser bundles consumed by applications.

Build and workflow

Zenbu is a Fossil repository. Use:

fossil status
fossil diff
fossil sync

Bazel-only rule

Zenbu is Bazel-only. Bazel is not just the C build tool; it is the repository's execution and dependency boundary.

Use Bazel for:

C/C++ libraries, binaries, and tests;
shell and Python entry points;
Node/Bun-driven frontend generation;
WASM compilation;
asset copying, image conversion, and bundles;
downloaded tools, browser runtimes, and model runtimes;
integration and end-to-end tests.

Do not add or rely on:

Makefiles or direct make workflows;
CMake project files;
manual cc, clang, or gcc build commands;
npm run, bun run, or pip install as the normal repository interface;
undocumented system packages or /usr/local libraries;
scripts that bypass Bazel runfiles and declared data.

An upstream ecosystem command may run inside a Bazel rule or a narrowly scoped maintenance workflow, but the committed user/agent interface must be a Bazel target.

Build and test from the repository root:

bazel build //seobeo:seobeo
bazel test //seobeo/tests:seobeo_http_framing_test

bazel build //mrjunejune:mrjunejune_server
bazel test //mrjunejune/test:integration_test

bazel build //connectors:connector_server
bazel test //connectors:connector_tests

bazel build //hg-web:hg_web_server

Inspect a package's BUILD file before broad searches. Keep dependencies on the smallest target that needs them.

Package selection guide

Choose an existing first-party package before writing a new helper or directly depending on third-party code.

Need	Use	Typical Bazel label	Do not substitute by default
Integer aliases, booleans, arenas, strings, arrays, hash maps, JSON helpers, math	`dowa`	`//dowa:dowa`	libc allocation scattered through request code, a second containers library
SQLite connections and prepared queries	`deita`	`//deita:deita`	direct `sqlite3_*` calls in application packages
TCP/TLS primitives without HTTP	`seobeo_min`	`//seobeo:seobeo_min`	raw sockets/OpenSSL setup duplicated in applications
HTTP server without WebSockets	`seobeo_tcp_server`	`//seobeo:seobeo_tcp_server`	another embedded HTTP server
HTTP server with WebSockets	`seobeo_tcp_server_ws`	`//seobeo:seobeo_tcp_server_ws`	direct WebSocket framing
Outbound HTTP/TLS only	`seobeo_tcp_client` or compatibility alias `seobeo_client`	`//seobeo:seobeo_tcp_client`	libcurl subprocesses or hand-built HTTP clients
Full HTTP/TLS/WebSocket stack	`seobeo`	`//seobeo:seobeo`	depending on every network source manually
Verbose Seobeo diagnostics	`seobeo_debug`	`//seobeo:seobeo_debug`	permanent `printf` debugging
User, password, session, cookie, CSRF, and auth crypto	`auth`	`//auth:auth`, `//auth:auth_http`	creating another login/session store
Google OAuth, Drive, Gmail, encrypted provider credentials, AI connector tools	`connectors`	`//connectors:connector_core`, `//connectors:connector_service_lib`	provider token logic inside unrelated applications
S3 signing and presigned uploads	`s3`	`//s3:s3`	ad-hoc AWS signature code
Native and WASM markdown conversion	`markdown_converter`	`//markdown_converter:markdown_to_html_c`, `//markdown_converter:markdown_to_html_wasm`	a second markdown pipeline
Shared Web Components, tokens, and UI primitives	`design_system`	package targets in `//design_system`	application-local copies of shared controls
Shared icons and generated image assets	`assets`	`//assets:icons`	copying asset files between applications
Web asset moves, bundles, WebP conversion, Bun actions, macOS bundles	`gui_ze` macros	`//gui_ze:gui_ze.bzl`	custom copy scripts and undeclared output folders
Shared rich text editor browser bundle	`rich_editor`	package targets in `//rich_editor`	forking editor code into an app
Personal site server and its production bundle	`mrjunejune`	`//mrjunejune:mrjunejune_server`	treating site-specific code as a generic library
Mercurial browser service	`hg-web`	`//hg-web:hg_web_server`	shelling out from unrelated UI code without its API boundary
MCP-style C HTTP server experiment	`npc`	`//npc:npc`	assuming it is a general connector framework
Raylib application rules	`third_party/raylib` macro plus first-party app package	`//third_party/raylib:raylib.bzl`	manual platform linker flags
Qwen/llama.cpp runtime orchestration	`qwen3_vl`	`//qwen3_vl:model`, `//qwen3_vl:serve`	untracked local model commands

Package boundary rules

Put reusable behavior in the narrowest shared package that owns the concept.
Applications may compose libraries; libraries must not depend on applications.
Avoid circular ownership such as dowa knowing about Seobeo or a site.
Expose public headers through the owning library target.
Add deps to the smallest target that compiles the source using them.
Use platform-aware aliases already provided by packages such as Seobeo and S3.
Search for an existing helper or macro before creating a sibling implementation.

Third-party dependency policy

Third-party code enters Zenbu through one of two Bazel-controlled paths:

A pinned Bzlmod dependency or repository rule in MODULE.bazel.
A vendored wrapper under third_party/<name>/BUILD.

Applications should depend on public Bazel labels, not include vendored source paths or reproduce platform flags.

Prefer first-party wrappers

Use Deita instead of direct SQLite APIs unless changing Deita itself.
Use Seobeo instead of raw sockets, OpenSSL transport code, or curl processes.
Use the S3 package instead of implementing AWS signing in an application.
Use gui_ze macros instead of manual generated-asset copying.
Use markdown_converter rather than adding another markdown dependency.
Use auth for Zenbu identity; external OAuth credentials belong in connectors, not a parallel user system.

Adding an external dependency

Before adding one:

Search first-party packages and existing third_party/ wrappers.
Confirm the behavior cannot be implemented safely with an existing library.
Add the dependency through MODULE.bazel when Bzlmod support is suitable; otherwise add a focused third_party/<name>/BUILD wrapper.
Pin versions and SHA-256 hashes for downloaded archives/files.
Preserve license files and upstream notices.
Expose only the smallest useful Bazel target and visibility.
Keep platform selection inside the wrapper, not every consumer.
Add or update lockfiles when the ecosystem requires them.
Document why the dependency exists and which first-party package owns its abstraction boundary.

Do not fetch executable code at ordinary runtime when it can be a declared Bazel dependency or data artifact.

Existing external systems

External system	Bazel integration and intended use
OpenSSL	Bzlmod `@openssl`; TLS and crypto, normally behind Seobeo/auth/connectors
SQLite	`//third_party/sqlite3`; normally consumed through Deita
Emscripten	`@emsdk` local override; WASM targets such as markdown conversion
Node/npm	rules_nodejs and aspect_rules_js; locked frontend/test dependencies
Python/pip	rules_python toolchain and package-specific locked hubs
Bun	pinned platform archives and `gui_ze` actions
Chromium/Playwright	pinned browser runtime for browser and integration tests
Tectonic	pinned runtime for LaTeX rendering
FFmpeg	`//third_party/ffmpeg` wrapper for media processing
Raylib	`//third_party/raylib` plus `raylib_binary` for native/web applications
libuv	`//third_party/libuv` for event-loop experiments such as Postdog
LuaJIT	`//third_party/luajit` for packages that explicitly declare it
Mercurial	wheel/runtime wrappers for hg-web tooling
Fossil	pinned `//third_party/fossil:fossil` administration CLI
CEF	repository rule under `third_party/cef` for the yuu native surface
llama.cpp/CUDA runtime	pinned archives exposed through `qwen3_vl` Bazel targets

First-party conventions

Prefer Dowa integer and boolean aliases plus TRUE/FALSE.
Allocation is arena-first. New first-party C code must not call raw malloc, calloc, realloc, or free.
Create a Dowa_Arena at the owner boundary, pass it into helpers, and use Dowa_Arena_Allocate, arena string helpers, and the _Arena array/hash-map macros.
Free each locally owned arena exactly once with Dowa_Arena_Free on every return path. Never individually free an arena-owned pointer.
Borrowed request arenas are never freed by callees.
Long-lived objects should own an arena whose lifetime matches the object. A non-arena allocation is permitted only at a true allocator/runtime or external-API ownership boundary, must be narrowly documented, and must use the matching first-party/external destructor. It is not a convenience escape hatch.
Use Seobeo logging and response-map conventions in Seobeo services.
Keep runtime secrets in one ignored, documented service config file.
Commit placeholder templates only; do not commit real credentials.
Preserve platform-aware Bazel aliases and precise dependencies.

Arena enforcement

Run:

bazel test //:arena_policy_test

The policy target fails when:

a new first-party C/H file introduces raw allocation calls; or
a legacy file increases its reviewed raw-allocation baseline.

The baseline is technical debt, not permission to add more allocation in those files. Changes should reduce it. Updating the baseline upward requires an explicitly documented allocator/runtime boundary and review.

Typical ownership:

Dowa_Arena *p_arena = Dowa_Arena_Create(64 * 1024);
if (!p_arena)
  return FALSE;

char *copy = Dowa_Arena_Allocate(p_arena, length + 1);
if (!copy)
{
  Dowa_Arena_Free(p_arena);
  return FALSE;
}

/* All arena-owned values die together. */
Dowa_Arena_Free(p_arena);

Wiki model

The repository index is the schema and router. Project wikis are synthesized, canonical knowledge for a bounded domain. Source code, BUILD files, tests, and committed config templates are evidence.

The Fossil wiki holds the public homepage, roadmap, and project-level notes. Technical documentation stays in these versioned wiki/ directories so it is reviewed and updated with the source it describes.

When a task changes knowledge:

Update the owning project wiki.
Update this routing page only if ownership, package boundaries, or canonical documentation locations changed.
Do not create one-off top-level notes or duplicate normative instructions.
Split a project wiki only when its index becomes hard to navigate; every new page must be linked from the project wiki.

Current wiki coverage

Domain	State
Repository map and agent routing	Canonical
Connectors and AI retrieval	Canonical
Design system	Canonical multi-page wiki
Seobeo	README plus focused protocol docs
Other packages	Existing README or source-first; promote to a wiki when the domain accumulates durable operational knowledge