UCG (Universal CRUD Generator)

A powerful, database-first CRUD generator for Node.js applications. UCG provides an interactive CLI and web dashboard to generate models, controllers, services, and API endpoints for your database tables with comprehensive Swagger/OpenAPI documentation.

🚀 Features

• Database-First Approach: Introspect existing databases to generate code
• Multiple Database Support: PostgreSQL, MySQL, SQLite, MongoDB
• Multiple ORM Support: Prisma, Sequelize, Mongoose adapters
• Comprehensive Swagger Documentation: Auto-generated OpenAPI specs with examples
• Web Dashboard: Interactive UI for code generation served from node_modules
• CLI Tools: ucg init and ucg quick-setup commands
• Pluggable Architecture: Easy to add new databases and ORMs
• Modern UI: Clean, responsive dashboard with preview capabilities
• No File Pollution: Everything served from the plugin, minimal host project changes

📦 Installation & Downloads

Latest Release

npm install ucg@latest

Beta Version (Recommended)

Get the latest features and improvements with comprehensive Swagger documentation:

npm install ucg@beta

Development Version

npm install ucg@1.2.1-beta.7

Download Summary

NPM Distribution Tags

• latest - Stable release
• beta - Beta releases with new features
• alpha - Development releases

🎯 Quick Start

Option 1: Add to Existing Project

# Install in your existing Node.js project
npm install ucg

# Initialize UCG (adds routes to your app.js/server.js)
npx ucg init

# Start your application and visit /ucg/setup
npm start

Option 2: Create New Project

# Create a new project with UCG pre-configured
npx ucg quick-setup

# Follow the prompts, then:
cd your-project-name
npm install
npm start

# Visit http://localhost:3000/ucg/setup

🛠️ Usage

CLI Commands

ucg init

Adds UCG to an existing Node.js project by mounting the router.

npx ucg init [--json]  # --json for machine-readable output

ucg quick-setup

Creates a new Node.js project with UCG pre-configured.

npx ucg quick-setup [--json]

Dashboard URLs

After running ucg init or ucg quick-setup, these URLs will be available:

• /ucg/setup - First-time configuration wizard
• /ucg/login - Dashboard login
• /ucg/dashboard - Main dashboard with table overview
• /ucg/generate/model - Model generator
• /ucg/generate/crud - CRUD generator
• /ucg/api-docs - Auto-generated API documentation

🗄️ Database Support

UCG supports multiple databases with comprehensive adapters:

PostgreSQL ✅

• Prisma: Full introspection, model generation, CRUD operations, Swagger docs
• Sequelize: Table structure detection, model/controller generation, Swagger docs
• Mongoose: Mock adapter (demonstrates architecture)

MySQL ✅

• Prisma: Full introspection, model generation, CRUD operations, Swagger docs
• Sequelize: Table structure detection, model/controller generation
• TypeORM: Coming soon

SQLite ✅

• Prisma: Full introspection, model generation, CRUD operations, Swagger docs
• Sequelize: Table structure detection, model/controller generation
• Better-SQLite3: Coming soon

MongoDB ✅

• Prisma: Full document introspection, schema generation, CRUD operations, Swagger docs
• Mongoose: Native MongoDB adapter with full ODM support
• Native Driver: Coming soon

Database Features Comparison

Connection Examples

PostgreSQL

{
  "database": "postgresql",
  "orm": "prisma",
  "credentials": {
    "host": "localhost",
    "port": 5432,
    "database": "myapp",
    "user": "postgres",
    "password": "password"
  }
}

MySQL

{
  "database": "mysql",
  "orm": "prisma",
  "credentials": {
    "host": "localhost",
    "port": 3306,
    "database": "myapp",
    "user": "root",
    "password": "password"
  }
}

SQLite

{
  "database": "sqlite",
  "orm": "prisma",
  "credentials": {
    "database": "./data/app.db"
  }
}

MongoDB

{
  "database": "mongodb",
  "orm": "prisma",
  "credentials": {
    "host": "localhost",
    "port": 27017,
    "database": "myapp",
    "user": "admin",
    "password": "password"
  }
}

