From 96c5b7898bc9deaffd3568c5fae5de58e28e03a0 Mon Sep 17 00:00:00 2001 From: Blake Bertuccelli-Booth <46652+bbertucc@users.noreply.github.com> Date: Fri, 15 May 2026 11:57:46 -0500 Subject: [PATCH] docs(storage): clarify that S3 means the S3 API, not AWS MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The architecture doc previously said "AWS S3 — current default for object storage" and pointed at a "provider-abstraction roadmap" for escaping AWS, framing it as a future improvement. That's misleading: boto3 already speaks the S3 API against any compatible backend today. Operators standing up the project outside AWS don't need to wait for a filesystem provider — they need to set AWS_ENDPOINT_URL_S3 to MinIO, Garage, Cloudflare R2, Backblaze B2, Wasabi, etc. Two narrow doc edits to reflect that: * architecture.md (Infrastructure section): rename the bullet to "S3-compatible object storage" and list the realistic options with links. Pointer to the new self-host guide for the full setup. Floci description rephrased as "S3-compatible emulator" rather than "AWS emulator" — same fact, less misleading. * src/services/storage_service.py module docstring: same clarification at the source-of-truth layer so readers of the code reach the same conclusion as readers of the docs. No code change. Concrete step toward the project's "maintained openly for any organisation" pitch landing for non-AWS operators. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/explanation/architecture.md | 4 ++-- src/services/storage_service.py | 12 +++++++++++- 2 files changed, 13 insertions(+), 3 deletions(-) diff --git a/docs/explanation/architecture.md b/docs/explanation/architecture.md index 3009882e..dcccacf6 100644 --- a/docs/explanation/architecture.md +++ b/docs/explanation/architecture.md @@ -33,8 +33,8 @@ Equalify Reflow is a monolithic Python application with background task queuing ### Infrastructure - **Redis 5.0+** - Task queues, job state, rate limiting, distributed locks -- **AWS S3** - Current default for object storage (PDFs, pipeline artefacts, results). Pluggable: the provider-abstraction roadmap (in progress) will add a local filesystem option for simpler deployments. -- **Floci** - Lightweight (~72 MB, ~26 ms startup, MIT licensed) local AWS emulator used by the default dev stack. Replaces LocalStack — same wire protocol, same port (4566). Once the filesystem storage provider lands, Floci becomes opt-in rather than required. +- **S3-compatible object storage** - PDFs, pipeline artefacts, and results live in two buckets (temp and results). The storage layer uses boto3 against the S3 API — *not* an AWS-only integration. Any service that speaks the S3 protocol works in production: AWS S3, [MinIO](https://min.io), [Garage](https://garagehq.deuxfleurs.fr/), [Cloudflare R2](https://developers.cloudflare.com/r2/), Backblaze B2, Wasabi, or [Floci](https://github.com/floci-io/floci). Point `AWS_ENDPOINT_URL_S3` at the chosen service and set `S3_PUBLIC_URL` to the public hostname used in client-facing presigned links. See [`docs/how-to/self-host.md`](../how-to/self-host.md) for the full setup. +- **Floci** - Lightweight (~72 MB, ~26 ms startup, MIT licensed) local S3-compatible emulator used by the default dev stack. Replaces LocalStack — same wire protocol, same port (4566). Production deployments swap it for any of the S3-compatible options listed above. - **Docker & Docker Compose** - Containerized services ### Monitoring & Observability diff --git a/src/services/storage_service.py b/src/services/storage_service.py index fafc9ada..c9c3a91e 100644 --- a/src/services/storage_service.py +++ b/src/services/storage_service.py @@ -1,4 +1,14 @@ -"""Storage service for S3 operations.""" +"""Object-storage service. + +Talks to any service that implements the S3 API via boto3. AWS S3 is one +option; production deployments also run against MinIO, Garage, Cloudflare +R2, Backblaze B2, Wasabi, etc. Local dev uses Floci. The choice is +controlled by ``AWS_ENDPOINT_URL_S3`` (boto3 reads it directly); this +module is endpoint-agnostic. + +The class and surrounding comments still say "S3" because that is the +name of the protocol the API speaks, not a claim that AWS is required. +""" import asyncio import json