UserBaseAPI

Overview

UserBaseAPI is a FastAPI backend for account management, subscriptions and billing, and S3-backed file storage, built around a quarantine-first upload and scanning pipeline — every upload lands in a quarantine bucket first, and nothing is readable from the approved bucket until a scanner clears it. It's a second draft: a public template stripped of the customer-specific business rules and domain logic from the production system it's drawn from, currently in beta architecture verification — the goal right now is confirming the architecture holds up in a team environment.

Problem

Account auth, billing, and file upload are exactly the surfaces where an unvalidated architecture costs the most in production — an unscanned file landing in a public bucket, or a billing record built on a schema that doesn't hold up under real subscription flows, are mistakes that are expensive precisely because they're invisible until something exploits them. UserBaseAPI's answer is to make every major decision (the quarantine-first upload path, the auth token model, the strict layer stack) a checkable, numbered ADR rather than an implicit choice buried in the code — the same discipline the production system it's drawn from was built with, now applied to a public template meant to hold up on its own.

Architecture

A strict layer stack where no layer skips another:

Routes → Gates → Controllers → Services → Repositories → Models

• Accounts & auth — email/password registration and login, Google OAuth 2.0 sign-in, JWT access + refresh tokens with revocation, password reset and email verification flows, Redis sliding-window rate limiting, admin-only user management.
• Profiles, subscriptions & billing — user profiles validated against admin-defined JSON profile schemas, plans and subscriptions with invitation- and promo-code-based signup, admin-managed billing sources and billing records.
• S3 file storage, quarantine-first — every upload lands in a quarantine bucket first; nothing is readable from the approved bucket until a scanner clears it. SHA-256 content-hash deduplication so identical uploads never re-hit S3, file sharing via signed share tokens, async transfer jobs with stalled-upload recovery via cron, and a pluggable scanner — a real external scanner in production, a Mock Scanner everywhere else, wired through the same callback contract either way.
• Admin dashboard — served by FastAPI itself, plain HTML/CSS/JS with no build step: a dev dashboard (user list, S3 file browser, manual upload/scan/archive), an auth-testing UI, and a live API/DB/Redis health-check page.
• Observability — a custom span-decorated structured logging system traces every layer of a request, with no external APM required.
• Background jobs — TaskIQ (Redis-backed) for S3 transfer jobs and async log emission.

Stack: FastAPI, SQLAlchemy 2.0 (async), Postgres (or SQLite for local dev), Redis, TaskIQ, boto3 for S3, PyJWT + httpx-oauth for auth, Pydantic v2, uv for packages, ruff for lint/format, pytest for tests, and Docker Compose + Traefik for deployment.

Engineering Decisions

Every major technology and design choice in this repo has its own numbered ADR:

• ADR-0011 — Auth built on PyJWT + httpx-oauth.
• ADR-0012 — A strict layer stack (Routes → Gates → Controllers → Services → Repositories → Models) where no layer is allowed to skip another.
• ADR-0013 — A custom span-decorated structured logging system instead of an external APM.
• ADR-0014 — Quarantine-first S3 uploads: nothing is readable from the approved bucket until a scanner clears it.
• ADR-0016 — The staging, demo, and production environments share one Traefik instance and only ever run one at a time on the same box.
• ADR-0017 — Four deployment environments, a deliberate progression from cheapest-to-iterate (local) to closest-to-production (prod).
• ADR-0019 — Postgres in production, with SQLite available as a local-dev-only option.

See the project's own _userbaseapi/adrs/ directory for the full decision record, and _userbaseapi/complete/project_context_ai_refresh.md for the complete architecture and pattern rundown. Inside the UserBaseAPI ADRs walks through the process itself — the numbering and supersede/amend rules, one full record, and links to all nineteen.

Screenshots

Repository

github.com/NDutraConsulting/UserBaseAPI

BSD 3-Clause License. Author: Nikko Dutra (NDutra Consulting).