create-odoo-app

A production-grade npm project generator that scaffolds full-stack monorepo applications built with Next.js (App Router), Fastify, PostgreSQL (Drizzle ORM), Redis, S3-compatible Object Storage (MinIO), Prometheus/Grafana Observability, and an Identity, Authentication & IAM Authorization System.

---

1. Quick Start

Create a new application with a single command:

npx create-odoo-app@latest my-awesome-app

Then navigate into your project and initialize your local environment:

cd my-awesome-app
pnpm setup
pnpm dev

---

2. CLI Usage & Options

npx create-odoo-app@latest <project-name> [options]
npx create-odoo-app@latest . [options]

Options

Flag	Description
--skip-install	Skip automatic dependency installation with pnpm
--skip-git	Skip initializing a new Git repository
--with-infra	Opt in to running docker compose up -d after dependencies are installed. Automatically skipped when --skip-install is passed. If Docker is missing or the daemon isn't running, scaffolding still succeeds and a warning is printed instead.
-h, --help	Display CLI help message
-v, --version	Display generator package version

The target directory must be empty (a lone .git directory is fine). Scaffolding never overwrites existing files, including when generating into ..

Workspaces, access control, and email

Every app is multi-tenant. Signing up creates a workspace and makes you its root user; you then invite people from Access control (/iam), which has its own sign-in at /iam/login. Users, roles, groups and policies are private to their workspace; the platform ships a few read-only system roles and policies that every workspace can use.

Sign-up verifies the email address with a one-time code. Password reset and invitations are emailed links that work once. Set RESEND_API_KEY and RESEND_FROM to send real mail. With no key, development prints each message (code or link) in the API log and the sign-up form shows the code, so the whole flow works with no provider account; production refuses to send rather than drop mail silently.

The INITIAL_ROOT_EMAIL / INITIAL_ROOT_PASSWORD account lives in a seeded default workspace so a fresh install has somewhere to sign in.

Generated Secrets

Each scaffolded project gets its own SESSION_SECRET and INITIAL_ROOT_PASSWORD, written to .env and printed once at the end of the run. Save the root password — it is hashed at seed time and cannot be recovered afterwards.

The infrastructure credentials in .env (DATABASE_PASSWORD, S3_ACCESS_KEY, S3_SECRET_KEY, REDIS_PASSWORD) are still local development defaults. The API refuses to start with NODE_ENV=production while any of them remain, and reports exactly which ones to change.

---

3. Architecture & Monorepo Structure

my-awesome-app/
├── apps/
│   ├── web/               # Next.js (App Router) + Tailwind CSS + shadcn/ui + TanStack Query + Auth/IAM UI
│   └── api/               # Fastify + Zod validation + OpenAPI / Swagger + Prometheus metrics + Auth/IAM Gateway
│
├── packages/
│   ├── auth/              # Password hashing (scrypt), session management (PostgreSQL + Redis), cookie helpers
│   ├── iam/               # Permission catalog, policy evaluation engine (Explicit Deny, :self ownership), route guards
│   ├── config/            # Developer configuration surface (app-config, auth-config, iam-config, feature-config)
│   ├── db/                # PostgreSQL client, Drizzle ORM schemas (System, Auth, IAM), migrations, seeds
│   ├── openapi/           # OpenAPI 3.0 specification metadata, tag taxonomy, and schema utilities
│   ├── shared/            # Reusable Redis (ioredis) & S3/MinIO (@aws-sdk/client-s3) clients
│   └── validation/        # Runtime validation schemas (Auth, IAM, pagination, UUID, HTTP error models)
│
├── skills/                # Agent-native reference skills (architecture, security, validation, database, etc.)
│
├── infrastructure/
│   └── docker/
│       ├── prometheus/    # Prometheus scrape configurations
│       └── grafana/       # Grafana datasource and dashboard provisioning
│
├── scripts/               # Cross-platform setup, smoke test, and health check scripts
├── docker-compose.yml     # Local infrastructure (PostgreSQL, Redis, MinIO, Prometheus, Grafana)
├── AGENTS.md              # Coding Agent & Developer Operating Manual
├── CHANGELOG.md           # Release history and Keep a Changelog documentation
├── .env.example           # Environment template with local defaults
└── package.json           # Monorepo root configuration

---

4. Developer Configuration Surface (packages/config)

The generated project exposes a configuration layer in packages/config/src/:

• app-config.ts: Application constants, metadata, pagination limits.
• auth-config.ts: Authentication behavior (registrationEnabled, sessionTtlSeconds, cookieName, minPasswordLength, maxLoginAttempts, lockoutSeconds, loginAttemptWindowSeconds). Every value here is enforced at runtime — registrationEnabled: false genuinely closes /auth/signup, and maxLoginAttempts drives a real per-email lockout.
• iam-config.ts: Declarative domain roles, groups, default policies, and baseline role-policy assignments so developers do not need to edit raw database records or authorization engine internals.
• feature-config.ts: Optional infrastructure feature toggles (enableSwagger, enableMetrics, enableStorage, enableRedis, enableEmail).

---

