mattstack

CLI to scaffold fullstack monorepos from battle-tested boilerplates, then generate features and audit for quality.

Skip the week of project setup — mattstack init clones production-ready backend and React boilerplates, wires them together, and hands you a running monorepo in under a minute. From there, generate crud scaffolds a complete full-stack feature in one command. The audit command keeps the codebase honest: type drift, missing tests, stub endpoints, hardcoded credentials, and CVEs — all surfaced in one pass.

---

Supported Stacks

Backends

Framework	Language	Description
django-ninja	Python	Django Ninja Extra — async REST API with Pydantic schemas
django-matt	Python	MattAPI controllers + CRUDService pattern
nestjs	TypeScript	NestJS v11 + Fastify + Drizzle ORM + JWT/OAuth/WebAuthn

Frontends

Framework	Bundler	Description
react-vite	Vite	React + TanStack Router + TanStack Query
react-vite-starter	Vite	React + React Router (simpler setup)
react-rsbuild	Rsbuild	React + TanStack Router (Rust-powered builds)
react-rsbuild-kibo	Rsbuild	React + Kibo UI (dashboards, kanban, calendars)
nextjs	Next.js	Next.js App Router + TypeScript + Tailwind

---

Quick Start

# Install
pip install mattstack

# Scaffold a project (interactive)
mattstack init

# Or with a preset
mattstack init my-app -p nestjs-fullstack
mattstack init my-app -p starter-fullstack
mattstack init my-app -p nestjs-api          # NestJS API only

# Generate a full-stack CRUD feature
cd my-app
mattstack generate crud Product --fields "name:str price:decimal"

# Audit the project
mattstack audit

---

Monorepo Structure

my-app/
├── backend/          # API (Django or NestJS) — cloned + customized
├── frontend/         # React / Next.js — cloned + wired to backend
├── ios/              # Swift iOS client (optional)
├── docker-compose.yml
├── Makefile          # setup, up, down, test, lint, format, migrate
├── .env.example
├── .pre-commit-config.yaml
└── README.md

Folder layout options

mattstack generates a monorepo with embedded subfolders — backend/ and frontend/ sit side-by-side under a shared root git repo.

my-app/           ← git root
  backend/        ← API (backend/pyproject.toml or backend/package.json)
  frontend/       ← UI  (frontend/package.json)

This is the same layout whether you use Django or NestJS on the backend, and any React variant on the frontend. The root Makefile and docker-compose glue everything together.

---

Architecture Diagram

graph TD
    A[mattstack init] --> B{Backend Framework}
    B -->|django-ninja| C[Django Ninja API<br/>Python + uv<br/>port 8000]
    B -->|django-matt| D[django-matt API<br/>Python + uv<br/>port 8000]
    B -->|nestjs| E[NestJS API<br/>TypeScript + bun<br/>port 4000]

    A --> F{Frontend Framework}
    F -->|react-vite| G[React Vite<br/>TanStack Router<br/>port 5173]
    F -->|react-rsbuild| H[React Rsbuild<br/>TanStack Router<br/>port 3000]
    F -->|nextjs| I[Next.js<br/>App Router<br/>port 3000]

    C --> J[Monorepo Root]
    D --> J
    E --> J
    G --> J
    H --> J
    I --> J

    J --> K[Makefile<br/>docker-compose.yml<br/>.env.example]
    J --> L[mattstack generate crud<br/>→ full vertical slice]
    J --> M[mattstack audit<br/>→ types, quality, CVEs]

Loading

---

Presets

Run mattstack info to list all presets. Use -p <preset> with mattstack init.

Django presets

Preset	Backend	Frontend	Celery
starter-fullstack	django-ninja	react-vite	yes
b2b-fullstack	django-ninja	react-vite	yes
starter-api	django-ninja	—	yes
b2b-api	django-ninja	—	yes
rsbuild-fullstack	django-ninja	react-rsbuild	yes
kibo-fullstack	django-ninja	react-rsbuild-kibo	yes
nextjs-fullstack	django-ninja	nextjs	yes
matt-api	django-matt	—	yes
matt-fullstack	django-matt	react-vite	yes
matt-b2b-fullstack	django-matt	react-vite	yes

NestJS presets

Preset	Backend	Frontend	Notes
nestjs-api	nestjs	—	API only, port 4000
nestjs-fullstack	nestjs	react-vite	Full monorepo
nestjs-rsbuild-fullstack	nestjs	react-rsbuild	Full monorepo
nestjs-nextjs-fullstack	nestjs	nextjs	Full monorepo

Frontend-only presets

Preset	Framework
starter-frontend	react-vite
simple-frontend	react-vite-starter
rsbuild-frontend	react-rsbuild
kibo-frontend	react-rsbuild-kibo
nextjs-frontend	nextjs

---

