[Janil-ship-it]

Summary

• Add English and Chinese codebase tour tutorials.
• Explain the current repository structure and the main desktop, sidecar, CLI, and server entry points.
• Add a Mermaid architecture diagram to orient new contributors.
• Register the tutorial in the documentation website.

Validation

• npm run build — passed in website/.
• git diff --check — passed.

Closes #167

[GoDiao]

Thanks for the quick turnaround! The structure works well, and the "where to start" section is exactly what new contributors need. We checked the tour against the current code, and two things are wrong. Please fix them before we merge:

1. src/assistant/ isn't where the agent lives.
That directory only holds generated stubs. src/assistant/index.ts starts with // @generated stub from scan-missing-imports, and every export is a no-op proxy. The tour points to it in three places: the repository map, node G in the diagram, and "Agent behavior or tools". The agent actually lives here:

• the main loop: src/query.ts and src/QueryEngine.ts
• tool definitions: src/tools/
• tool execution: src/services/tools/

2. The diagram's launch path doesn't match how the app runs.
The diagram shows the sidecar choosing between server and CLI as two parallel modes. In the desktop app, the flow is:

• Tauri starts the sidecar in server mode only (start_server_sidecar in desktop/src-tauri/src/lib.rs).
• The desktop UI talks to that server directly over HTTP and WebSocket, not through Tauri.
• For each session, the server spawns a separate CLI process (resolveCliArgs in src/server/services/conversationService.ts), and the agent runs inside that process.
• The sidecar's cli mode is what the dreamcoder command uses in a terminal.

"One CLI process per session" is probably the most useful single fact for a new contributor, so it's worth showing in the diagram. Roughly:

flowchart TD
    UI["Desktop UI<br/>desktop/src/"] -->|HTTP / WebSocket| S["Server<br/>src/server/"]
    T["Tauri<br/>desktop/src-tauri/"] -->|starts sidecar in server mode| S
    S -->|spawns one per session| C["CLI process<br/>src/entrypoints/cli.tsx"]
    C --> A["Agent loop and tools<br/>src/query.ts, src/tools/"]

Loading

Smaller things:

• Please add the language switch line at the top of both files, like the other pages (English | [简体中文](./07-codebase-tour.zh.md) and the reverse). The site strips it, but it's what readers see on GitHub.
• Please add the page to the tables in docs/tutorial/README.md and README.en.md.
• Please drop the last paragraph about older walkthroughs being out of date. We'll update those chapters ourselves.
• English title: "Codebase tour", to match the sentence case of the other titles (both in the file and in tutorial.ts).

One open question where we'd like your view. As 07, the tour becomes part 7 of the walkthrough, and "Next" on part 6 leads to it. But the walkthrough explains the code at a pinned September commit, the tour describes the code as it is now, and the tour is probably the first thing a new contributor should read. Should it stay 07, or be a separate page outside the numbered series? Go with your own judgment, and just tell us why.

Thanks again!