Express TypeScript API

A robust, production-ready Express.js API built with TypeScript following clean architecture principles and modern development practices.

✨ Features

• 🏗️ Layered Architecture - Controllers, Services, Repositories pattern for clean separation of concerns
• 🔒 Security First - Helmet, CORS, CSRF protection, and secure headers
• 📝 Type Safety - Full TypeScript support with strict configuration
• 🔍 Validation - Zod schemas for request/response validation
• 🗄️ Database - Prisma ORM with PostgreSQL support
• 📊 Logging - Winston logger with Morgan HTTP request logging
• 🔧 Developer Experience - Hot reload, ESLint, Prettier, Husky pre-commit hooks
• 🚀 Production Ready - Proper error handling, graceful shutdown, and environment configuration

🏛️ Architecture

src/
├── config/          # Configuration modules (CORS, CSRF, environment, logging, Prisma)
├── controllers/     # Request handlers and business logic coordination
├── middleware/      # Express middleware (CSRF, error handling, validation)
├── repositories/    # Data access layer (Prisma interactions)
├── routes/          # API route definitions
├── schema/          # Zod validation schemas
├── services/        # Business logic layer
├── types/           # TypeScript type definitions
└── utils/           # Utility functions and helpers

Key Design Patterns

• Repository Pattern - Abstracts data access logic
• Service Layer - Contains business logic
• Middleware Pattern - Handles cross-cutting concerns
• Factory Pattern - Configuration and dependency injection
• Error Boundary - Centralized error handling

🛠️ Tech Stack

• Runtime: Node.js
• Framework: Express.js 5.x
• Language: TypeScript
• Database: PostgreSQL with Prisma ORM
• Validation: Zod
• Security: Helmet, CORS, CSRF
• Logging: Winston + Morgan
• Code Quality: ESLint, Prettier, Husky
• Development: Nodemon, ts-node

🚀 Quick Start

Prerequisites

• Node.js 20+
• PostgreSQL database
• npm or yarn

Installation

See INSTALL.md for detailed installation instructions.

🧪 Development

Import Aliases

Use the @/ alias for clean imports:

import { userService } from '@/services';
import { corsConfig } from '@/config';
import { wrap } from '@/utils';

Code Quality

• ESLint - Enforces code style and catches potential issues
• Prettier - Code formatting
• Husky - Pre-commit hooks for quality checks
• TypeScript - Static type checking

📁 Project Structure Details

Controllers

Handle HTTP requests and coordinate between services and middleware.

Services

Contain business logic and coordinate with repositories.

Repositories

Handle data access and database operations using Prisma.

Middleware

• Error Handler - Centralized error processing
• Validation - Request/response validation with Zod
• CSRF Protection - Cross-site request forgery protection
• Security Headers - Various security middleware

Configuration

Modular configuration system with separate files for:

• CORS settings
• CSRF protection
• Environment variables
• Logger setup
• Prisma client
• Error mappings

🔒 Security

• Helmet - Sets various HTTP headers for security
• CORS - Configurable cross-origin resource sharing
• CSRF - Cross-site request forgery protection
• Input Validation - Zod schema validation
• Error Handling - No sensitive information in error responses

📊 Logging

• Winston - Structured logging with multiple levels
• Morgan - HTTP request logging
• Error Tracking - Comprehensive error logging with stack traces

📄 License

MIT License - see LICENSE file for details.