Architecture diagrams

Five pictures that between them explain what MechCrate is. Each one is embedded elsewhere in the docs next to the prose it belongs to; this page collects them so you can see the whole system at once.

They are authored as Mermaid in src/components/diagrams/sources/ and rendered to static SVG ahead of the build, so there is no diagramming JavaScript on this page. The pictures are in the HTML, which is also what llms-full.txt and any scraper sees.

Ecosystem topology

The problem MechCrate starts from: you need three services from one repo and one from another, not all fourteen. One Traefik router runs per workstation. Projects attach to the shared devmesh-traefik network and declare a Host() rule in their compose labels, so a service is reachable at a hostname the moment it is up, and costs nothing when it is not.

One router per workstation. Every project attaches to the same devmesh-traefik network, Traefik reads Host() rules off container labels, and only the services you started are up.

The folder contract

Every mx project has the same shape. That is what lets make dev mean the same thing in a Rust API, an Astro site and a Laravel app: the verbs live in make/*.mk and scripts/*.sh, which mx owns and can upgrade, while apps/ and docker/system/ stay yours.

Every mx project has the same shape, so every project answers to the same verbs. mx owns the contract; you own apps/{service} and docker/system.

Compose layering

There is one compose file per service describing what it is, and a .dev.yml override describing what it needs while you are working on it: the source mount, the HMR port, a healthcheck with room to boot. make dev merges both; make up uses the baseline alone, which is the same file that ships.

A baseline compose file describes the service everywhere; a dev override adds the source mount, the HMR port and a relaxed healthcheck. make dev merges the two, make up uses the baseline alone.

The AI loop

The techniques corpus is a Postgres + pgvector store that agents query through the MCP server’s rag_context tool. What fills it is a research pipeline that opens a pull request, so the corpus only ever learns things a human agreed to merge. The same markdown is published here under Techniques Corpus.

Agents read the corpus through the MCP rag_context tool. The research pipeline writes to it, but only through a pull request a human merges, so the corpus grows on purpose.

Recipe install flow

mx add is not a file copier. A recipe manifest declares options, placeholders, directories, an optional framework scaffold command and a set of templates; mx resolves them in order, lands the compose files, dockerfiles and env file, writes the Traefik labels for your domain, and hands you a make dev that works.

mx add reads a recipe manifest, expands its placeholders, scaffolds the framework app, lands the compose, dockerfile and env files, and writes the router labels. Then make dev.

Editing a diagram

The sources are Mermaid flowcharts. Change one, then re-render and commit both:

cd site/apps/site
npm run diagrams          # renders light + dark SVG pairs
npm test                  # fails if a source drifted from its rendering

Rendering needs a Chromium build (npx playwright install chromium); nothing else does. astro build only inlines the committed SVGs, so CI and the deploy never touch a browser.