Extensible Architecture

The database-first folder structure makes it easy to add new databases:

src/databases/
├── postgresql/          # PostgreSQL adapters
│   ├── prisma/         # Prisma adapter
│   ├── sequelize/      # Sequelize adapter
│   └── mongoose/       # Mock adapter
├── mysql/              # MySQL adapters
│   ├── prisma/         # Prisma adapter
│   └── sequelize/      # Sequelize adapter
├── sqlite/             # SQLite adapters
│   ├── prisma/         # Prisma adapter
│   └── sequelize/      # Sequelize adapter
└── mongodb/            # MongoDB adapters
    ├── prisma/         # Prisma adapter
    └── mongoose/       # Mongoose adapter

🎨 Generated Code Structure

UCG generates clean, production-ready code:

your-project/
├── src/
│   ├── controllers/     # Express controllers with full CRUD
│   ├── services/        # Business logic layer
│   ├── routes/          # Express routes with middleware
│   ├── models/          # ORM models (Prisma/Sequelize/etc)
│   ├── validation/      # Input validation middleware
│   └── tests/           # Unit tests for generated code

🔧 Configuration

UCG stores its configuration in node_modules/ucg/.ucg/config.json - no files are created in your project root.

Example Configuration

{
  "database": "postgresql",
  "orm": "prisma",
  "credentials": {
    "host": "localhost",
    "port": 5432,
    "database": "myapp",
    "user": "postgres",
    "tablePrefix": "app_"
  },
  "user": {
    "email": "admin@example.com"
  }
}

🚦 API Generation & Swagger Documentation

Generated Endpoints

For each model, UCG generates RESTful endpoints with comprehensive Swagger documentation:

GET    /models          # List with pagination (clean - no filter examples)
GET    /models/:id      # Get by ID
POST   /models          # Create new (with request/response examples)
PUT    /models/:id      # Update (with request/response examples)
DELETE /models/:id      # Delete (with response examples)

Swagger Documentation Features

UCG generates comprehensive OpenAPI 3.0 specifications with:

✅ Clean GET Operations

• Pagination parameters only
• No cluttered filter examples
• Clear response schemas

✅ Rich POST/PUT/DELETE Operations

• Detailed request body examples
• Response examples for all status codes
• Error handling documentation

✅ Complete Component Schemas

• Model definitions with examples
• Error response schemas
• Pagination metadata schemas

✅ Database-Specific Adaptations

• MongoDB: ObjectId format handling
• PostgreSQL/MySQL/SQLite: Integer ID autoincrement
• All databases: Consistent schema patterns

Example Generated Swagger

# Clean GET endpoint (no examples)
/users:
  get:
    summary: Get all users
    parameters:
      - name: page
        in: query
        schema:
          type: integer
      - name: limit
        in: query
        schema:
          type: integer
    responses:
      '200':
        description: Users retrieved successfully

# Rich POST endpoint (with examples)
/users:
  post:
    summary: Create a new user
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UserCreate'
          example:
            name: "John Doe"
            email: "john@example.com"
            age: 30
    responses:
      '201':
        description: User created successfully
        content:
          application/json:
            example:
              id: 1
              name: "John Doe"
              email: "john@example.com"
              age: 30
              createdAt: "2024-01-01T00:00:00Z"

API Features

• Pagination: Built-in pagination support with metadata
• Validation: Input validation middleware with error responses
• Relationships: Foreign key relationships populated automatically
• Error Handling: Consistent error responses across all endpoints
• Status Codes: Proper HTTP status codes (200, 201, 400, 404, 500)
• Content Types: JSON request/response handling

🧪 Testing & Validation

Testing the UCG Package

# Test the plugin itself
npm test

# Test Swagger documentation templates
node test-swagger-documentation.js

# Test with real databases
node real-database-test.js

# Test SQLite with rich data
node sqlite-focus-test.js

Testing Generated Code

UCG generates unit tests for all generated code:

# Test generated code in your project
npm test  # Run tests for generated models/controllers

Validation Features

UCG includes comprehensive validation testing:

✅ Template Validation

