Architecture Overview

This document describes the internal architecture and design patterns of the Newgate framework.

Overview

Newgate is a lightweight, multi-format backend framework built on Node.js's native HTTP module. It provides:

Express-like routing with parameter and wildcard support
Automatic content-type detection and parsing
Middleware system with global and route-level support
Enhanced response helpers for multiple formats
Error handling with custom middleware
Graceful shutdown with cleanup hooks

The framework is designed to be minimal yet extensible, allowing developers to handle multiple data formats without external dependencies for routing or middleware.

Core Components

1. App (`src/core/app.js`)

The main application class that orchestrates the framework.

Responsibilities:

Route registration (GET, POST, PUT, DELETE, PATCH)
Global middleware management
CORS configuration
Shutdown hook management
Server lifecycle (listen, shutdown)

Key Methods:

get/post/put/delete/patch(path, ...handlers) - Register routes
use(middleware) - Register middleware

2. Router (`src/core/router.js`)

The Router handles URL matching and handler dispatching.

Stores routes in a structured format.
Supports parameterized routes (/users/:id).
Supports wildcard routes (/files/*).
Handles HTTP methods (GET, POST, PUT, DELETE, etc.).

3. Middleware Engine

Newgate uses a middleware stack similar to Connect/Express.

Global Middleware: Runs for every request.
Path-Specific Middleware: Runs for requests matching a path prefix.
Route-Specific Middleware: Runs for specific routes.
Error Middleware: Handles errors propagated via next(err).

4. Parsers (`src/parsers/`)

The parsing system is modular. It inspects the Content-Type header and delegates to the appropriate parser.

json.js: Handles application/json.
csv.js: Handles text/csv.
xml.js: Handles application/xml.
yaml.js: Handles application/x-yaml.
formdata.js: Handles multipart/form-data.
binary.js: Handles application/octet-stream.

5. Response Enhancer (`src/response/enhance.js`)

The enhanceResponse function adds helper methods to the native ServerResponse object.

res.json(data)
res.csv(data)
res.xml(data)
res.status(code)
res.send(data)

Request Flow

graph TD
    A[Incoming Request] --> B[Enhancement]
    B --> C[Format Detector]
    C --> D{Content-Type?}
    D -- JSON --> E[JSON Parser]
    D -- CSV --> F[CSV Parser]
    D -- XML --> G[XML Parser]
    D -- Other --> H[Other Parsers]
    E --> I[Middleware Stack]
    F --> I
    G --> I
    H --> I
    I --> J[Router Matching]
    J --> K[Handler Execution]
    K --> L[Response Helper]
    L --> M[Outgoing Response]

Incoming Request: HTTP server receives a request.
Enhancement: req and res objects are enhanced with Newgate properties and methods.
Body Parsing: The body is parsed based on Content-Type.
Middleware Execution: Global and path-specific middleware are executed in order.
Route Matching: The router finds a matching route handler.
Handler Execution: The route handler is executed.
Response: The handler sends a response using one of the helper methods.

Module Structure

newgatejs/
├── bin/
│   └── newgatejs.js          # CLI entry point
├── src/
│   ├── core/
│   │   ├── app.js      # Main App class
│   │   ├── router.js   # Routing logic
│   │   └── server.js   # HTTP server wrapper
│   ├── middleware/
│   │   └── index.js    # Built-in middleware
│   ├── parsers/
│   │   ├── index.js    # Parser dispatcher
│   │   ├── json.js
│   │   ├── csv.js
│   │   └── ...
│   ├── response/
│   │   └── enhance.js  # Response helpers
│   └── utils/
│       └── logger.js   # Logger utility
├── tests/              # Unit and integration tests
├── docs/               # Documentation
└── package.json

Extensibility

Newgate is designed to be extensible.

Custom Parsers: Can be added by modifying the parser dispatcher (future feature: plugin system).
Custom Middleware: Standard middleware signature (req, res, next) allows easy integration of custom logic.