Atlas architecture

Atlas is one repository holding two things: the wiki content plus the static site that renders it, and the atlas tool that reads and writes that content.

Parts

Part	Location	Job
CLI + MCP server	root package, bin/ and src/	Read and write documents from any codebase
Site	site/	Astro Starlight, builds the content to static HTML
Content	site/src/content/docs/	The wiki itself, one markdown file per page
Registry	site/src/data/sites.json	The list of sites, so missing documentation is detectable

How a write works

1. atlas push resolves --site and --type to a document path.
2. It refreshes a local clone of this repository at ~/.atlas/cache.
3. It scans the content for anything credential-shaped and refuses if it finds any.
4. It builds frontmatter — owner from your git config, repository and commit from your working directory, verification date from today.
5. It commits to main and pushes. Coolify rebuilds and redeploys.

There is no review step. Direct commit is deliberate: at this team size, friction costs more documentation than review saves.

How a read works

The MCP server searches the same local clone with an in-process text scan — no backend, no index, works offline. Results are ranked title, then heading, then body.

Deployment

Coolify builds site/ on push to main and serves the static output. Access is restricted by a Traefik IP allowlist covering the office and the VPN.