umpordez 1.0.0 → 1.0.2

package/.claude/settings.local.json

@@ -10,7 +10,11 @@
       "Bash(echo:*)",
       "WebFetch(domain:umpordez.com)",
       "Bash(curl:*)",
-      "Bash(python3:*)"
+      "Bash(python3:*)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "Bash(gh api:*)",
+      "WebFetch(domain:api.github.com)"
     ]
   }
 }

package/README.md

@@ -0,0 +1,123 @@
+# umpordez
+
+SaaS starter kit generator.
+
+---
+
+## 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
+everything wired up.
+
+**No magic, no hidden abstractions.** The generated code is yours;
+plain TypeScript, plain React, plain SQL. Read it, change it, own it.
+
+## What you get
+
+```
+server/
+  apps/api/           Admin API (Express + TypeScript)
+  apps/site-api/      Public API (Express + TypeScript)
+  apps/shared/        Shared middlewares + utilities
+  core/               Models, DB, S3, email, auth
+  console/            Task runner (migrations, seeds, custom tasks)
+  migrations/         Raw SQL migrations (Knex)
+
+ui/admin/             React SPA (Vite + shadcn/ui + Tailwind)
+ui/site/              Public site (Express + EJS + Tailwind)
+```
+
+The architecture:
+
+- **Multi-tenant**; users > accounts with role-based access
+  (admin, owner, manager, user)
+- **Multi-API**; separate Express servers sharing core logic,
+  add more as you need
+- **Cookie auth**; httpOnly JWT, 30-day expiry, no tokens
+  in localStorage
+- **S3 uploads**; multer-s3 with signed URLs (never public-read)
+- **Context DI**; fresh context per request with all models
+  instantiated, no singletons
+- **PostgreSQL**; Knex.js with raw SQL migrations, because ORMs
+  lie to you eventually :X
+
+## Install
+
+```bash
+npm install -g umpordez
+```
+
+## Usage
+
+### Create a project
+
+```bash
+umpordez
+```
+
+That's it. It asks you a few questions (name, domain, ports, colors)
+and generates everything. Then:
+
+```bash
+cd my-project
+./install.sh          # install deps
+./seed.sh             # create db + migrate + seed admin
+./dev.sh              # start all services
+```
+
+### Build for production
+
+The build system is split in two steps on purpose; compilation is
+expensive and should run on your machine, dependency installation
+needs to happen on the target machine (native bindings, OS-specific
+stuff).
+
+```bash
+# 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
+```
+
+After `build-deps`, the builds repo is ready to clone and run. Add
+your `.env`, start the services, done.
+
+### Other commands
+
+```bash
+umpordez --help       # see all commands
+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 |
+| Public site| Express + EJS + Tailwind |
+| Auth       | httpOnly JWT cookies (bcrypt + 30-day expiry) |
+| Uploads    | AWS S3 via multer-s3, signed URLs |
+| Email      | Nodemailer + HTML templates |
+
+## License
+
+MIT; do whatever you want with it.
+
+---
+
+*May the speedy force be with you.* ✌️
+
+[youtube.com/ligeiro](https://youtube.com/ligeiro)

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "umpordez",
     "type": "module",
-    "version": "1.0.0",
+    "version": "1.0.2",
     "description": "SaaS starter kit generator - multi-tenant TypeScript + React + PostgreSQL",
     "main": "cli.mjs",
     "scripts": {

package/template/README.md

@@ -0,0 +1,128 @@
+# {{PROJECT_NAME}}
+
+{{PROJECT_DESCRIPTION}}
+
+---
+
+## Quick start
+
+```bash
+./install.sh          # install all deps
+./seed.sh             # create db + migrate + seed admin user
+./dev.sh              # start everything (Ctrl+C to stop)
+```
+
+Admin panel: `http://localhost:{{ADMIN_UI_PORT}}`
+Admin API: `http://localhost:{{API_PORT}}`
+Site: `http://localhost:{{SITE_PORT}}`
+
+## How it works
+
+Multi-tenant SaaS; users can belong to multiple accounts with
+different roles. Each request gets a fresh Context with all models
+instantiated (no singletons, no global state).
+
+```
+users (global identity)
+    |
+user_in_accounts (user_id + account_id + role)
+    |
+accounts (tenant)
+    |
+[your domain entities scoped by account_id]
+```
+
+Roles: `admin` (platform-wide), `owner`, `manager`, `user`
+
+For the full architecture details, patterns and how-tos see
+[architecture.md](architecture.md). For coding standards and style
+rules see [code.md](code.md).
+
+## Project structure
+
+```
+server/
+  apps/api/           Admin API (Express, port {{API_PORT}})
+    routes/            auth, user, account, admin, files
+  apps/site-api/      Public API (Express, port {{SITE_API_PORT}})
+    routes/            public endpoints
+  apps/shared/        Shared middlewares + buildHandler
+  core/               Business logic
+    context.ts         DI container (fresh per request)
+    models/            One model per entity (extends BaseModel)
+    db.ts              Knex wrapper
+    s3.ts              S3 uploads + signed URLs
+    email.ts           Nodemailer + HTML templates
+    errors.ts          AppError hierarchy (400, 401, 403, 404, 409)
+  console/            Task runner
+    tasks/             One file per task (seed-admin, etc.)
+  migrations/         Raw SQL (Knex)
+  emails/             HTML email templates
+
+ui/admin/             React SPA (Vite, port {{ADMIN_UI_PORT}})
+  src/
+    pages/             public/, user/, admin/, account/
+    layouts/           One layout per scope
+    components/ui/     shadcn/ui (Radix + Tailwind)
+    hooks/queries/     React Query hooks per entity
+    lib/               fetchApi, query-keys, utils
+
+ui/site/              Public site (Express + EJS, port {{SITE_PORT}})
+  views/              EJS templates
+```
+
+## Commands
+
+### Server (from `server/`)
+
+```bash
+npm run dev                # admin API with hot-reload
+npm run dev:site-api       # site API with hot-reload
+npm run build              # TypeScript compilation
+npm run migrate:latest     # run pending migrations
+npm run migrate:rollback   # rollback last batch
+npm run migrate:make NAME  # create new migration
+npm run console -- --task=TASK_NAME
+```
+
+### Admin UI (from `ui/admin/`)
+
+```bash
+npm run dev           # Vite dev server
+npm run build         # production build
+npm run lint          # ESLint
+```
+
+### Site (from `ui/site/`)
+
+```bash
+npm run dev           # Express + Tailwind watcher
+npm run build         # production build
+```
+
+### Production build
+
+```bash
+umpordez build ../app ../builds       # compile + move artifacts
+umpordez build-deps ../builds         # install prod deps on target
+```
+
+## Tech stack
+
+| What        | How |
+|-------------|-----|
+| Backend     | TypeScript, Express, PostgreSQL, Knex.js, Zod |
+| Admin UI    | React 18, Vite, Tailwind, shadcn/ui, React Query v5 |
+| Public site | Express + EJS + Tailwind |
+| Auth        | httpOnly JWT cookies (bcrypt, 30-day expiry) |
+| Uploads     | AWS S3 via multer-s3, signed URLs |
+| Email       | Nodemailer + HTML templates |
+
+## Docs
+
+- [architecture.md](architecture.md) - patterns, how-tos, examples
+- [code.md](code.md) - coding standards, naming, style rules
+
+## License
+
+MIT