Technical reference
Learn how the open-source Joshu box works and why, with the architecture, design decisions, and code map of each subsystem.
The technical reference tells developers how Joshu works and why it works that way. It is for each person who reads or changes the code of Joshu, including the contributors to the open-source repository. Each technical reference document covers one subsystem. The document tells the problem that the subsystem solves, how the parts of the subsystem fit together, what happens at run time, and the reason for each important design decision.
The technical reference is not a user guide. A user guide tells owners how to use Joshu, and the technical reference tells developers how Joshu is built.
- Part 1System overviewThis overview shows how one Joshu box is built from end to end, from the desktop and companion runtime to channels, and why the boundaries exist.
- Part 2Slack chatJoshu talks with its owner in Slack through a Slack app on each box, and this page explains its tokens, the first message, and the design.
- Part 3Shared browser live view and session lifetimeThe shared browser lets the owner and Joshu use one browser, and this page explains jWeb, the handoff page, the tab strip, and session lifetime.
- Part 4Voice agent toolsThe Joshu voice agent calls tools during a phone call, and this page explains the async tool path, the delivery claim guard, and the work claim guard.
- Part 5Realtime goals — theory of operationJoshu routes owner messages on SMS, voice, Slack, and Telegram into goals, and this page explains how it keeps each conversation on track.
- Part 6Public docsOne text of each manual chapter serves hosted and self-hosted owners, and this page explains the block markers and how the exports keep private text out.
How to read the technical reference
If Joshu is new to you, read the system overview first. It shows how a box is built from end to end (the desktop, the Joshu API, Hermes, Kanban workers, connectors, memory, voice, and the Docker stack), and why the main boundaries exist. Then read the gentle introduction to the app architecture and the platform architecture, which show the three layers of the app platform (apps, the platform data plane, and the runtime) and how a request moves between them. Then read the document of the subsystem that you want to change.
Technical reference documents in other folders
| Subsystem | Document | What you learn |
|---|---|---|
| Platform and apps | platform-architecture.md | The three layers, the domains, the packages, and the app invoke API. |
| Platform and apps | joshu-app-architecture-intro.md | How the companion reaches an app through skills, the app GUI, and voice, with diagrams. |
| Platform and apps | platform-data.md | The TypeScript client that apps use to read mail, calendar, and files. |
| Hermes | hermes-integration.md | Why Joshu customizes Hermes with skills, plugins, and environment variables instead of a fork, and where each customization goes. |
| Box access | box-api-edge-security.md | Which routes of the box API a request from the internet can reach, which need a desktop session or a direct localhost request, and how an admin desktop login signs in as the owner with a one-time link. |
| Instance agent | instance-agent-protocol.md | How the instance agent gets signed commands from the control plane, which commands it runs, and what each command returns. |
| Realtime goals | realtime-goals.md | The acknowledgment, the follow-up questions, and the results on the channel of the request. |
| Safety | agent-safety.md | The three tiers that control the writes of the companion, and how the owner approves a write. |
| Mail and calendar | connectors.md | How the connector apps copy mail and calendar into Markdown files, index the files, and give the companion a small set of actions. |
| Files and search | file-brain.md | How gbrain indexes the Desktop files and answers hybrid search. |
| Kanban engine | kanban/hermes-kanban-engine.md | How Hermes runs Kanban workers on a box, which Joshu patches change Hermes Kanban, and when Joshu stops the worker of a task. |
| Proactive nudges | kanban/cross-board-readers.md | How the hourly proactive tick picks one owner question from all boards, when it composes and sends a nudge, and how owner replies reach the task. |
| Teams | teams.md | How the companions of different owners work together in a team stand-up. |
| Whiteboard | jwhiteboard-developer-guide.md | How the UI, the semantic model, storage, the embedded agent, and voice of jWhiteboard fit together. |
| Whiteboard | curatorial-whiteboard.md | The semantic and review layer beside an Excalidraw board, and its authority rules. |
| Box stack | vps-sandbox/README.md | The Docker stack of a box on a VPS or a local host. |
| Build | runtime-assets.md | Why the files that the API reads at run time must be copied to dist/. |
| Repositories | oss-fleet-sync.md | How the public repository and the fleet repository stay aligned. |
What a technical reference document has
Each technical reference document has these sections, in this order. A short document can join two sections, but it must keep the content of each.
- Purpose: what the subsystem does, in two or three sentences.
- Motivation: the problem that the subsystem solves, and the constraints that shaped the design (for example cost, privacy, or a limit of an upstream project).
- Architecture: the components, the boundary of each component, the data that each component owns, and how the components connect. Add a Mermaid diagram when a diagram is clearer than text.
- Theory of operation: what happens at run time, step by step, and the mental model that a developer needs to predict the behavior of the subsystem.
- Design decisions: one entry for each important decision, with the date, the decision, the alternatives that were considered, and the reason that the decision won. When a later decision replaces an entry, keep the entry and write which entry replaces it.
- Limits and failure modes: what the subsystem does not do, what can go wrong, and how the subsystem recovers.
- Code map: the main files, the entry points, the configuration, and the tests.
Write about the current design. The design decisions section is the only place for history; release notes and GitHub issues hold the rest.