archgen

A CLI tool that generates production-ready backend projects in seconds — Node.js, Python, or Go — so you can focus on building, not configuring.

Quick Start

npm install -g @kidkender/archgen

archgen create my-app

Answer a few prompts. Your project is ready in under a second.

Features

• Generate a complete backend project in under 1 second
• Opinionated architecture — clean, consistent, maintainable
• Built-in authentication, logging, error handling, and validation
• Multi-language support — Node.js and Python
• Optional Docker + docker-compose setup
• Optional testing setup with example test files
• Optional GitHub Actions CI workflow
• Optional WebSocket support with Socket.io + JWT auth
• Optional OAuth2 (Google + GitHub) via @fastify/oauth2
• Optional API documentation via Scalar + Swagger UI
• Optional Email support via SMTP (nodemailer) — send welcome, password reset, and custom emails
• Optional S3 storage (AWS S3 / R2 / MinIO) — upload, presigned URLs, delete, exists
• Optional Claude Code setup — CLAUDE.md + pre-configured skills for Claude Code agent
• Optional Cursor setup — .cursor/skills/ with pre-configured skills for Cursor agent
• Optional observability stack — OpenTelemetry traces + Prometheus /metrics + Grafana dashboard + OTel Collector (both Node.js and Python)
• Optional Sentry error tracking — injected alongside --observability
• Optional pre-commit hooks (Python) — ruff + black + mypy via .pre-commit-config.yaml
• Auto update notifier — hints when a new version is available
• Interactive CLI prompts — no flags required
• Post-scaffold addon injection with archgen add
• archgen upgrade — re-apply all addons from meta to get latest templates

Supported Stacks

| Language | Stack | |----------|-------| | Node.js | TypeScript · Fastify · Prisma · MariaDB/MySQL · Redis · JWT · Zod · Pino · Swagger | | Python | FastAPI · SQLAlchemy 2.0 · Alembic · PostgreSQL · Redis · Pydantic v2 · APScheduler | | Go | chi v5 · GORM v2 · PostgreSQL · golang-migrate · godotenv · slog · air |

Usage

Interactive mode (recommended)

archgen create my-app

With flags

archgen create my-api --language node --docker --testing --ci
archgen create my-api --language node --all           # enable all addons at once
archgen create my-service --language python --author "John Doe"
archgen create my-app --database postgresql
archgen create my-app --claude-code                   # add Claude Code setup (CLAUDE.md + skills)
archgen create my-app --cursor                        # add Cursor agent setup (.cursor/skills/)
archgen create my-app --email                         # add nodemailer SMTP support
archgen create my-app --s3                            # add AWS S3 / R2 / MinIO support
archgen create my-app --claude-code --cursor          # add both AI agent setups
archgen create my-app --observability                 # add OTel + Prometheus + Grafana
archgen create my-app --observability --sentry        # add observability + Sentry
archgen create my-app --pre-commit                    # add pre-commit hooks (Python only)
archgen create my-api --language go --module-path github.com/user/my-api  # Go project
archgen create my-api --language go --jwt --docker    # Go with JWT auth + Docker
archgen create my-app --force                         # overwrite existing directory
archgen create my-app --dry-run                       # preview files without writing
archgen create my-app --skip-git                      # skip automatic git init

Inject addons into an existing project

cd my-existing-project
archgen add docker
archgen add testing
archgen add ci
archgen add websocket       # Socket.io + JWT auth + notification helpers
archgen add oauth           # Google + GitHub OAuth2 routes
archgen add api-docs        # Scalar UI at /reference + Swagger UI at /docs
archgen add claude-code     # Claude Code setup (CLAUDE.md + .claude/skills/)
archgen add cursor          # Cursor agent setup (.cursor/skills/)
archgen add email           # nodemailer SMTP email support
archgen add s3              # AWS S3 / R2 / MinIO storage support
archgen add observability   # OTel + Prometheus + Grafana
archgen add observability --sentry  # with Sentry error tracking
archgen add pre-commit      # pre-commit hooks (Python only: ruff + black + mypy)
archgen add jwt             # JWT auth addon (Go only)
archgen add ci --dry-run    # preview changes without writing

Upgrade existing project to latest templates

cd my-existing-project
archgen upgrade             # re-apply all addons from .archgen-meta.json
archgen upgrade --dry-run   # preview what would change

Other commands

archgen list                # list available languages and addons
archgen info node           # show full stack details for a language
archgen doctor              # check that required tools are installed

Options

| Flag | Description | Default | |------|-------------|---------| | -l, --language | node or python | prompt | | --database | mysql or postgresql (Node.js only) | prompt | | --docker | Include Dockerfile + docker-compose | false | | --testing | Include testing setup | false | | --ci | Include GitHub Actions CI workflow | false | | --all | Enable docker + testing + ci at once | false | | --websocket | Include Socket.io WebSocket support | false | | --oauth | Include Google + GitHub OAuth2 | false | | --api-docs | Include Scalar + Swagger API docs | false | | --email | Include nodemailer SMTP email support | false | | --s3 | Include AWS S3 / R2 / MinIO storage | false | | --observability | Include OTel + Prometheus + Grafana stack | false | | --sentry | Include Sentry (pair with --observability) | false | | --pre-commit | Include pre-commit hooks (Python only) | false | | --jwt | Include JWT auth routes + middleware (Go only) | false | | --module-path | Go module path (e.g. github.com/user/app) | prompt | | -a, --author | Author name | Your Name | | -d, --description | Project description | — | | --force | Overwrite existing directory | false | | --dry-run | Preview files without writing | false | | --skip-git | Skip automatic git init | false |

Generated Project Structure

Node.js

my-app/
├── src/
│   ├── config/        # env, database, redis, logger
│   ├── middleware/    # auth, error handling, rate limiting
│   ├── modules/       # auth, users, health — ready to extend
│   ├── shared/        # utils, cache, exceptions, types
│   └── jobs/          # background job scheduler
├── prisma/
├── tests/
├── .env.example
├── .editorconfig
└── package.json

Python

my-api/
├── app/
│   ├── core/          # config, database, redis, logging
│   ├── middleware/    # auth, error, logging, rate limiting
│   ├── schedulers/    # background jobs with APScheduler
│   ├── schemas/       # Pydantic request/response models
│   └── routes/        # API routers
├── migrations/
├── tests/
├── .env.example
├── .editorconfig
└── pyproject.toml

Requirements

• Node.js >= 18
• git (optional — for auto git init)
• Docker (optional — for --docker addon)

License

ISC © Kidkender