🛒 Product marketplace¶

Multi-tenant sales platform Mercado Livre / Shopee style, no external integrations. The point is to exercise tempest-fastapi-sdk in a realistic scenario — auth, multi-tenant, RBAC, idempotency, auditable stock, orders with a state machine, real-time messaging (SSE + Web Push) for status and notifications, MinIO uploads, transactional email.

Project pages¶

Page	What's there
Business rules	The domain written as prose — who can do what, under which conditions. Read first.
Domain model	UML class + ER diagrams, every entity explained (attributes, invariants, relationships).
Critical flows	Sequence diagrams covering signup, member invite, product creation, checkout, shipment. Order and Invitation state machines.
Endpoint map	Table of the whole REST API with method + path + auth + payload + status.

Project setup (5 min)¶

# 1. Scaffold via SDK
tempest new marketplace --extras auth,admin,upload,cache,email,minio,queue,tasks,metrics,prometheus,http,webpush

# 2. Boot the infra
cd marketplace
docker compose up -d

# 3. Configure env
cp .env.example .env
uv sync

# 4. Migrations (create the schema, including the users table)
uv run tempest db revision -m "init"
uv run tempest db upgrade

# 5. Bootstrap the first admin so /admin login works
uv run tempest user create --email admin@local --password admin-pass-12 --admin

# 6. Run
uv run python main.py

When the service boots you have:

REST API at http://localhost:8000
Swagger docs at http://localhost:8000/docs
SDK admin panel at http://localhost:8000/admin
MinIO console at http://localhost:9001 (minioadmin/minioadmin)
RabbitMQ UI at http://localhost:15672 (guest/guest)
MailHog UI at http://localhost:8025

Local-development credentials only

The logins and passwords above (minioadmin/minioadmin, guest/guest, the admin-pass-12 admin) are local-development defaults. Never deploy with them: rotate or replace every one with strong secrets before any shared or production environment.

SDK stack exercised¶

Need	SDK primitive
Public signup + login + password reset	`UserAuthService` + `make_auth_router` (signup / activate / login / password-reset ready since v0.31.0) + `BaseUserModel` + `BaseUserTokenModel`
Access-token refresh via JWT pair	`JWTUtils` + `make_jwt_user_dependency`
Multi-tenant membership	`BaseRepository[T]`, `make_role_dependency`, `make_permission_dependency`
Member invitation	`EmailUtils.render_template` + `generate_opaque_token`/`hash_opaque_token`
Variants + versioned prices	`BaseModel` + `AuditMixin` + SQLAlchemy 2.0 async relationships
Append-only stock with bulk seed	`BaseModel` (movement) + `BaseRepository.bulk_create_values` / `bulk_upsert` (v0.28+)
Non-duplicating checkout	`IdempotencyMiddleware` + `RedisIdempotencyStore`
Upload body-size limit	`BodySizeLimitMiddleware` (v0.28+)
Product images	`UploadUtils` + `MinIOUploadStorage` + presigned URLs
Real-time order status (app open)	`SSEBroker` — per-user channel (`str(user.id)`); `broker.response(channel)` builds the `StreamingResponse`
Notification with app closed (background)	`WebPushDispatcher` + `WebPushSubscriptionService` + `make_web_push_router` (`[webpush]` extra)
One domain event on two channels (foreground + background)	Custom `NotificationService` fanning out SSE + Web Push with the same payload
Async notifications	`AsyncTaskBrokerManager` (TaskIQ) + `AsyncBrokerManager` (FastStream)
Public catalog cache	`AsyncRedisManager`, `@cached`
Oncall metrics	`PrometheusMiddleware` + `make_prometheus_router` (v0.28+) and `MetricsUtils`
Social OAuth (Google / GitHub)	`GoogleOAuthClient` / `GitHubOAuthClient` / `OIDCProvider` (v0.29+)
Safe server-rendered forms	`CSRFMiddleware` (v0.29+)
Outbound calls to external services	`HTTPClient` (v0.28+) with retry + circuit-breaker
Standardized errors	`AppException` hierarchy + `register_exception_handlers`
Per-level logs + `/logs`	`configure_logging(log_dir=…)` + `make_logs_router`

Suggested structure¶

marketplace/
├── main.py
├── docker-compose.yaml
├── pyproject.toml
├── alembic/
└── src/
    ├── api/
    │   ├── app.py
    │   ├── routers/
    │   │   ├── auth.py            # signup + login + refresh
    │   │   ├── organizations.py   # CRUD org + members
    │   │   ├── invitations.py     # invite / accept / revoke
    │   │   ├── catalog.py         # public navigation
    │   │   ├── products.py        # product + variant CRUD (org-only)
    │   │   ├── stock.py           # in / out / adjust
    │   │   ├── cart.py            # buyer cart
    │   │   ├── orders.py          # checkout + status
    │   │   ├── reviews.py         # post-delivery reviews
    │   │   ├── notifications.py   # GET /notifications/stream (SSE)
    │   │   └── push.py            # make_web_push_router (subscriptions)
    │   └── dependencies/
    │       ├── auth.py            # current_user, require_org_role
    │       └── controllers.py
    ├── controllers/               # cross-service orchestration
    ├── services/                  # domain logic
    │   └── notification.py        # NotificationService (fan-out SSE + Web Push)
    ├── schemas/                   # Pydantic DTOs
    ├── core/                      # settings + exceptions + constants
    ├── db/
    │   ├── models/                # ORM (includes push_subscription.py)
    │   └── repositories/          # queries
    ├── queue/                     # FastStream consumers
    ├── tasks/                     # TaskIQ tasks
    └── utils/

Recommended implementation order¶

Auth — UserModel(BaseUserModel) + UserTokenModel(BaseUserTokenModel) + wire UserAuthService + make_auth_router. Five endpoints ready: /auth/signup, /auth/activate/{token}, /auth/login, /auth/password-reset/request, /auth/password-reset/confirm. (Covers: abstract model concretization, bundled flow, JWT pair, Jinja2 templates.) See Auth flow recipe ».
Organizations + members — Organization + Membership with the 2-orgs-per-user / 10-members-per-org guard. (Covers: domain invariants, role-based access.)
Invitations — Invitation with opaque token, Jinja2 email, 7-day expiry. (Covers: transactional email.)
Catalog + products — Product + ProductVariant + PriceHistory. (Covers: 1-N relationships, soft-delete.)
Stock — StockMovement (append-only) + balance derived via view or aggregate query. (Covers: auditing, transactions.)
Cart + checkout — Cart + Order + OrderItem with idempotency. (Covers: state machine, idempotency.)
Real-time messaging (SSE + Web Push) — a NotificationService fans each domain event (order paid/shipped, invite, new review) out across two channels with the same payload: SSEBroker for the buyer with the app open, and Web Push (VAPID) for devices with the app closed. (Covers: SSE, Web Push.) SSE is core; Web Push needs uv add "tempest-fastapi-sdk[webpush]"; multi-worker SSE needs [cache]. See SSE recipe » and Web Push recipe ».
Product images — upload via UploadUtils + MinIOUploadStorage + listing with presigned URL. (Covers: storage.)
Async notifications — TaskIQ sending emails + RabbitMQ publishing events to projections / reports. (Covers: queues, tasks.)
Metrics + admin — Prometheus endpoint + /admin listing entities. (Covers: observability, SDK admin.)

Each step ships one complete vertical slice — one feature end-to-end before adding the next.