docs: Add crate-level architecture documentation#304
Merged
Conversation
Reflect that is_redirect_tombstone is no longer part of the shared from_headers/to_headers methods after #303.
Semver Impact of This PR🟢 Patch (bug fixes) 📋 Changelog PreviewThis is how your changes will appear in the changelog. New Features ✨
Documentation 📚
Internal Changes 🔧
🤖 This preview updates automatically when you update the PR. |
lcian
approved these changes
Feb 16, 2026
jan-auer
added a commit
that referenced
this pull request
Feb 16, 2026
…y-parsing * origin/main: docs: Add crate-level architecture documentation (#304)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This is the starting point for more extensive documentation. The architecture docs added here cover the high-level design of each crate. Over time, we will expand documentation into submodules and individual types, which may elaborate on the concepts introduced here and push some of this content further down in the hierarchy. Expect these top-level docs to evolve as that happens.
Adds
docs/architecture.mdto each of the three main crates (objectstore-service,objectstore-server,objectstore-types) and wires them in as crate-level rustdoc viainclude_str!. This uses the same pattern as the Rust client crate's README and requires zero CI/infrastructure changes — the existingcargo docbuild and GitHub Pages deploy pick these up automatically.objectstore-service — the primary doc, covering the two-tier backend system (BigTable + GCS), the 1 MiB size threshold and streaming-based backend routing, redirect tombstones (what they solve, how each CRUD operation interacts with them), the
Backendtrait and its implementations, object identification (ObjectId/ObjectContext/scopes), and the streaming architecture.objectstore-server — server-level concerns: endpoint routes, end-to-end request flow through middleware/extractors/auth/admission control, JWT authentication with EdDSA and key rotation, figment-based layered configuration, token-bucket rate limiting with EWMA bandwidth metering, and glob-based killswitches.
objectstore-types — the shared type vocabulary:
Metadatafields and their HTTP header mapping (x-sn-*/x-snme-*prefixes), the scope system (validation rules, storage vs API path formats), expiration policies (Manual/TTL/TTI), compression, and permissions.Also updates
AGENTS.mdwith instructions to check architecture docs when making changes, and cleans up the binary crate's (main.rs) doc comment to point at the library crate instead of duplicating a stale description.