@diagramers/api

🚀 Diagramers API

A comprehensive Node.js API framework built with TypeScript, Express, MongoDB, and built-in authentication and permission management.

🎯 Quick Start

Prerequisites

• Node.js 18+
• MongoDB 6+
• npm or yarn

Installation

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# Start development server
npm run dev

Environment Setup

# Database
MONGODB_URI=mongodb://localhost:27017/diagramers
MONGODB_DB=diagramers

# JWT
JWT_SECRET=your-secret-key
JWT_EXPIRES_IN=1h

# Server
PORT=3000
NODE_ENV=development

🏗️ Project Structure

src/
├── core/                    # Core system components
│   ├── app.ts             # Application setup
│   ├── server/            # Server management
│   ├── database/          # Database connection & seeding
│   └── middleware/        # Authentication & permission middleware
├── modules/               # Business logic modules
│   ├── auth/             # Authentication module
│   ├── user/             # User management
│   └── permission/       # Permission system
├── shared/               # Shared utilities and types
│   ├── types/            # TypeScript interfaces
│   ├── utils/            # Utility functions
│   └── constants/        # System constants
└── routes/               # Route definitions

🔐 Authentication & Permissions

The API includes a comprehensive permission system:

• JWT-based authentication with multiple provider support
• Role-based access control with fine-grained permissions
• Dynamic permission middleware for route protection
• Resource-based permissions for ownership checks

📚 Documentation

For comprehensive development guides, examples, and best practices, see:

🚀 Complete Developer Guide

The developer guide covers:

• Module development from A to Z
• Database design and entity creation
• API endpoint development
• Permission system setup
• CLI commands and automation
• Testing and deployment
• Troubleshooting and best practices

🎛️ Available Scripts

Development

npm run dev              # Start development server
npm run build            # Build for production
npm run start            # Start production server

Database

npm run seed             # Seed database with sample data
npm run setup:permissions # Initialize permission system
npm run setup:admin      # Create admin user

Module Generation

npm run generate:module  # Generate new module
npm run generate:table   # Generate new database table
npm run generate:endpoint # Generate new API endpoint

Utilities

npm run lint             # Run ESLint
npm run type-check       # TypeScript type checking
npm run format           # Format code with Prettier
npm run docs             # Generate API documentation

🌐 API Endpoints

Base URL

http://localhost:3000/api

Available Endpoints

• GET /health - Health check
• POST /auth/login - User authentication
• GET /users - Get all users (requires authentication)
• POST /users - Create new user (requires authentication)

Authentication

Include JWT token in Authorization header:

Authorization: Bearer <your-jwt-token>

Request Headers

x-request-id: MODULE_ACTION_UUID (optional)
x-correlation-id: <correlation-id> (optional)

🧪 Testing

# Run permission tests
npm run test:permissions

# Run all tests
npm test

🚀 Deployment

# Build for production
npm run build

# Start production server
npm start

# Docker deployment
npm run docker:build
npm run docker:run

🔧 Configuration

Environment Variables

• NODE_ENV - Environment (development/production)
• PORT - Server port
• MONGODB_URI - MongoDB connection string
• JWT_SECRET - JWT signing secret
• JWT_EXPIRES_IN - JWT expiration time

Database Configuration

• MongoDB with Mongoose ODM
• Automatic schema management
• Built-in seeding and migration tools

📖 Examples

Creating a New Module

# Generate complete module structure
npm run generate:module -- --name=products --description="Product management"

# This creates:
# - Entity files (interfaces and schemas)
# - Service with CRUD operations
# - Controller with HTTP handlers
# - Routes with permission middleware
# - Swagger documentation

Permission Setup

# Initialize permission system
npm run setup:permissions

# Create admin user
npm run setup:admin

🆘 Support

• Documentation: Complete Developer Guide
• Issues: Create issues in the project repository
• Examples: Check existing modules in src/modules/

📄 License

This project is licensed under the MIT License.

For complete development guides and examples, see the Developer Guide