System Blueprint

Application Architecture

This page explains how Bunship composes runtime, domain modules, and shared packages into a scalable SaaS foundation.

Read docsStart building

10+

Workspace packages

6

Core domains

3

Built-in surfaces

Request Lifecycle

From user action to business result: the pipeline below reflects how major requests are handled.

  1. 01

    Entry Surface

    A request starts in Marketing, App, or Admin routes under locale-aware Next.js App Router segments.

  2. 02

    Validation & Auth

    Session context, role checks, and schema validation are resolved before touching domain services.

  3. 03

    Domain Execution

    Pricing, orders, content, and AI generation modules execute business rules in isolated services.

  4. 04

    Data & Provider Layer

    Drizzle-powered persistence and external provider calls are coordinated with retries and limits.

  5. 05

    Feedback Loop

    The UI gets deterministic states for success, failure, and loading, including credits and billing updates.

Design Principles

  • Feature modules own business logic, shared packages own contracts.
  • Critical workflows are idempotent by design (payments, refunds, retries).
  • Runtime boundaries are explicit: UI, service, persistence, provider.
  • Every major flow ships with fallback and observable states.

Application Layers

Each layer has a strict responsibility to keep system behavior predictable as your product grows.

Experience Layer

User-facing surfaces for marketing conversion, product usage, and admin operations.

  • /Marketing pages and localized routing
  • /App dashboard and task workflows
  • /Admin console for operations and model management

Domain Layer

Business modules that govern pricing, subscriptions, content, and AI generation behavior.

  • /Order, credit, and subscription logic
  • /CMS and block distribution
  • /AI generation rules and parameter schemas

Integration Layer

Adapters for authentication, payment providers, storage, and model providers.

  • /Better Auth session integration
  • /Payment and invoice orchestration
  • /FAL / Replicate / KIE provider connectors

Data Layer

Persistent state, migrations, and shared typed access through workspace packages.

  • /Drizzle schema and migrations
  • /Typed query utilities
  • /Seed and environment-aware bootstrapping

Multi-Cloud Storage

S3 Multi-Provider Upload Architecture

Uploads are resolved through a provider factory at request time, allowing per-user provider and bucket routing within one deployment.

Supported S3-Compatible Providers

  • /Cloudflare R2
  • /AWS S3
  • /Backblaze B2 (S3)
  • /Tigris
  • /DigitalOcean Spaces
  • /MinIO
  • /Wasabi
  • /Custom (including OSS-compatible scenarios)

Core Entry Routes

App Upload

POST /api/v1/s3/upload

Resolves provider + bucket from current user context before executing upload.

Admin Upload

POST /api/v1/admin/s3/upload

Handles admin assets and operations uploads with the same provider resolution logic.

Provider Factory

apps/ship-api/src/services/upload/provider.ts

Unifies default settings, per-user overrides, and environment fallback handling.

Configuration Priority

  • 1.UPLOAD_PROVIDER_OVERRIDES (per-user override)
  • 2.UPLOAD_PROVIDER_DEFAULT (system default)
  • 3.BETTER_UPLOAD_PROVIDER (environment fallback)

Task Queue Guarantees

Generation and provider work is driven by a scheduler-aware queue that controls throughput, retries safely, and prevents duplicate financial side effects.

Throughput

Concurrency + QPS Guard

Worker slots and provider-level QPS windows are enforced together, so burst traffic cannot exceed upstream limits.

Control

Timeout + Cancellation

AbortController is propagated from queue jobs to submit/poll HTTP requests, allowing deterministic timeout and active cancel behavior.

Recovery

Retry Budget with Backoff

Transient failures use bounded retries and delay strategy, while permanent failures short-circuit to terminal state.

Finance

Refund Idempotency

Credit compensation is protected with idempotency keys to prevent duplicate refunds during retries and race conditions.

Stack Matrix

A practical map of the core stack used in production.

Runtime & Framework

Next.js 16React 19BunTurborepo

Product Foundations

Better AuthDrizzle ORMnext-intlshadcn/ui base

Business Modules

Pricing and billingOrder lifecycleCMS + blocksAI generation

Operations

Admin model controlsCredits and refundsQueue + retryProvider fallback

Quality Transparency

Backend API Coverage Report

We publish a dedicated coverage details page and summary JSON for core API chains: orders, products, subscription, webhook, and key admin routes. Public output keeps file paths redacted.

Open coverage detailsOpen summary JSON

Route

/stacks/backend-coverage

Build command

bun run coverage:backend:report

Coverage scope

orders | products | subscription | webhook | admin routes

Ready to build on this architecture?

Start with the existing foundation and adapt domains, providers, and workflows to your product.

Get startedView pricing