Built for the AI era: a production-ready TypeScript modular monolith
with guardrails for robot coworkers.
Every new project starts the same way. You need auth, multi-tenancy,
file uploads, notifications, emails, i18n, a web app, a mobile app,
tests, observability… and three weeks later you're still wiring
boilerplate instead of building the thing that actually matters.
So I built the starter I always wished existed: a production-grade
modular monolith in TypeScript — one repo, one deployable, zero
premature microservices — with all the boring-but-critical stuff
already done. It's open source and free: fork it, change it, make it
yours → https://github.com/ihssmaheel-dev/modular-monolith-starter.
Here's the tour. 🎢
AI made it possible to build a working app in a weekend. That's amazing —
but it's also where the trouble starts. Once real users, real data, and
real money arrive, so do the questions nobody planned for:
Speed without structure becomes pain. Every time.
This starter exists so you can have both: move fast on day one, and
still sleep well on day one thousand.
Big words, simple meaning:
auth, notes,
files, notifications…) is a strict module with walls around it.
Modules never touch each other's database tables. They talk through
clean commands, queries, and events — and CI blocks you if you cheat.
Simple to start, safe to scale — easy for a new developer (or an AI
agent) to grasp in an afternoon, and solid when the team grows to twenty.
Each domain module follows CQRS: thin controllers,
single-responsibility commands and queries, pure domain entities, and
Drizzle repositories. Application code never throws — it returns
neverthrow Results. Boring? Yes. The kind of boring that sleeps
through the night? Also yes.
Already wired behind those modules:
/api/docs
notes:create,
team:invite…), ownership checks, tenant and department predicates,
enforced via decorators and servicesx-request-id flows through
logs, error envelopes, and traces, so a user report maps to the
exact request in secondsAccept-Language negotiation, the
same keys consumed by web and mobile, and CI parity checks so no
language ever falls behind
The web app (SSR on srvx, file-based routes, dark mode, EN/ES/FR out of
the box) and the Expo mobile app (SecureStore auth, push notifications,
deep links, offline-tolerant queries) consume the same Zod contracts as
the API. Change a schema, and TypeScript yells at every layer that
disagrees. API drift becomes a compile error instead of a 2 a.m. mystery.
Features already living in both clients: auth flows, notes CRUD with
attachments, user management, tenant invitations, notification center
with preferences and live updates, GDPR export and erasure, avatar +
file uploads (presigned S3 URLs via local MinIO), toasts, paginated
data tables, and empty//error states that don't lie to users.
The notes feature doubles as the reference slice: a complete,
production-shaped example — contracts, module, permissions,
translations, tests, web and mobile UI — that new developers read
first and copy when building their own features.
And when it's time to make it yours: change one theme file, run one
command, and the whole product — web, mobile, even emails — wears
your brand.
Backend
| Stack | Why |
|---|---|
| NestJS 11 + Fastify 5 | Modules and DI that mirror the monolith; Fastify for raw speed |
| PostgreSQL 16 | JSON, full-text search, RLS, rock-solid transactions |
| Drizzle | SQL you can read, types you can trust, migrations you control |
| Redis 7 + BullMQ | Queues, retries, digests, and scheduled work that survives restarts |
| Zod 4 + oRPC | One contract language, end to end — drift is a compile error |
| neverthrow | Errors as values, not hidden GOTO statements |
| Argon2 | Modern password hashing, not legacy bcrypt defaults |
| Pino + OpenTelemetry + prom-client | Structured logs, traces, and metrics without extra wiring |
| Nodemailer / Resend + React Email | Transactional mail with failover and real templates |
| Piscina + NestJS Schedule | CPU-heavy work off the event loop; cron without a sidecar |
| WebSockets + SSE | Live updates for browsers and phones alike |
Frontend
| Stack | Why |
|---|---|
| TanStack Start + React 19 | File-based routes and SSR without framework magic taking over — explicit, portable, and easy for AI tools to reason about. No lock-in, no deploy surprises |
| TanStack Query + Zustand 5 | Server state with caching; client state without boilerplate |
| Tailwind 4 + shadcn + Base UI | Utility styling plus accessible primitives, themed by tokens |
| react-hook-form + zodResolver | Forms validated by the same schemas as the API |
| react-i18next + date-fns | Every string and date localized, no hardcoding |
| Vitest + Playwright | Fast unit tests plus real browser journeys |
| srvx + nginx | Lean SSR server in front of a production-grade proxy |
Mobile
| Stack | Why |
|---|---|
| Expo 57 + expo-router | Real native apps, file-based routes like the web |
| NativeWind + Tailwind 3 | Same design tokens, native rendering |
| SecureStore + expo-notifications | Hardware-backed secrets; push that actually arrives |
| Same api-client + contracts | One API language across web, mobile, and server |
Platform
| Stack | Why |
|---|---|
| Turborepo + pnpm 10 + TypeScript 6 | Fast monorepo builds, one lockfile, strict types everywhere |
| Docker + MinIO + Mailpit + pgAdmin | Prod-like local infra: S3, inbox, and DB GUI included |
| Prometheus + Loki + Jaeger + Grafana | Metrics, logs, and traces locally before you need them in prod |
| Husky + commitlint + Changesets | Clean commits and versioned releases by default |
| GitHub Actions CI/CD | Typecheck, lint, tests, architecture rules — enforced, not suggested |
Nothing trendy-for-trendy's-sake. Everything chosen to make the next
five years easier, not just the next five minutes.
pnpm bootstrap → deps, env, Docker services, migrations, build.
Then pnpm dev. That's it. (An optional idempotent seed creates
your first admin.)pnpm project:init rebrands the whole starter — name, slug, app
titles, bundle IDs — so your fork stops looking like a template in
minutes, with a dry-run plan before it touches anything.pnpm generate:feature <module> <feature> scaffolds a full vertical
slice: contracts, backend module, API client, web + mobile UI. A new
feature stops being a two-day wiring exercise.pnpm rules:check enforces architecture as code: file placement, no
stray fetch, locale parity across languages, co-located tests for
every data module. The rules bite — I know, they've bitten me._FILE mounts, traces and logs wired from the start.
Here's the part I'm most excited about. The repo has an
ai_instructions/ folder — mandatory, machine-readable architecture
laws: locked stack, where every file belongs, how errors, i18n, and
tests work. Combined with small single-responsibility files and
end-to-end types, AI assistants stop hallucinating random patterns and
start writing code that fits the codebase on the first try. It turned my
own workflow from "review every line suspiciously" into "review, nod,
merge." The feature generator plus strict contracts plus enforced rules
basically function as guardrails for robot coworkers.
Last week I needed a full feature with API, web UI, mobile UI,
permissions, translations in three languages, and tests. Old me: two
days. With this starter: scaffold the slice, fill in the business logic,
run the gate (typecheck, lint, test:unit, rules:check,
format:check, build), commit. The checklist does the worrying.
An honest note: this is an active, early-stage project. Mobile component
tests are now in place, coverage keeps ratcheting, docs keep growing —
and next up is a Python-based intelligence layer, so AI features live in
a dedicated service beside the NestJS API. There will still be rough
edges and bugs we haven't met. But everything you need to start
a serious project today is already here and wired.
git clone https://github.com/ihssmaheel-dev/modular-monolith-starter.git
cd modular-monolith-starter
pnpm bootstrap
pnpm dev
That's the whole install. If it helps you, a star on GitHub is the cheapest way to say thanks — and it helps other developers find it too. ⭐
If you try it and something breaks, confuses you, or just smells wrong —
please open an issue on GitHub
or drop it in the comments. Feature requests doubly welcome. The fastest
way to make a starter great is people actually using it and complaining
loudly. 🙂
Happy building — and may your monolith stay modular.