Skip to content

README.md

Latest commit

 

History

History
308 lines (235 loc) · 8.59 KB

README.md

File metadata and controls

308 lines (235 loc) · 8.59 KB

TypeScript Enterprise Nexus

Node.js Version TypeScript License MongoDB Tests PRs Welcome

A production-ready Clean Architecture foundation for enterprise TypeScript applications

TypeScript Enterprise Nexus Architecture

📚 Table of Contents

Overview

TypeScript Enterprise Nexus is a comprehensive Clean Architecture API built with TypeScript, featuring enterprise-grade capabilities including contracts to integrate with any database provider (e.g., MongoDB, Redis, PostgreSQL), to any communication protocol (e.g., HTTP, gRPC, Message), OpenAPI documentation, comprehensive monitoring, security middleware, dependency injection, and extensive testing support.

🌟 Features

  • ✨ Clean Architecture implementation with clear separation of concerns
  • 🔒 TypeScript for enhanced type safety and developer experience
  • 💉 Dependency Injection using InversifyJS
  • 🗄️ MongoDB integration with Mongoose
  • 📝 OpenAPI Documentation using Swagger
  • 🔐 Authentication & Authorization with JWT
  • 🛡️ Comprehensive Security Features
    • Helmet for HTTP headers security
    • Rate limiting
    • XSS protection
    • CORS
    • HPP (HTTP Parameter Pollution) protection
  • 📊 Monitoring & Logging
    • Express Status Monitor
    • Prometheus metrics
    • Winston logger
    • Morgan HTTP request logging
  • 🧪 Testing
    • Jest for unit and integration tests
    • Supertest for E2E testing
    • Test containers for integration tests
  • 🛠️ Development Tools
    • ESLint & Prettier
    • Husky for git hooks
    • Dependency cruiser for architecture validation
    • TypeDoc for documentation generation

📋 Prerequisites

  • Node.js >= 18.0.0
  • NPM >= 9.0.0
  • MongoDB >= 5.0
  • Docker (optional)

🚀 Quick Start

  1. Clone the repository
git clone https://github.com/yourusername/typescript-enterprise-nexus.git
cd typescript-enterprise-nexus
  1. Install dependencies
npm install
  1. Environment setup
cp .env.example .env

Edit the .env file with your configuration.

  1. Start MongoDB
# Using Docker
docker run --name mongodb -d -p 27017:27017 mongo:latest

# Or use your local MongoDB installation
  1. Run the application
# Development mode
npm run dev

# Production mode
npm run build && npm run start:prod

🏗 Project Structure

Directory Overview

  • application/: Contains application-specific business rules and use cases

    • Implements the core application logic
    • Defines interfaces for external dependencies
    • Manages application state and flow

  • enterprise/: Houses domain entities/events/dtos

    • Contains business entities and logic
    • Independent of external frameworks
    • Defines core business rules and constraints

  • infrastructure/: Implements technical capabilities and frameworks

    • Handles database operations
    • Manages external services integration
    • Provides technical implementations of interfaces
    • Contains framework-specific code

  • interface/: Handles external communication

    • Manages HTTP requests and responses
    • Implements API endpoints
    • Handles data transformation
    • Contains presentation logic

  • __tests__/: Contains all test-related files

    • Organized by test type
    • Includes test helpers and fixtures
    • Follows the same structure as source code

Key Files

  • index.ts: Application entry point
  • Application.ts: Main application class
  • types/: Global type definitions
  • utils/: Shared utility functions

Architecture Principles

  • Follows Clean Architecture principles
  • Maintains separation of concerns
  • Dependencies flow inward
  • External dependencies are isolated in infrastructure layer
  • Business logic is framework-agnostic

This structure promotes:

  • Modularity
  • Testability
  • Maintainability
  • Scalability
  • Clear separation of concerns

🛠 Available Scripts

Development

  • npm run dev - Start development server with hot-reload
  • npm run build - Build for production
  • npm run start:prod - Start production server

Testing

  • npm test - Run all tests
  • npm run test:coverage - Run tests with coverage report
  • npm run test:integration - Run integration tests
  • npm run test:e2e - Run end-to-end tests

Code Quality

  • npm run lint - Run ESLint
  • npm run lint:fix - Fix ESLint errors
  • npm run format - Format code with Prettier

Documentation

  • npm run docs:generate - Generate TypeDoc documentation
  • npm run deps:graph - Generate dependency graph

Maintenance

  • npm run security:audit - Run security audit
  • npm run deps:check - Check for unused dependencies
  • npm run fresh-install - Clean install dependencies

🔒 Environment Variables

Key environment variables required for the application:

PORT=3000
MONGODB_URL=mongodb://127.0.0.1:27017/typescript-enterprise-nexus
JWT_SECRET=your-jwt-secret
SMTP_HOST=email-server
# See .env.example for all required variables

📚 API Documentation

When the application is running, access the OpenAPI documentation at:

  • Swagger UI: http://localhost:3000/api/v1/docs

API Documentation Screenshot

🔐 Security

This project implements various security best practices:

  • JWT-based authentication
  • Rate limiting
  • HTTP Security Headers
  • XSS Protection
  • CORS Configuration
  • Parameter Pollution Protection
  • Security Audit Tools

📊 Monitoring

The application includes several monitoring endpoints:

  • /api/v1/status - Application status
  • /api/v1/metrics - Prometheus metrics
  • /api/v1/monitor - Real-time monitoring dashboard

Monitoring Dashboard

🧪 Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test adapters
npm run test:integration
npm run test:e2e

🔄 CI/CD

The project includes configurations for:

  • GitHub Actions workflows
  • Husky pre-commit hooks
  • ESLint and Prettier checks
  • Automated testing
  • Security audits

📦 Docker Support

# Build the image
docker build -t typescript-enterprise-nexus .

# Run the container
docker run -p 3000:3000 --memory=2g --cpus=2 typescript-enterprise-nexus

# Development with Docker Compose
docker-compose up

🤝 Contributing

We welcome contributions to TypeScript Enterprise Nexus! Please check out our Contributing Guide for guidelines about how to proceed.

  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

🧭 Project Roadmap

Our vision for TypeScript Enterprise Nexus includes:

  • GraphQL support
  • Microservices communication patterns
  • Event sourcing implementation
  • CQRS pattern support
  • Enhanced observability features
  • Multi-tenant architecture support
  • Expanded database adapters
  • Kubernetes deployment templates

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

👥 Support

For support, please open an issue in the GitHub repository or contact the maintainers.

🙏 Acknowledgments

  • Clean Architecture principles by Robert C. Martin
  • Express.js community
  • TypeScript team
  • All contributors and maintainers

Built with ❤️ using TypeScript and Clean Architecture principles

⭐ If you find TypeScript Enterprise Nexus useful, please consider giving it a star on GitHub! ⭐