[opensourcedex]

nodejs-backend-architecture-typescript is a free, open source databases project written in TypeScript and released under Apache-2.0. It has 3,073 GitHub stars, 709 forks and 11 open issues, and was last pushed 3 months ago. On this registry it ranks #182 of 203 tracked projects in Databases, with 5 head-to-head comparisons available.

What is nodejs-backend-architecture-typescript?

Node.js Backend Architecture Typescript is an open-source reference implementation and learning project for building a production-ready blogging platform backend — the kind of server behind Medium or FreeCodeCamp — written in TypeScript for developers and teams who want a maintainable, highly testable Node.js API.

What it is

The project is a complete backend server built on the Node.js and Express.js ecosystem, written in TypeScript and structured around the 3RE architecture: Router, RouteHandler, ResponseHandler, ErrorHandler. It is a pure backend project, deliberately kept separate from any frontend, and it is licensed under Apache-2.0. The repository holds the latest version of the code, referred to as version 2; anyone still on the earlier codebase is pointed to the version-1 branch.

The concrete problem it solves is the one that appears when a backend is grown alongside a frontend: the two become entangled, the API cannot be reused, and scaling turns difficult. This project replaces that starting-from-a-blank-Express-app approach with a structured, feature-encapsulated layout where each component has a mutually exclusive role, so that routes, handlers, responses, and errors are handled in one consistent place. It ships as a blogging platform backend that can serve many websites and mobile apps at once, and it is designed for production use rather than demonstration.

Key capabilities

  • 3RE architecture separating Router, RouteHandler, ResponseHandler, and ErrorHandler into distinct layers.
  • Centralised error handling and centralised response handling, giving one framework for all errors and a common API response pattern.
  • MongoDB accessed through Mongoose, with Redis used as a cache for items that do not change frequently.
  • JWT authentication using an AccessToken and RefreshToken pair, alongside role-based access control.
  • TypeScript throughout, with validation handled by zod in the version 2 highlight list; Joi appears in the topic list and description.
  • Unit tests and integration tests written with Jest, with unit tests favoured and able to run without a database server.
  • Docker deployment support: a Dockerfile and Docker Compose configuration are provided, with a Docker Compose CI workflow at .github/workflows/docker_compose.yml.

Who uses it and how

  • Companies named in the README include MindOrks, AfterAcademy, and CuriousJr, with apps and websites reported at a 10+ million userbase.
  • Teams serving several surfaces at once — web apps, mobile apps, and other API services — from a single separated backend.
  • Developers learning backend architecture from the companion article and the video guide linked in the README.
  • Projects that need test suites running in CI without provisioning a database server, since unit tests are designed to work without one.
  • Self-hosters who want deployment through Docker Compose rather than manual environment setup. The repository has 3073 stars, 709 forks, and 11 open issues, with the most recent push on 2026-07-02.

Getting started

Clone the repository and run it with the included Dockerfile and Docker Compose configuration, which are intended to provide deployability without any setup or configuration. The README also points to a video guide at https://youtu.be/t7blRxqPIMs for building and running the project.

How it compares

No list of commercial products this project replaces is provided in the facts, and no comparable alternatives are named, so it stands alone in this registry. The only external products it references are Medium and FreeCodeCamp, and those are models for the blogging platform being built rather than competing tools.

When to use it — and when not to

A self-hoster must operate MongoDB, Redis, and a Docker environment, because all three are part of the stack rather than managed services. Teams looking for a turnkey hosted product, or a backend unrelated to blogging and content publishing, should look elsewhere. The main weakness is documentation depth: the README is strong on architecture rationale and light on step-by-step command and API reference, and the split between version 1 and version 2 requires care when reading older material.

project readme (upstream, from github) — read inline

Node.js Backend Architecture Typescript Project

A complete project to build a blogging platform like Medium, and FreeCodeCamp

Docker Compose CI

Note: This is the latest (version 2) of the project. If you are using version 1 then checkout the branch version-1


Project Highlights

  1. Node.js
  2. Express.js
  3. Typescript
  4. Mongoose
  5. Redis
  6. Mongodb
  7. zod
  8. Unit Tests & Integration Tests
  9. Docker
  10. JWT

About The Project

This project is designed for a production ready environment. It can handle the scale and complexity of a very demanding application. This project is being used by companies like MindOrks, AfterAcademy, and CuriousJr. Apps/Websites having 10+ million usebase.

It is suitable for Web Apps, Mobile Apps, and other API services.

About The Author

You can connect with us here:

Project Instructions

