Architecture

s3BEAR is a FastAPI gateway that sits between clients and any S3-compatible storage. It authenticates every request, enforces group-based permissions, and is the single path through which objects leave your buckets.

System overview

For large uploads the browser sends parts directly to S3-compatible storage via presigned PUT URLs (the dashed line); the backend only signs URLs and finalizes the manifest. This removes the double-bandwidth cost and the FastAPI request-size limit.

Request flow: authenticated image preview

A private-bucket image rendered in the browser, gated by the user's JWT.

An expiring public URL you can hand straight to a multimodal LLM — the bucket stays private.

The planes

Client — the React 18 SPA (Ant Design + Zustand), plus non-browser consumers: LLM provider APIs fetching share URLs, and external systems (CMS, partners) using public token links.
s3BEAR backend (FastAPI) — middleware (CORS, security headers, rate limiting), authentication (JWT HS256 for local + MSAL for Entra), the API v1 routers, the permission engine (glob patterns unioned across a user's groups), and an APScheduler worker for scheduled cleanup.
Data plane — S3-compatible storage holds the objects; PostgreSQL holds users, groups, permissions, cleanup policies, audit records, share links, and webhook state.

Multi-provider routing

s3BEAR can front several S3-compatible backends at once. Each backend is registered as a Storage Provider; every bucket is mapped to one provider, and each operation is routed to the backend that owns the bucket.

API surface

Every endpoint is under /api/v1, and interactive OpenAPI docs are served at http://<backend>/docs (Swagger UI) and http://<backend>/redoc.

Router	Responsibility
`auth`	Login (local + Entra), token refresh, callback, current user
`tokens`	Personal access token (PAT) create / list / revoke
`buckets`	Bucket CRUD, browsing, quotas, tags
`objects`	Listing, deletion, copy / move, bulk copy / move
`upload`	Multipart init / complete / abort, simple upload, presigned download
`images`	Authenticated image proxy with optional on-the-fly transforms
`share` + `public`	Expiring / revocable tokenized links + unauthenticated serving
`policies`	Cleanup policy CRUD and manual runs
`webhooks`	Webhook endpoint CRUD, delivery log, and test delivery (admin)
`users` / `groups`	User & group management, permission assignment, Entra import
`providers`	Storage provider CRUD, default selection, connection test
`settings`	Runtime settings (auth toggles, Azure, storage, quotas)
`audit`	Audit-log queries (filtering + pagination)

See the full API Surface for endpoint-level detail.