Skip to content

docs: Add crate-level architecture documentation#304

Merged
jan-auer merged 4 commits intomainfrom
docs/architecture
Feb 16, 2026
Merged

docs: Add crate-level architecture documentation#304
jan-auer merged 4 commits intomainfrom
docs/architecture

Conversation

@jan-auer
Copy link
Copy Markdown
Member

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.md to each of the three main crates (objectstore-service, objectstore-server, objectstore-types) and wires them in as crate-level rustdoc via include_str!. This uses the same pattern as the Rust client crate's README and requires zero CI/infrastructure changes — the existing cargo doc build 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 Backend trait 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: Metadata fields 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.md with 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.

@jan-auer jan-auer marked this pull request as ready for review February 16, 2026 11:58
@jan-auer jan-auer requested a review from a team as a code owner February 16, 2026 11:58
* main:
  feat(docs): Add styled landing page for GitHub Pages (#305)
  ref(types): Move tombstone + custom-time out of Metadata header methods (#303)
  fix(server): Validate metadata headers, strip internal fields (#302)
Reflect that is_redirect_tombstone is no longer part of the shared
from_headers/to_headers methods after #303.
@github-actions
Copy link
Copy Markdown

Semver Impact of This PR

🟢 Patch (bug fixes)

📋 Changelog Preview

This is how your changes will appear in the changelog.
Entries from this PR are highlighted with a left border (blockquote style).


New Features ✨

  • (types) Add origin as built-in metadata field by jan-auer in #292

Documentation 📚

  • (clients) Restructure Rust and Python client READMEs by jan-auer in #294
  • Add crate-level architecture documentation by jan-auer in #304

Internal Changes 🔧

  • (types) Move tombstone + custom-time out of Metadata header methods by jan-auer in #303

🤖 This preview updates automatically when you update the PR.

@jan-auer jan-auer merged commit 4c29ffd into main Feb 16, 2026
21 checks passed
@jan-auer jan-auer deleted the docs/architecture branch February 16, 2026 13:10
jan-auer added a commit that referenced this pull request Feb 16, 2026
…y-parsing

* origin/main:
  docs: Add crate-level architecture documentation (#304)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants