Architecture

dqx is Bun and TypeScript, compiled to a single binary. Two rules shape everything else.

Ports and adapters

src/core/ is pure. It computes plans, renders configuration, decides what is wrong. It touches no filesystem, spawns no process, opens no socket. Give it the same input and it returns the same answer, always.

src/adapters/ does the touching. Filesystem, docker compose, git, mkcert, the DNS socket. Adapters are thin: they gather facts, hand them to core, and carry out what core decided.

The backends sit behind one interface (EnvPort), so dqx up on Docker Compose and on DDEV are the same code path with a different adapter underneath. Adding a fifth backend is implementing that interface, not editing the commands.

src/
  core/        pure logic — config, plans, checks, generators
  adapters/    the outside world
  commands/    the CLI surface, thin
  ports/       the interfaces adapters implement

The consequence that matters

Because core is pure, it can be tested exhaustively without a container, and it is: every line of src/core/ is covered, enforced by a gate that fails the build. That is affordable precisely because core has no I/O to mock.

It also means logic cannot hide in an adapter. When a check turns out to be wrong — and several have — the fix is in a function with a test beside it, not in a command that only runs when Docker is up.

Generated, never hand-maintained

A project's environment is generated from its declaration on every sync. Nothing in it is precious: delete it, regenerate it, get the same thing back.

That is only true if the generator can reproduce everything the project needs, so when it cannot, dqx says so rather than quietly dropping it — and compose: in the config exists for exactly the keys it does not generate.

What the code reads like

Comments explain why, not what. A comment that restates the line above it is noise; a comment naming the failure that made the line necessary is the reason the codebase is navigable at all.

Most of the sharper ones exist because something failed in a way that was hard to see, and the comment is there so the next person does not undo the fix.