TinyShip Technical Architecture

TinyShip is a modern SaaS starter built for both global and China markets. It keeps a clean monorepo, dual-framework frontends, shared libraries, and provider-agnostic integrations. Below is a concise architecture overview distilled from the stacks page and README.

Architecture pillars

• Dual apps, one backend shape: Next.js (React) and Nuxt.js (Vue) coexist, sharing backend capabilities and patterns.
• Shared libraries (/libs): Auth, payment, database, email/SMS, i18n, UI, permissions, storage—kept framework-agnostic for reuse.
• Provider flexibility: Payments (Stripe / WeChat Pay / Creem), comms (Resend/SendGrid/SMTP, Twilio/阿里云), auth (Better-Auth + OAuth), AI (Vercel AI SDK).
• No vendor lock-in: Swap providers by configuration; unified APIs for payments and comms.
• Developer-first DX: TypeScript everywhere, Zod validation, CASL permissions, Tailwind + theme system, Cursor/AI-ready structure.

Frontend applications

• Next.js app (React): Next.js (SSR/ISR) + Tailwind CSS + shadcn/ui.
• Nuxt.js app (Vue): Nuxt + Tailwind CSS + Magic UI + shadcn/vue.
• Docs app (Fumadocs): Documentation subsite with i18n, search, and shared design tokens.

Core domains (shared across apps)

• Auth & Accounts: Better-Auth, email/phone/WeChat/OAuth, MFA-ready; account linking; session & password flows.
• Payments & Plans: Stripe + WeChat Pay + Creem, one-time and recurring, non-tier plans; subscription cycles and third-party portal launch.
• Credits System: AI-era pay-as-you-go model; fixed/dynamic consumption modes; AI model multipliers; complete transaction tracking.
• Cloud Storage: Unified storage interface; supports Alibaba Cloud OSS / AWS S3 / Cloudflare R2; file upload/download, signed URLs, metadata management.
• AI: Vercel AI SDK–based chat starter; ready to extend to embeddings, tools, or multi-modal; integrated credit consumption calculation.
• Admin Panel: Dashboard, users, orders, subscriptions; reference for RBAC and data management.
• Content & i18n: Shared translations; locale-prefixed routing; bilingual docs/pages.

Infrastructure & tooling

• Backend data: PostgreSQL + Drizzle ORM; typed schemas and migrations.
• Validation & permissions: Zod for input validation; CASL for role/permission control.
• Styling & themes: Tailwind CSS; theme classes (e.g., theme-claude), light/dark modes, gradient/chart tokens.
• Build & runtime: pnpm + turbo monorepo; Docker-ready; supports standalone or static export where applicable.
• Developer experience: Cursor-friendly layout, typed SDKs, Shiki/MDX docs, Nuxt stacks page with motion examples.

Project structure (high level)

tinyship/
  apps/
    next-app/      # React/Next.js app
    nuxt-app/      # Vue/Nuxt.js app
    docs-app/      # Fumadocs documentation site
  libs/
    auth/          # Authentication & accounts
    database/      # Database & ORM
    payment/       # Payment integration
    credits/       # Credits system
    i18n/          # Internationalization
    ui/            # UI components
    email/         # Email service
    sms/           # SMS service
    storage/       # Cloud storage (OSS/S3/R2)
    permissions/   # Permission control
    ai/            # AI integration
    ...
  docs/            # project docs & guides

Extensibility playbook

• Swap or add providers (payments, comms) via unified adapters.
• Add vertical flows: onboarding, feature gating, auditing, custom billing logic.
• Extend AI scenarios: RAG, tools, multi-model, multi-modal.
• Customize Admin actions, logs, and dashboards.
• Introduce templates on top of the existing pages without changing the core architecture.

See it live

• Tech stack tour: /stacks (Nuxt app)
• Product flows: demo.tinyship.cn
• Future plans: Roadmap