We will learn and build the backend application for a blogging platform. The main focus will be to create a maintainable and highly testable architecture.
Following are the features of this project:

  • This backend is written in Typescript: The type safety at build time and having intellisense for it in the IDE like vscode is unparalleled to productivity. I have found production bug reduced to a significant amount since most of the code vulnerabilities are identified during the build phase itself.
  • Separation of concern principle: Each component has been given a particular role. The role of the components is mutually exclusive. This makes the project easy to be unit tested.
  • Feature encapsulation: The files or components that are related to a particular feature have been grouped unless those components are required in multiple features. This enhances the ability to share code across projects.
  • Centralised Error handling: I have created a framework where all the errors are handled centrally. This reduces the ambiguity in the development when the project grows larger.
  • Centralised Response handling: Similar to Error handling we have a response handling framework. This makes it very convenient to apply a common API response pattern.
  • Mongodb is used through Mongoose: Mongodb fits very well to the node.js application. Being NoSQL, fast, and scalable makes it ideal for modern web applications.
  • Redis Memcache: I have used the redis server for caching the items which does not change frequently. It will boost the performance of our system.
  • Async execution: I have used async/await for the promises and made sure to use the non-blocking version of all the functions with few exceptions.
  • Docker compose has been configured: I have created the Dockerfile to provide the easy deployability without any setup and configurations.
  • Unit test is favored: The tests have been written to test the functions and routes without the need of the database server. Integration tests has also been done but the unit test is favored.
  • A pure backend project: I have experienced that when a backend is developed clubbed with a frontend then in the future it becomes really difficult to scale. We would want to create a separate backend project that servers many websites and mobile apps.

3RE Architecture: Router, RouteHandler, ResponseHandler, ErrorHandler


Project Outline: Blogging Platform


Request-Response Handling Schematic Diagram


Learn the concepts used in this project

How to build and run this project

vscode is the recommended editor - dark theme

Get the repo

# clone repository recursively
git clone https://github.com/afteracademy/nodejs-backend-architecture-typescript.git

Run Docker Compose

# install and start docker containers
docker-compose up --build

Run Tests

docker exec -t blogs-tester npm run test

If having any issue

  • Make sure 3000 port is not occupied else change PORT in .env file.
  • Make sure 27017 port is not occupied else change DB_PORT in .env file.
  • Make sure 6379 port is not occupied else change REDIS_PORT in .env file.

Run on the local machine

Change the following hosts in the .env and .env.test

  • DB_HOST=localhost
  • REDIS_HOST=localhost

Best way to run this project is to use the vscode Run and Debug button. Scripts are available for debugging and template generation on vscode.

  • Install node.js and npm on your local machine.
# From the root of the project executes
$ npm install

Stop the app and tester docker container

$ docker compose stop tester
$ docker compose stop app

Run the app

# production mode
$ npm start
or
# watch mode
$ npm run watch

Test

# unit and integration tests
$ npm test

API DOC

API Documentation

Learn To Deploy This API Service On Amazon EC2 - YouTube Video

YouTube Video

Learn Backend Development From Our Videos

Project Directory Structure

├── .vscode
│   ├── settings.json
│   ├── tasks.json
│   └── launch.json
├── .templates
├── src
│   ├── server.ts
│   ├── app.ts
│   ├── config.ts
│   ├── auth
│   │   ├── apikey.ts
│   │   ├── authUtils.ts
│   │   ├── authentication.ts
│   │   ├── authorization.ts
│   │   └── schema.ts
│   ├── core
│   │   ├── ApiError.ts
│   │   ├── ApiResponse.ts
│   │   ├── JWT.ts
│   │   ├── Logger.ts
│   │   └── utils.ts
│   ├── cache
│   │   ├── index.ts
│   │   ├── keys.ts
│   │   ├── query.ts
│   │   └── repository
│   │       ├── BlogCache.ts
│   │       └── BlogsCache.ts
│   ├── database
│   │   ├── index.ts
│   │   ├── model
│   │   │   ├── ApiKey.ts
│   │   │   ├── Blog.ts
│   │   │   ├── Keystore.ts
│   │   │   ├── Role.ts
│   │   │   └── User.ts
│   │   └── repository
│   │       ├── ApiKeyRepo.ts
│   │       ├── BlogRepo.ts
│   │       ├── KeystoreRepo.ts
│   │       ├── RoleRepo.ts
│   │       └── UserRepo.ts
│   ├── helpers
│   │   ├── asyncHandler.ts
│   │   ├── permission.ts
│   │   ├── role.ts
│   │   ├── security.ts
│   │   ├── utils.ts
│   │   └── validator.ts
│   ├── routes
│   │   ├── access
│   │   │   ├── credential.ts
│   │   │   ├── login.ts
│   │   │   ├── logout.ts
│   │   │   ├── schema.ts
│   │   │   ├── signup.ts
│   │   │   ├── token.ts
│   │   │   └── utils.ts
│   │   ├── blog
│   │   │   ├── editor.ts
│   │   │   ├── index.ts
│   │   │   ├── schema.ts
│   │   │   └── writer.ts
│   │   ├── blogs
│   │   │   ├── index.ts
│   │   │   └── schema.ts
│   │   ├── index.ts
│   │   └── profile
│   │       ├── sc

readme truncated — read the full docs on github

Frequently asked questions

Is nodejs-backend-architecture-typescript free to use?

nodejs-backend-architecture-typescript is open source under the Apache-2.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does nodejs-backend-architecture-typescript do?

Node.js Backend Architecture Typescript - Learn to build a backend server for production ready blogging platform like Medium and FreeCodeCamp. Main Features: Ro

What is nodejs-backend-architecture-typescript written in?

nodejs-backend-architecture-typescript is primarily written in TypeScript. Its source is publicly available at https://github.com/afteracademy/nodejs-backend-architecture-typescript, and it has 3,073 GitHub stars.