Development

This section is for people working on Bugsaur

Everything here describes the internals. If you are trying to debug your own program, you want Using Bugsaur or Troubleshooting instead — nothing on these pages is needed to use the debugger.

The workspace

Crate	Responsibility
bugsaur	the binary: CLI, session wiring, adapter catalog, logs, IPC server
dap-protocol	DAP types, generated from the protocol schema
dap-client	the DAP client: transports, framing, request management
debugger-core	domain state: commands, events, reduction, the session model
debugger-ui	the window: egui panels, layout, keys, theme
project-config	.bugsaur/config.toml, detection, .env, breakpoints
source-frontend-protocol	the wire types between debugger and editor
nvim-ipc	the Unix-socket server for the source frontend
php-dbgp-adapter	Bugsaur's own DBGp adapter for PHP
test-discovery	finding the test under a cursor position
fake-dap-adapter	a scriptable adapter for tests

This section

Page	What it covers
Architecture	how the pieces fit together, and who owns what
DAP model	how the protocol is represented and driven
IPC	the debugger–editor boundary
Contributing	building, testing, and the toolchain trap
Architecture Decision Records	why things are the way they are

The invariant everything else follows from

Bugsaur owns the debug session. It is the only DAP client and the authoritative holder of state. The editor is a replaceable source frontend, and the GUI is a view.

Most design decisions in this codebase are consequences of that sentence: the session outliving the editor, the config being read by the debugger rather than the editor, breakpoints living in the project, and the editor never being sent variables or stack contents to hold.