Architecture
Atlas sits next to S3, not on top of it. Every read of “what files exist” goes straight to a live S3 listing — there’s no cache, no index, no background sync job that could drift from reality. What Postgres stores is strictly the part S3 has no concept of: a document’s status, its business properties, and its relationships to other documents.
browse, download
Objects & versions
declare, search, link
Documents · Links · Events
A Document points at S3 by bucket + key — never a
copy of the object itself.
A file dropped into a bucket by hand, a script, or a third-party tool is immediately visible and downloadable through the API — it just has no status, properties, or place in a search filter until something declares it. Declaring is idempotent and the only way to attach governance to a file, no matter which producer creates it: a script, an upload, or a person clicking “index” in the browser all go through the same door.
Mirroring S3’s contents into a database is the obvious design, and the wrong one: the moment a file is uploaded, deleted, or overwritten outside the app — a script, another team, the storage console — a mirror goes stale, and nothing in the system would know. Reading S3 live removes that whole class of bug at the cost of a network call per read, a trade Atlas makes everywhere except the couple of things S3 genuinely can’t answer on its own, like searching by a business property.
The codebase mirrors the split
Section titled “The codebase mirrors the split”“Talk to S3” and “talk to Postgres” are never the same function, let alone the same line of code:
Request/response shapes
Talks to Postgres
Talks to S3's SDK
No I/O, no dependencies
The domain layer depends on nothing else, and exactly one module is allowed to talk to S3’s SDK directly — everything above it goes through a narrow storage interface instead. That’s what makes it possible to test governance logic (staleness, permissions, search) without a real bucket or a real database anywhere near the test.