OpenBucket — Implementation White Paper
Status: implementation plan (v1). This document specifies how OpenBucket is built, in enough detail that a senior engineer can implement directly from it. It is the operational sibling of ARCHITECTURE.md (the what) and supersedes BACKEND-DESIGN.md (the summary-level how) at the level of code.
. Backend Architecture & Bootstrap
This section specifies the structural backbone of the OpenBucket backend: how the single Node process boots, how one Nest application multiplexes three traffic types onto port 9000, and which scaffolding pieces every downstream subsystem can assume is already in place. Subsystem internals — S3 wire handling [see §3], persistence and the blob store [see §2], streaming and background ticks [see §4], the frontend [see §5] — are deliberately out of scope here. What is in scope is everything they hang off.
. S3 Wire Protocol & SigV4 Authentication
This section specifies the S3 surface of OpenBucket end-to-end: how requests are
. Persistence & Storage Layer
This section specifies the durable substrate beneath OpenBucket: the SQLite-backed metadata store, the path-mirrored blob store, and the discipline that keeps the two consistent across crashes. Everything here is single-process, single-host, single-volume. There is no distributed locking, no replication, no quorum — just one Node process, one event loop, one filesystem, one SQLite file, and a small set of rules that make atomic writes possible.
. Streaming I/O, Concurrency & Background Work
This section is the implementation layer between the HTTP server (handled by the backend-architect agent) and the persistence layer (handled by the persistence agent). It owns the byte plumbing for the S3 object hot path — PUT, GET, Range, multipart — plus the in-process scheduler that drives lifecycle, multipart cleanup, trash purge, and orphan scans.
. Admin API, Frontend, Auth Flow & Delivery
This section specifies the JSON admin API that lives at /api/admin/, the Angular SPA that lives at /admin/, the authentication flow that ties them together, and the build pipeline that produces the single Docker image carrying both. The S3 wire protocol (everything else on port 9000) is owned by the S3 agent and only referenced where its boundary touches admin code.