umpordez

SaaS starter kit generator. Server, admin SPA, public site (i18n + SEO), mobile app — all wired up, single command.

Why?

We all know the drill; you want to build a SaaS, you spend two weeks setting up auth, multi-tenancy, file uploads, admin panels, role-based access... and then you still haven't written a single line of your actual product.

I've built this same architecture across multiple production apps (different domains, same bones). At some point I got tired of copying between repos, adapting folder names, and forgetting to update that one hardcoded port somewhere.

So I made a CLI that generates the whole thing. One command, answer a few questions, and you get a production-ready multi-tenant SaaS with server + admin + site + mobile already talking to each other.

No magic, no hidden abstractions. The generated code is yours; plain TypeScript, plain React, plain SQL, plain Expo. Read it, change it, own it.

What you get

<project>/
├── server/                   Admin API + Site API + console + DB
│                              (Express + TypeScript + PostgreSQL +
│                               Knex + Zod)
├── ui/admin/                 React SPA (Vite + shadcn/ui + Tailwind)
├── ui/site/                  Public site (Express + EJS + Tailwind +
│                              i18n with SEO best practices)
├── mobile/<slug>/            Expo + React Native + TypeScript
│                              with auth, offline SQLite, content
│                              sync, IAP, push (custom-native),
│                              Apple Health + Health Connect
├── scripts/                  All helpers in one place (mobile, deploy,
│                              version bumping, icon generation)
├── doc/index.html            HTML docs themed in your primary color
├── .claude/                  Claude Code permission allowlist
└── CLAUDE.md (× 5)           Per-app rules for AI agents

Architecture (the bones)

• Multi-tenant — users → user_in_accounts → accounts → domain entities. Roles: admin / owner / manager / user.
• Multi-API — separate Express servers sharing one core/ layer. Add more APIs by copying apps/api/.
• Hybrid auth — httpOnly JWT cookies for web, Bearer tokens for mobile, refresh-token rotation single-flighted to prevent false logouts on concurrent refresh.
• Apple Sign-In + Google OAuth pre-wired. Apple via JWKS verify (zero-dep), Google via server-side flow that keeps the client_secret out of the app bundle.
• Free-first mobile — anyone can use the app without sign-in. Auth reached via Profile or via PremiumGate's onUpgrade.
• Offline-first SQLite with USER vs SHARED table classes, cloud backup/restore via S3 (two-phase upload survives mid-failure).
• Content sync — versioned catalog + HMAC-signed presigned asset URLs cached for 55 min, server out of the streaming path.
• i18n done right — pt-BR default + en, every string via t(). Site uses URL prefixes (/ vs /en/) for SEO with full hreflang + canonical + sitemap.xml.
• Custom-native push with cold-start tap dispatch (the bit expo-notifications can't do reliably).
• Context DI — fresh Context per request, all models instantiated, no singletons, no shared state.
• Routes go through models — never knex from a route. Path aliases (#core/*, #shared/*, @/*) over relative paths.
• PostgreSQL with raw SQL migrations — because ORMs lie to you eventually.

Install

npm install -g umpordez

Usage

Create a project

umpordez

It asks what to generate first:

| Preset | Includes | |---|---| | everything | server + admin UI + site + mobile | | web-only | server + admin UI + site (no mobile) | | mobile-and-server | server + mobile (no UI) | | just-mobile | mobile only (assumes external API) |

Then a few questions (name, domain, ports, primary color, mobile bundle ID if applicable). After scaffold:

cd my-project
./install.sh           # install all node deps + seed .env files
./install.sh --native  # also expo prebuild + pod install + native
./seed.sh              # create db + run migrations + seed admin
./dev.sh               # start every service (mobile included by default)
./dev.sh --no-mobile   # skip Metro this run

Update an existing project

When the umpordez template ships fixes / new files / refactors, pull them into your project:

umpordez update <path>          # walk template + project, prompt per file
umpordez update <path> --yes    # accept all auto-updates without prompting

How it knows what's safe to auto-update: at scaffold time, the CLI writes .umpordez/manifest.json with sha256 of every file as it was generated. On update:

• File untouched since scaffold → auto-updates if template changed
• File user-edited → shows a diff and asks (y / N / d=full diff / a=accept all)
• Generated assets (icons, splash, favicon) regenerate from the manifest's stored primary color when missing

Random secrets (JWT, content HMAC) are persisted in the manifest so updates don't mint fresh ones and break sessions / signed URLs already issued by the running app.

Generate icons

The mobile preset auto-generates a branded icon set at scaffold time from your primary color + first letter of the project name. To re-run later (e.g. after dropping in a real logo PNG):

umpordez icons --primary '#02e027' --letter U --out ./assets
umpordez icons --from logo.png --primary '#02e027' --out ./assets

Outputs: icon.png, adaptive-icon.png, splash-icon.png, favicon.png, appstore.png, playstore.png.

Build for production

The build system is split in two on purpose: compilation is expensive and should run locally; dependency installation needs to happen on the target machine (native bindings, OS-specific stuff).

# Step 1: compile locally, push artifacts to builds repo
umpordez build ../app ../builds

# Step 2: on prod/staging, install production deps
umpordez build-deps ../builds

Mobile release

./scripts/bump-version.sh patch       # bumps every version-holding file atomically
./scripts/release-android.sh          # EAS local build → submit to Play (internal track)
# iOS: open ios/<slug>.xcworkspace and Archive, or use eas build

All commands

umpordez                          create a new project
umpordez create                   same
umpordez build <app> <builds>     compile for production
umpordez build-deps <builds>      install prod deps on target machine
umpordez icons [--from logo.png]  generate the mobile icon set
umpordez update <path> [--yes]    pull template changes into a project
umpordez --help                   show this help
umpordez --version                check version

Tech stack

| Layer | Tech | |---|---| | Backend | TypeScript, Express, PostgreSQL, Knex.js, Zod | | Admin UI | React 18, Vite, Tailwind, shadcn/ui (Radix), React Query v5, React Hook Form | | Public site| Express + EJS + Tailwind + i18next (with hreflang/canonical/sitemap) | | Mobile | Expo, React Native, TypeScript, expo-sqlite, react-native-iap, react-native-health, custom-native push | | Auth | httpOnly JWT cookies (web) + Bearer + refresh rotation (mobile), Apple + Google OAuth | | Uploads | AWS S3 with signed URLs | | Email | Nodemailer + HTML templates |

What changed in 1.1

The big one. v1.0.x was server + web only. v1.1 adds:

• Mobile preset — full Expo + RN app with auth, offline DB, cloud backup, content sync, IAP, push, health.
• CLI presets — pick what you want generated up front.
• umpordez update — pull template changes into existing projects without losing your custom code.
• umpordez icons — branded icon generator.
• i18n — site (URL-prefixed, SEO-best-practices) and mobile (Profile picker with country flags).
• Custom-native push with cold-start tap dispatch (Swift + Kotlin), Apple Sign-In + Google server-side OAuth.
• Per-app CLAUDE.md files + .claude/settings.json with a permission allowlist for routine commands.
• Tests scaffold in server/tests/ (KISS — node:test + tsx).
• Production hardening — TZ=UTC, fatal handlers, trust-proxy lifted from agendalize.

Existing projects pick up everything via umpordez update <path>.

License

MIT; do whatever you want with it.

May the speedy force be with you. ✌️

youtube.com/ligeiro