Generate: Full-Stack Feature in One Command

mattstack generate crud Product --fields "name:str price:decimal"

Files created (Django backend):

backend/apps/products/models/product.py      ← Django model
backend/apps/products/schemas/product.py     ← Pydantic schemas
backend/apps/products/api/product.py         ← Django Ninja router
backend/apps/products/admin/product_admin.py ← Admin registration
frontend/src/api/product.ts                  ← TypeScript API client
frontend/src/hooks/useProducts.ts            ← TanStack Query hooks
frontend/src/components/ProductList/index.tsx ← React component

Other generators: model, endpoint, component, page, hook, schema.

---

Commands Overview

mattstack init        Scaffold a new project
mattstack add         Add frontend/backend/ios to existing project
mattstack generate    Generate models, CRUDs, components, hooks
mattstack db          Database operations (migrate, seed, reset, shell)
mattstack sync        Sync types/zod/api-client between stacks
mattstack test        Run all tests (parallel supported)
mattstack lint        Lint all code (parallel supported)
mattstack fmt         Format all code
mattstack audit       Static analysis (6 domains)
mattstack dev         Start all services
mattstack deps        Dependency management (check, update, audit)
mattstack health      Service health checks
mattstack hooks       Git hooks (install, status, run)
mattstack workflow    Generate CI/CD (GitHub Actions, GitLab CI)
mattstack env         Manage .env files
mattstack rules       Generate AI assistant context files
mattstack context     Dump project context (for AI prompts)
mattstack info        Show presets, repos, frameworks
mattstack doctor      Check dev environment
mattstack version     Show version
mattstack completions Shell completions (bash/zsh/fish)

Full reference: docs/commands.md

---

NestJS Backend Details

The nestjs-boilerplate is a production-ready NestJS v11 stack:

• Runtime: Node.js + Fastify (faster than Express)
• ORM: Drizzle ORM + PostgreSQL
• Auth: JWT (access + refresh) + Google/GitHub OAuth + WebAuthn/passkeys
• Queues: Bull (Redis-based — no Celery needed)
• Email: Resend integration
• File storage: Local or S3/Cloudflare R2
• Payments: Stripe
• Observability: OpenTelemetry + Sentry
• Testing: Jest + mutation testing (Stryker)
• Tooling: Biome (lint + format), bun (package manager)

In monorepo mode, the NestJS API runs on port 4000 (to avoid conflicts with React dev servers on 3000/5173). The generated root .env and Makefile are pre-configured for this.

# NestJS monorepo workflow
mattstack init my-app -p nestjs-fullstack
cd my-app
make setup         # bun install (backend) + bun install (frontend)
make up            # Start Postgres + Redis via Docker
make backend-migrate   # Run Drizzle migrations
make backend-dev   # http://localhost:4000
make frontend-dev  # http://localhost:5173

---

Audit

Six audit domains in one pass:

mattstack audit                         # All domains
mattstack audit --domain types          # Pydantic ↔ TypeScript drift
mattstack audit --domain quality        # TODOs, stubs, hardcoded creds
mattstack audit --domain endpoints      # Missing/unimplemented endpoints
mattstack audit --domain tests          # Coverage gaps
mattstack audit --domain dependencies   # Outdated packages
mattstack audit --domain vulnerabilities # CVE scan
mattstack audit --html                  # HTML dashboard

Results are printed as a Rich table and appended to tasks/todo.md.

---

Installation

pip install mattstack

# Or install from source
git clone https://github.com/mattjaikaran/mattstack-cli
cd mattstack-cli
uv sync --extra dev
uv run mattstack --help

---

Development

uv sync --extra dev     # Install with dev deps
uv run pytest -x -q    # 784 tests
uv run ruff check src/ tests/
uv run ruff format src/ tests/

---

Source Repositories

Key	Repository
django-ninja	django-ninja-boilerplate
django-matt	django-matt-boilerplate
nestjs	nestjs-boilerplate
react-vite	react-vite-boilerplate
react-vite-starter	react-vite-starter
react-rsbuild	react-rsbuild-boilerplate
react-rsbuild-kibo	react-rsbuild-kibo-boilerplate
nextjs	nextjs-starter
swift-ios	swift-ios-starter

---

Extending

Custom repos

Override any repo URL via ~/.mattstack/config.yaml:

repos:
  nestjs: https://github.com/your-org/your-nestjs-fork.git
  react-vite: https://github.com/your-org/your-frontend.git

Custom presets

presets:
  my-api:
    description: My standard API
    project_type: backend-only
    variant: starter
    backend_framework: nestjs

Custom audit plugins

See docs/plugin-guide.md.

---

Docs

• Commands reference
• Architecture
• Ecosystem & customization
• Deployment guide
• Audit plugin guide

---

License

Apache-2.0 — see LICENSE.