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
- TypeScript & JavaScript: Choose your preferred language during setup
- 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

$3

``bash
npm install ucg@latest
`

$3

Get the latest features and improvements with comprehensive Swagger documentation:

`bash
npm install ucg@beta
`

$3

`bash
npm install ucg@1.2.1-beta.1
`

$3

| Version | Features | Database Support | TypeScript | Swagger Docs |
| -------------- | -------------------------------------------------- | ---------------------------------- | ---------- | ------------ |
| 1.2.1-beta.1 | 🔥 Latest - TypeScript CRUD fix + Complete Swagger | PostgreSQL, MySQL, SQLite, MongoDB | ✅ Full | ✅ Complete |
| 1.2.1-beta.7 | Complete Swagger documentation | PostgreSQL, MySQL, SQLite, MongoDB | ❌ | ✅ Complete |
| 1.2.1-beta.6 | Previous beta | PostgreSQL, MySQL, SQLite, MongoDB | ❌ | ⚠️ Basic |
| 1.2.0 | Stable release | PostgreSQL, MySQL, SQLite, MongoDB | ❌ | ❌ Limited |

$3

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

🎯 Quick Start

$3

`bash


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
`

$3

`bash


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

$3

#### ucg init

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

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

#### ucg quick-setup

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

`bash
npx ucg quick-setup [--json]
`

$3

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:

$3

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

$3

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

$3

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

$3

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

$3

| Database | Introspection | CRUD Generation | Swagger Docs | Relationships | Migrations |
| ---------- | ------------- | --------------- | ------------ | ------------- | ---------- |
| PostgreSQL | ✅ | ✅ | ✅ | ✅ | ✅ |
| MySQL | ✅ | ✅ | ✅ | ✅ | ✅ |
| SQLite | ✅ | ✅ | ✅ | ✅ | ✅ |
| MongoDB | ✅ | ✅ | ✅ | ✅ | ⚠️ |

$3

#### PostgreSQL

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

#### MySQL

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

#### SQLite

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

#### MongoDB

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

$3

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.

$3

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

🚦 API Generation & Swagger Documentation

$3

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)
`

$3

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

$3

`yaml


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"
`

$3

- 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

📘 TypeScript Support

UCG now supports TypeScript code generation! Choose your preferred language during setup and UCG will generate fully typed code.

$3

During setup (CLI or Web Dashboard), you'll be prompted to select:

- JavaScript - Traditional ES6+ JavaScript
- TypeScript - Fully typed TypeScript with interfaces

$3

When TypeScript is selected, UCG generates:

`typescript
// user.controller.ts
import { Request, Response } from "express";
import { UserService } from "../services/user.service";

export class UserController {
private userService: UserService;

constructor() {
this.userService = new UserService();
}

async getAll(req: Request, res: Response): Promise {
// Type-safe implementation
}
}

// user.service.ts
import { PrismaClient, User } from "@prisma/client";

export class UserService {
private prisma: PrismaClient;

constructor() {
this.prisma = new PrismaClient();
}

async findAll(page: number = 1, limit: number = 10): Promise {
// Type-safe queries
}
}
`

$3

- ✅ Full Type Safety: All generated code uses proper TypeScript types
- ✅ Express Types: Request, Response, and middleware types
- ✅ ORM Types: Prisma Client types, Sequelize model types
- ✅ Interface Definitions: Custom interfaces for DTOs and responses
- ✅ Generics Support: Type-safe generic implementations
- ✅ Auto-Configuration: Automatic tsconfig.json generation
- ✅ Dependency Management: Auto-installs TypeScript and @types packages

$3

UCG automatically creates a tsconfig.json when TypeScript is selected:

`json
{
"compilerOptions": {
"target": "ES2020",
"module": "commonjs",
"lib": ["ES2020"],
"outDir": "./dist",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"resolveJsonModule": true
},
"include": ["src/*/"],
"exclude": ["node_modules", "dist"]
}
`

$3

You can switch between JavaScript and TypeScript at any time:

1. Via Web Dashboard: Go to Settings → Language Selection
2. Via CLI: Run npx ucg init again and choose a different language
3. Manual: Update .ucg/config.json and set "language": "typescript" or "language": "javascript"

$3

TypeScript code generation works seamlessly with Swagger documentation:

- All types are properly documented in OpenAPI schemas
- Request/response examples include TypeScript interfaces
- Type-safe API endpoints with full documentation

$3

TypeScript files (.ts) cannot be directly executed by Node.js. You have several options:

#### Option 1: Using ts-node (Recommended for Development)

`bash


Install ts-node

npm install --save-dev ts-node @types/node

Run your server

npx ts-node server.js

Or add to package.json scripts:

{
"scripts": {
"dev": "ts-node server.js",
"start": "node dist/server.js"
}
}
`

#### Option 2: Using tsx (Fastest)

`bash


Install tsx (faster than ts-node)

npm install --save-dev tsx

Run your server

npx tsx server.js

Or add to package.json:

{
"scripts": {
"dev": "tsx server.js",
"start": "tsx server.js"
}
}
`

#### Option 3: Compile to JavaScript

`bash


Compile TypeScript

npx tsc

Run compiled JavaScript

node dist/server.js

Add build script to package.json:

{
"scripts": {
"build": "tsc",
"start": "node dist/server.js",
"dev": "tsc --watch"
}
}
`

$3

#### Error: Cannot find module './src/routes/xxx.routes.js'

This means UCG generated .ts files, but your code is trying to require .js files.

Solution 1: Regenerate Index Route

`bash


Update UCG to latest version

npm update ucg

Delete old index file

rm src/routes/index.js

Regenerate any CRUD (this will create correct index.ts)

Visit /ucg/generate/crud and regenerate

`

Solution 2: Use ts-node or tsx

`bash
npm install --save-dev tsx
npx tsx server.js
`

#### Mixing TypeScript Routes with JavaScript Server

If you have a JavaScript server.js but TypeScript routes:

`javascript
// server.js (JavaScript)
const express = require("express");
const app = express();

// Use require.resolve to handle .ts files with ts-node
if (require.resolve("./src/routes/index.ts")) {
const routes = require("./src/routes/index.ts");
app.use("/api", routes.default || routes);
}

// Then run with: npx ts-node server.js
`

Or convert your server to TypeScript:

`typescript
// server.ts (TypeScript)
import express from "express";
import routes from "./src/routes/index";

const app = express();
app.use("/api", routes);

// Run with: npx tsx server.ts
`

$3

1. Always use a TypeScript runner (ts-node, tsx) or compile before running
2. Keep tsconfig.json in sync with your project structure
3. Install type definitions for all dependencies: npm install --save-dev @types/express @types/node
4. Use ESM imports in TypeScript for better type support
5. Compile for production to avoid runtime overhead

🧪 Testing & Validation

$3

`bash


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
`

$3

UCG generates unit tests for all generated code:

`bash


Test generated code in your project


npm test # Run tests for generated models/controllers
`

$3

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

$3

Before publishing, test the package:

`bash


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

`

$3

Test with multiple databases using Docker:

`bash


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

$3

`
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
`

$3

`bash


Clone and setup

git clone
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

$3

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

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

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

$3

`javascript
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

$3

- ✅ 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

$3

#### 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

$3

#### 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

$3

- 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:

$3

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

$3

`bash


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
`

$3

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:

`javascript
// 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
`javascript
// Add to test-swagger-documentation.js
// Add real database test cases
// Validate generated code works
`

$3

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

$3

- 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

$3

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

$3

- 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

$3

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

$3

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

$3

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

$3

- 📦 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!