• All 6 database adapter templates validated
• Swagger documentation completeness checked
• HTTP method coverage verified

✅ Database Testing

• Real database connection testing
• CRUD operation validation
• Relationship handling verification

✅ Integration Testing

• Dashboard functionality
• API endpoint generation
• Swagger UI integration

Package Testing Workflow

Before publishing, test the package:

# Create tarball
npm pack

# Install in test project
cd /path/to/test-project
npm install /path/to/ucg-1.2.1-beta.7.tgz

# Test functionality
npx ucg init
# Visit /ucg/setup and test dashboard
# Generate models and test API endpoints

Docker Testing

Test with multiple databases using Docker:

# PostgreSQL
docker run --name test-postgres -e POSTGRES_PASSWORD=password -p 5432:5432 -d postgres:15

# MySQL
docker run --name test-mysql -e MYSQL_ROOT_PASSWORD=password -p 3306:3306 -d mysql:8

# MongoDB
docker run --name test-mongo -p 27017:27017 -d mongo:7

🎯 Development

Project Structure

ucg/
├── package.json
├── bin/ucg                    # CLI entry point
├── src/
│   ├── index.js              # Main exports
│   ├── server.js             # Standalone server (dev)
│   ├── cli/                  # CLI implementations
│   │   ├── init.js
│   │   └── quick-setup.js
│   ├── databases/            # Database-first adapters
│   │   └── postgresql/
│   │       ├── prisma/       # Prisma adapter
│   │       ├── sequelize/    # Sequelize adapter
│   │       └── mongoose/     # Mongoose adapter
│   ├── ui/                   # Web dashboard
│   │   ├── routes/           # Express routes
│   │   ├── views/            # Handlebars templates
│   │   └── static/           # CSS/JS assets
│   ├── lib/                  # Utilities
│   │   ├── config.js         # Configuration management
│   │   └── utils.js          # Helper functions
│   └── tests/                # Unit tests
├── .ucg-config.example.json  # Example configuration
└── README.md

Running in Development

# Clone and setup
git clone <repo>
cd ucg
npm install

# Run development server
npm run dev

# Run tests
npm test

# Lint code
npm run lint

🔒 Security

• Password Hashing: User passwords hashed with bcrypt
• Configuration Security: Database credentials stored in plugin directory
• Input Validation: All generated endpoints include validation
• No Secrets: No hardcoded secrets in the repository

📚 API Reference

CLI Integration

When you run ucg init, it adds these lines to your app:

// CommonJS
const ucg = require("ucg");
app.use("/ucg", ucg.router);

// ES Modules
import ucg from "ucg";
app.use("/ucg", ucg.router);

Programmatic Usage

const { router } = require("ucg");
const configManager = require("ucg/src/lib/config");
const utils = require("ucg/src/lib/utils");

// Mount UCG in your app
app.use("/admin/ucg", router);

// Access configuration
const config = await configManager.getConfig();

// Use utilities
const modelName = utils.tableNameToModelName("user_profiles");

🛣️ Roadmap & Changelog

Current Version (1.2.1-beta.7) - Latest Beta ✨

• ✅ Complete Swagger Documentation: Comprehensive OpenAPI specs for all database adapters
• ✅ Clean GET Operations: No cluttered filter examples, pagination params only
• ✅ Rich POST/PUT/DELETE: Detailed request/response examples for all mutations
• ✅ Multi-Database Support: PostgreSQL, MySQL, SQLite, MongoDB with full CRUD
• ✅ Database-Specific Handling: ObjectId for MongoDB, integer IDs for SQL databases
• ✅ Template Validation: All 6 adapters pass comprehensive testing
• ✅ Real Database Testing: Validated with Docker containers and rich test data

Previous Versions

1.2.1-beta.6

• ✅ Multi-database support foundation
• ✅ Basic Swagger documentation
• ⚠️ Limited API examples

1.2.0 - Stable Release

• ✅ PostgreSQL + Prisma/Sequelize support
• ✅ Web dashboard with modern UI
• ✅ Model and CRUD generation
• ✅ CLI tools (init, quick-setup)
• ❌ Limited Swagger documentation

