🏗️ NestJS Clean Architecture CRUD Generator

Stop writing boilerplate. Generate production-grade, strictly-typed NestJS modules following Clean Architecture, Domain-Driven Design (DDD), and CQRS from a single YAML file.

Define your entity, run one command, and get a fully structured module with domain logic, CQRS handlers, TypeORM persistence, DTO validation, Swagger documentation, and REST controllers.

✨ Features

📥 Installation

Install globally using pipx (recommended for CLI tools) or pip:

pipx install nestjs-clean-gen
# or
pip install nestjs-clean-gen

---

## 🚀 Quick Start

### 1. Define your entity in YAML

```yaml
# modules/comment.yml
module: comments
parent: posts                       # Marks this as an aggregate child of 'posts'

entity:
  name: Comment
  table: comments
  fields:
    - name: text
      type: string
      sortable: true                # Allow sorting by this field
    - name: postId
      type: uuid
      filterable: true              # Allow filtering by this field
    - name: authorId
      type: uuid
      filterable: true

relations:
  # Aggregate parent (must be cascade + non-nullable)
  - name: post
    type: many-to-one
    target: Post
    targetModule: posts
    foreignKey: postId
    nullable: false
    onDelete: cascade

  # Standard association
  - name: author
    type: many-to-one
    target: User
    targetModule: users
    foreignKey: authorId
    nullable: false
    onDelete: restrict

operations:
  - create
  - list
  - get
  - update
  - delete

2. Generate

# Generate a single module
python -m generator.structure.cli modules/comment.yml --src src/

# Bulk generate an entire folder
python -m generator.structure.cli modules/ --src src/ --force

3. Enjoy your API 🎉

📖 YAML Configuration Reference

Field Types & List Options

Note: id, createdAt, and updatedAt are managed automatically and are sortable by default.

Relationships

many-to-one (Owning side - holds the FK)

- name: author
  type: many-to-one
  target: User
  targetModule: users
  foreignKey: authorId
  nullable: false
  onDelete: restrict # restrict | cascade | set-null | no-action

one-to-many (Inverse side)

- name: comments
  type: one-to-many
  target: Comment
  targetModule: comments
  mappedBy: author # Must match the child's many-to-one relation name

one-to-one (Owning side - FK is marked UNIQUE)

- name: profile
  type: one-to-one
  target: Profile
  targetModule: profiles
  foreignKey: profileId
  nullable: true
  onDelete: set-null

many-to-many (Junction table)

- name: tags
  type: many-to-many
  target: Tag
  targetModule: tags
  joinTable: post_tags
  joinColumn: post_id
  inverseJoinColumn: tag_id

💻 CLI Usage

python -m generator.structure.cli <path> [options]

Arguments:

• <path>: Path to a single .yml file, or a directory for bulk generation.

Options:

🗂️ The Module Manifest

Every successful generation upserts an entry into .generator.manifest.json at the project root.

Commit this file to Git. It serves as the team-visible inventory of everything the generator has produced, preventing modules from "popping out of nowhere" and enabling future cross-module validation.

🧠 Generator Architecture

The generator is a modular Python package. Templates (.tpl files) are edited directly, and the Python code handles parsing, validation, and rendering.

generator/
├── structure/
│   ├── cli.py                 # Entry point (single + bulk)
│   ├── config_loader.py       # YAML loading + aggregate validation
│   ├── generator.py           # Orchestrates file writing
│   ├── context.py             # Builds the template context
│   ├── output_mapper.py       # Template → output path mapping
│   ├── manifest.py            # .generator.manifest.json upsert
│   ├── app_module_updater.py  # Idempotent app.module.ts registration
│   ├── fields/                # Field builder package
│   │   ├── normalization.py   #   normalize fields/relations
│   │   ├── types.py           #   ts_type, typeorm_type
│   │   ├── domain.py          #   entity/command/handler builders
│   │   ├── dto.py             #   DTO + validator + swagger builders
│   │   ├── orm.py             #   ORM columns + imports
│   │   ├── mapping.py         #   domain ↔ ORM field mapping
│   │   └── registry.py        #   build_field_context orchestrator
│   └── relations/             # Relation builders
│       ├── many_to_one.py
│       ├── one_to_many.py
│       ├── one_to_one.py
│       ├── many_to_many.py
│       └── registry.py        # relation dispatcher
└── templates/                 # .tpl template sources (edit these directly!)

🗺️ Roadmap

• v1: Clean Architecture CRUD, CQRS, TypeORM, 4 Relation Types.
• v2: Aggregates, Nested Reads, Manifest, Bulk Generation, Idempotent Registration.
• v3: Pagination, Whitelisted Filtering, Sorting.

📄 License

This project is licensed under the AGPL-3.0 License.

Enterprise / Commercial Use: If you wish to use this generator in proprietary, closed-source products without the AGPL open-source obligations, a commercial license is available. Please contact the maintainer for details.

Built to eliminate boilerplate so you can focus on your domain.