architecture.md

docs/architecture.md

1. # Architecture
3. ```
4. +------------------------------ Cortex.app ---------------------------------+
5. | |
6. | WebView (React) Rust (Tauri shell, src-tauri) |
7. | +-----------------------+ invoke +------------------------------+ |
8. | | main window | ------------> | commands.rs | |
9. | | sidebar, chat, | | thin wrappers | |
10. | | composer, picker, | <-- Channel - | (stream events) | |
11. | | settings, usage | | windows.rs | |
12. | +-----------------------+ | vibrancy, quick window, | |
13. | | quick window | | tray, global shortcut | |
14. | +-----------------------+ +--------------+---------------+ |
15. | no network, no keys, no paths | |
16. | +---------------v---------------+ |
17. | | cortex-core | |
18. | | provider: SSE, client, | |
19. | | errors, cancellation -----> DeepInfra or a
20. | | chat: one turn end to end | | local server
21. | | pricing, cost, estimate | |
22. | | storage: SQLite + FTS5 | |
23. | | attachments, export, secrets ----> OS keychain
24. | +-------------------------------+ |
25. +---------------------------------------------------------------------------+
26. ```
28. ## The split
30. - **`crates/cortex-core`** holds all the logic and has no Tauri dependency, so
31. it builds and tests in seconds on any machine. The whole of a chat turn
32. (history into a request, streaming, stopping, usage, cost, saving) is one
33. function, `chat::run_turn`, tested against the stand-in server.
34. - **`src-tauri`** is the shell: commands that call into the core, the two
35. windows, the tray and the shortcut.
36. - **`src/`** is the interface. It talks to Rust only through the `IpcClient`
37. interface (`src/ipc/client.ts`), which has two implementations: the real one
38. (`tauri.ts`) and an in-memory one with sample data (`mock/`), which the
39. browser tests and the screenshots use.
40. - **`crates/standin`** is a small OpenAI-compatible server whose behavior is
41. picked by model id (echo, slow, no usage, reasoning, vision, errors). Every
42. provider path is tested against it, and so is the real app end to end.
44. ## Rules the code keeps
46. - **The webview never sees a key or the network.** Provider calls happen in
47. Rust. The CSP allows no outside connections. Keys are write-only from the
48. interface: it can set, clear and ask whether one exists.
49. - **The webview never supplies a file path.** File pickers are opened from
50. Rust; pasted and dropped files arrive as bytes.
51. - **Each window gets only the commands it needs.** `build.rs` declares every
52. command, so each one needs a permission; the quick window's capability
53. grants 14 of them (`src-tauri/capabilities/`).
54. - **No model call behind your back.** Chats are titled from their first line,
55. not by asking a model. Failed requests are not retried automatically,
56. because a retry is billed.
57. - **Types cross the boundary once.** Rust structs generate their TypeScript
58. twins (`src/ipc/gen`, via ts-rs) when the tests run; CI fails if they are
59. stale.
61. ## Streaming
63. `provider/sse.rs` is a byte-level Server-Sent Events parser: a network chunk
64. can split a line, a `\r\n` pair or a UTF-8 character anywhere, and a property
65. test feeds it every way of cutting the same stream. `provider/openai.rs` reads
66. each chunk tolerantly (DeepInfra, Ollama and llama.cpp each differ a little)
67. and keeps the last usage block seen, whether it arrives on the final content
68. chunk or in a chunk of its own. Deltas are batched about every 30 ms on the way
69. to the interface, which paints them once per frame.
71. Stopping cancels a token held by the stream: the read loop drops the HTTP
72. connection at once (the stand-in test checks the server sees it go), and the
73. partial reply is saved as `cancelled`, with estimated tokens.
75. ## Storage
77. One SQLite file in the app's data folder. Tables for providers, conversations,
78. messages (with tokens, prices and cost on each row), attachments, presets,
79. settings and the model price list. FTS5 indexes messages and titles, kept in
80. step by triggers; search input is quoted word by word, so nothing typed can
81. break the query. A reply left `streaming` by a crash is marked interrupted at
82. the next start. Images are stored once per content hash, downscaled first to
83. 1568 px on the long edge, because vision models bill by size.
85. ## Windows
87. - **Main:** created hidden and shown when the page has painted (no white
88. flash). Closing it hides it; Quit quits. On macOS it has a transparent
89. overlay title bar over `Sidebar` vibrancy.
90. - **Quick prompt:** a separate small page, created hidden at startup so it
91. opens at once. A global shortcut (Cmd+Shift+Space by default) shows it on the
92. screen under the pointer; it hides on Esc or when it loses focus.
93. - **Tray:** new chat, quick prompt, this month's spend, settings, quit.
95. On Linux the window is opaque and the page paints its own soft backdrop behind
96. the glass. Windows is not built or tested.