Introduction

Atlas is a document governance API backed by S3. Files live in a bucket and are always visible there, whether or not anyone ever tells Atlas about them. Declaring a file adds governance on top — status, business properties, relationships to other documents — without ever copying or mirroring the bucket’s contents into a database.

That serves two rather different audiences, deliberately with the same tool:

Administrators

Already have data sitting in an S3 bucket and want a real interface to browse, search, and manage it — the console an S3 admin panel was never quite meant to be.

Business teams

Want to take back control and governance over data that already lives in a bucket: who can see what, whether a file has been reviewed, what it’s linked to.

Two rules summarize the whole design:

• S3 decides what exists. Browsing the API reads the bucket live, every time. There is no index of files to fall out of sync.
• The database decides what’s governed. It only stores what S3 has no concept of — status, custom metadata, links between documents.

A file dropped into the 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. See Architecture for how those two rules turn into an actual system, and Definition for the vocabulary (Bucket, Workspace, Object, MetaObject, Document, Orphan, Stale).

Core philosophy

An object is never mutated by Atlas once it lands in the bucket — what you get back through the API is byte-for-byte what’s actually in S3, never a converted, resized, or otherwise transformed copy. Atlas only ever adds governance next to a file; it never touches the file itself.

That’s a deliberate constraint, not a missing feature:

• Atomicity and precision — the moment something rewrites bytes on your behalf, “what’s in the bucket” and “what’s been processed” can silently diverge. That’s exactly the class of drift the two rules above exist to rule out.
• A simple component — supporting every file format’s own read/write/ transform semantics is a different, much larger product than governance. Staying out of that business is what keeps Atlas small enough to actually reason about.
• Staying as close to S3 as possible — S3 already stores bytes reliably. Reimplementing any part of that inside Atlas would just be a worse version of a solved problem.

What Atlas does today

• Browse a bucket like a console — list, download, rename, move, delete, create folders — on any bucket Atlas has credentials for, registered or not.
• Add governance on top, through Documents — status, free-form business properties, and links to other documents, layered next to a file without ever touching it.
• Turn a bucket into a Workspace to unlock a full governance layer on top of it: members, fine-grained roles, and an audit log of every mutating action.
• Sign in your way — OIDC/SSO, a local break-glass account, or a long-lived API key for scripts and service accounts.
• Detect drift automatically — orphan (the file is gone) and stale (it changed since declaration), checked live against S3, no background job required.
• Upload from the browser over the TUS protocol — resumable, multipart, and optionally auto-declared as a Document the moment it finishes.
• Stick to standard technology throughout — plain S3 API calls, Postgres, nothing proprietary to learn.
• Notify external systems with signed outbound webhooks on every audit event.
• Report accurate bucket statistics — recomputed straight from source on every read, never a stale counter.
• Automate through a REST API, a generated Python SDK, and API keys.
• Expose native S3 features directly — versioning, lifecycle policies, Object Lock, tagging — configured per bucket, not reimplemented by Atlas.
• Search and sort declared documents across a workspace.
• Authorize by role (READER / MEMBER / MANAGER), granted to a person or a whole OIDC group, re-checked on every request.
• Stay observable — structured request logs, a queryable audit trail, and a Prometheus metrics endpoint.
• Ship on a modern, robust stack — a Python API, a Next.js frontend — with no long-term S3 lock-in: two cleanly separated layers (S3 for bytes, Postgres for semantics), so dropping Atlas leaves every file exactly where it was, still fully usable on its own.

It runs as a standard OCI container under Docker or Podman, and fits a Kubernetes Deployment just as easily — see Installation for what’s actually published today.

What it isn’t

Atlas doesn’t process files itself — no OCR, no thumbnails, no content extraction. It hands you presigned URLs and lets your own pipelines do that work, notified through webhooks. It doesn’t render or preview a file’s content in the browser either — browsing surfaces the list and its metadata, not a PDF or image viewer. Editing a file in place, converting it to another format, and bulk operations across many documents at once are all out of scope too — each is a different, larger product than a governance layer over files you already own.

For how Atlas compares to an S3 console, a NAS, a sync platform, an enterprise GED suite, a document archiver, or a data catalog, see Alternatives.

QuickstartDocker Compose, running in a couple of minutes

DefinitionBucket, Workspace, Object, Document — the vocabulary

ArchitectureHow the pieces fit together, and why

API RéférenceGenerated from the OpenAPI schema