5. Agent Skills Architecture & Discovery (skills/*)

The project provides 14 reusable Agent Skills aligned with the Agent Skills open standard, cataloged in the machine-readable registry skills/index.yaml:

• skills/architecture/SKILL.md: Monorepo structure, package boundaries, layering rules.
• skills/authentication/SKILL.md: Session lifecycle, scrypt hashing, cookies, auth events.
• skills/authorization/SKILL.md: Policy evaluation, explicit deny precedence, :self ownership.
• skills/database/SKILL.md: Drizzle schemas, migrations, relations, deterministic seeds.
• skills/api/SKILL.md: Fastify route conventions, Zod validation, error responses.
• skills/frontend/SKILL.md: Next.js App Router, TanStack Query, AuthContext.
• skills/security/SKILL.md: Inviolable security rules (never trust client input, server guards).
• skills/validation/SKILL.md: Input validation rules, bounds, dates, pagination.
• skills/testing/SKILL.md: Testing doctrine, testing pyramid, AAA standard, adversarial tests.
• skills/storage/SKILL.md: MinIO/S3 StorageService abstractions.
• skills/email/SKILL.md: Transactional email provider integration.
• skills/realtime/SKILL.md: Redis Pub/Sub notification events.
• skills/observability/SKILL.md: Prometheus metrics, Grafana dashboards, health probes.
• skills/dependencies/SKILL.md: Monorepo dependency inventory, safe upgrades, lockfile integrity.

Validate, list, inspect, and package skills at any time:

pnpm skills:list      # List all 14 canonical skills with descriptions
pnpm skills:show <n>  # Display metadata and content for a skill
pnpm skills:check     # Validate Agent Skills registry, frontmatter, and links
pnpm skills:lint      # Structural markdown and frontmatter linter
pnpm skills:pack      # Package skills into deterministic ZIP archives in dist/skills/
pnpm skills:export    # Export standalone clean skill directories in dist/skills/

---

6. Local Service Endpoints

Service	URL	Description
Frontend Web App	http://localhost:3000	Next.js App Router UI
Access Control Console	http://localhost:3000/iam	Users, roles, groups and policies for your workspace (own sign-in at /iam/login)
Backend API Gateway	http://localhost:3001	Fastify HTTP Gateway
OpenAPI Documentation	http://localhost:3001/api/docs	Interactive Swagger UI
OpenAPI Raw Spec	http://localhost:3001/api/openapi.json	OpenAPI 3.0 JSON Specification
Prometheus Metrics	http://localhost:3001/metrics	Prometheus metrics endpoint
Grafana Dashboards	http://localhost:3002	admin / admin (or anonymous viewer)
MinIO S3 Console	http://localhost:9001	minioadmin / minioadmin

---

7. Monorepo & Quality Commands

Command	Description
pnpm dev	Run Next.js (apps/web) and Fastify (apps/api) concurrently
pnpm dev:api	Run Fastify API in watch mode (apps/api)
pnpm dev:web	Run Next.js in development mode (apps/web)
pnpm build	Compile all workspace packages, applications, and CLI binary
pnpm test	Run complete Vitest test suite across all packages
pnpm test:security	Run dedicated IAM & authentication security tests
pnpm test:coverage	Run Vitest test suite with v8 code coverage analysis
pnpm test:smoke	Run generator smoke test in a temporary directory
pnpm test:dogfood	Execute full unpacked generator dogfooding test
pnpm audit:security	Scan workspace and git history for credentials and machine paths
pnpm audit:deps	Fail on any known vulnerability in production dependencies
pnpm deps:check	Audit direct external dependencies inventory
pnpm skills:check	Validate Agent Skills registry, frontmatter, and links
pnpm skills:lint	Run structural linter across all skill files
pnpm skills:pack	Package skills into deterministic ZIP archives
pnpm verify	Run full local quality gate (skills + lint + typecheck + test + smoke + build)
pnpm verify:release	Execute pre-release packaging, package audit, and unpacked generator test
pnpm release:check	Canonical pre-release verification checklist command
pnpm typecheck	Run strict TypeScript verification across all packages + CLI
pnpm lint	Run ESLint across all packages (zero warnings tolerated)
pnpm setup	Cross-platform idempotent setup and database seeding
pnpm db:migrate	Apply pending Drizzle PostgreSQL migrations
pnpm db:seed	Seed database (default workspace, its ROOT user, and baseline IAM)
pnpm design:check	Fail on literal colours, emoji, gradients and micro type in the web app
pnpm db:studio	Launch Drizzle Studio database GUI
pnpm infra:up	Start Docker Compose infrastructure
pnpm infra:down	Stop Docker Compose infrastructure
pnpm infra:reset	Stop infrastructure and purge all Docker volume data
pnpm health	Execute end-to-end infrastructure health check script

---

8. Release Engineering, CI/CD & Publishing

Automated CI/CD Pipeline

• Continuous Integration (.github/workflows/ci.yml): Runs on pull requests and pushes to main. Tests on Ubuntu and Windows across Node.js 22.x with full quality gates: dependency vulnerability audit, ESLint, strict typecheck, tests with coverage thresholds, generator smoke test, and a production build. A separate Linux job runs migrations and the seed script against real PostgreSQL and Redis service containers.
• Release Automation (.github/workflows/release.yml): Automatically triggers on Git tags (v*.*.*) or manual trigger. Builds, audits package contents for leaks, publishes to npm with --access public --provenance, and generates a GitHub Release.

Semantic Versioning Policy

• patch (e.g. 1.0.1): Bug fixes, security patches, documentation updates.
• minor (e.g. 1.1.0): Backward-compatible additions to the generator, CLI options, or template packages.
• major (e.g. 2.0.0): Breaking CLI argument changes, major architectural changes to generated templates.

Pre-Release Verification

Before publishing or tagging a release, run:

pnpm release:check

This builds all packages, packages the .tgz artifact via npm pack, scans the tarball contents to guarantee zero leaked secrets or local machine paths, unpacks into a clean temporary directory, and runs the generator from the unpacked distribution to verify the generated application.

---

9. Community, Security & Contributing

• Contributing Guide: Instructions for submitting bug reports, features, and pull requests.
• Code of Conduct: Community participation guidelines (Contributor Covenant v2.1).
• Security Policy: Instructions for responsibly disclosing security vulnerabilities.
• License: MIT License.