Upcoming Features

Next Release (1.2.2)

• Enhanced UI: Code editor with syntax highlighting
• Bulk Operations: Generate multiple models at once
• Custom Templates: User-defined code templates
• Migration Tools: Database schema migration support

Future Enhancements (1.3.0+)

• More ORMs: TypeORM, Knex.js, DrizzleORM
• GraphQL Generation: Auto-generated GraphQL schemas and resolvers
• API Versioning: Support for multiple API versions
• Advanced Relationships: Many-to-many, polymorphic relationships
• Performance: Query optimization and caching
• Testing: Generated test suites with coverage reports

UI/UX Improvements

• Dark Mode: Theme switching capability
• Mobile Responsive: Full mobile dashboard support
• Real-time Preview: Live code preview as you configure
• Diff Viewer: Compare generated code changes
• Export/Import: Configuration backup and restore

Breaking Changes

• 1.2.0 → 1.2.1: Configuration format updated for multi-database support
• 1.1.x → 1.2.0: Dashboard routes restructured, CLI commands updated

🤝 Contributing

We welcome contributions! Here's how to get started:

Quick Start

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

# Clone and setup
git clone https://github.com/your-repo/ucg.git
cd ucg
npm install

# Run development server
npm run dev

# Run tests
npm test

# Lint code
npm run lint

# Test Swagger documentation
node test-swagger-documentation.js

# Test with real databases
node real-database-test.js

Adding New Database Support

1. Create Database Folder

   src/databases/your-database/
   ├── prisma/           # Prisma adapter
   ├── sequelize/        # Sequelize adapter
   └── your-orm/         # Your ORM adapter

2. Implement Required Interface Each adapter must implement:

   // Database connection and introspection
   async introspectTables(connectionConfig)
   async testConnection(connectionConfig)
   
   // Code generation
   async generateModelCode(table, options)
   async generateCRUD(model, options)
   
   // Swagger documentation
   generateSwaggerComponents(model)
   generateSwaggerPaths(model)

3. Add Swagger Documentation

   • Component schemas with examples
   • Clean GET operations (no filter examples)
   • Rich POST/PUT/DELETE operations with examples
   • Database-specific ID handling (ObjectId vs integer)

4. Create Tests

   // Add to test-swagger-documentation.js
   // Add real database test cases
   // Validate generated code works

Adding New ORM Support

1. Create ORM Adapter Folder

   src/databases/database-name/your-orm/
   ├── index.js          # Main adapter
   ├── introspection.js  # Database introspection
   ├── generator.js      # Code generation
   └── templates/        # Code templates
       ├── model.js
       ├── controller.js
       ├── service.js
       └── routes.js

2. Follow Template Patterns

   • Study existing adapters (Prisma, Sequelize)
   • Use consistent naming conventions
   • Include comprehensive Swagger documentation
   • Handle relationships properly

Testing Guidelines

• Write tests for new database adapters
• Test with real databases using Docker
• Validate Swagger docs are complete and correct
• Check generated code compiles and works
• Follow existing patterns for consistency

Code Style

• Use ES6+ features
• Follow existing patterns
• Add JSDoc comments for public functions
• Use meaningful variable names
• Keep functions small and focused

Documentation

• Update README.md for new features
• Add JSDoc comments for new functions
• Include examples in pull requests
• Update roadmap if adding major features

📄 License

MIT License - see LICENSE file for details.

🙋‍♂️ Support & Resources

Documentation

• 📖 Full Documentation
• 🚀 Quick Start Guide
• 🗄️ Database Setup
• 📝 API Reference

Community

• 🐛 Bug Reports
• 💡 Feature Requests
• 💬 Discussions
• 🤝 Contributing Guide

Getting Help

• 📚 Check the FAQ
• 🔍 Search existing issues
• 💬 Start a discussion
• 📧 Email: support@ucg-generator.com

Release Information

• 📦 NPM Package
• 🏷️ Releases
• 📋 Changelog

Made with ❤️ by the UCG team

🌟 Star us on GitHub if UCG helps with your projects!
🚀 Happy coding with Universal CRUD Generator!