clean-ts-api is a teaching repository, and its value is the layering rather than the survey API

It is course material, and that is the honest framing

The repository is a Clean Node API written in TypeScript, and the README states plainly that this API is part of Professor Rodrigo Manguinho's training on Udemy. The stated objective of the training is to show how to create an API with a well defined and decoupled architecture, using TDD as a working methodology, Clean Architecture to distribute responsibilities across layers, always following the SOLID principles and, whenever possible, applying design patterns to solve common problems.

That framing matters for how you read the code. A teaching repository optimises for making a concept visible. A production repository optimises for the thing being built. Where the two conflict, the teaching repository usually wins, which is why a project like this can have an unusually complete set of layers and an unusually old dependency list at the same time.

The README is also a curriculum. It lists the principles the project follows, which are the SOLID five plus Separation of Concerns, Don't Repeat Yourself, You Aren't Gonna Need It, Keep It Simple Silly, Composition Over Inheritance and Small Commits. The design patterns are Factory, Adapter, Composite, Decorator, Proxy, Dependency Injection, Abstract Server, Composition Root, Builder and Singleton. The methodologies and designs are TDD, Clean Architecture, DDD, Conventional Commits, GitFlow, Modular Design, Dependency Diagrams, Use Cases and the three continuous delivery stages.

Then it lists what the code actually contains. The Node features include API documentation with Swagger, a REST API with Express, GraphQL with Apollo Server, error logging, security with hashing, encryption and encoding, CORS, middlewares, access level on routes with Admin, User and Anonymous, deployment to Heroku, and serving static files. The GraphQL features are types, queries, mutations, resolvers, directives, scalars and plugins. The testing features are unit tests, integration tests for both the REST and GraphQL sides, test coverage, and the full set of test doubles from doubles to fakes. The MongoDB section is a list of the driver operations the code exercises, from connect and reconnect through the aggregation pipeline stages.

The licence is GPL-3.0-or-later, and the repository metadata says the same. For a project whose code people are meant to learn from and reuse, that is a meaningful constraint, and it is worth reading the `license` file at the repository root before you copy a layer into something commercial.

The requirements documents show the design being driven from the outside

The `requirements/` directory is the most instructive part of the repository and the README links to it as the API documentation.

There are six documents, each describing one API operation: Cadastro, which is registration, Login, Criar enquete for creating a survey, Listar enquetes for listing surveys, Responder enquete for answering a survey, and Resultado da enquete for the survey result. Each one is a `requirements` file with a name like `signup.md` and `add-survey.md`, and the README presents them as the APIs built in the training.

The reason this is worth reading is that it shows the direction of the design. The behaviour is specified first, as a set of use cases, and the layers are derived from them. That is the Clean Architecture argument made concrete rather than asserted, and it is the thing a reader is meant to take away.

The domain is a survey application, which is a good choice for a teaching project. It has a user, a survey, an answer and a result, it has authentication, and it has enough operations to exercise every layer without the domain logic being large enough to obscure the structure.

The `run_instruction.md` file at the repository root is the setup guide, and `readme.md` exists alongside `README.md`, which is a small sign of a repository that has been through several rounds of editing. The `public/` directory holds the static assets, and `src/` is the source of the application.

Three jest configurations separate unit from integration

The test setup is where the TDD claim is either credible or not, and the package scripts make the structure visible.

"test": "jest --passWithNoTests --runInBand --no-cache",
"test:unit": "npm test -- --watch -c jest-unit-config.js",
"test:integration": "npm test -- --watch -c jest-integration-config.js",
"test:staged": "npm test -- --findRelatedTests",
"test:ci": "npm test -- --coverage",
"test:coveralls": "npm run test:ci && coveralls < coverage/lcov.info"

There are three separate jest configuration files at the repository root, `jest.config.js`, `jest-unit-config.js` and `jest-integration-config.js`, plus `jest-mongodb-config.js`. The unit and integration suites are separated by configuration rather than by directory convention, and the integration side uses `@shelf/jest-mongodb`, which starts a real MongoDB instance for the tests rather than mocking the database.

That choice is the correct one for this project, and it is the reason the In-Memory MongoDb Server appears in the tooling list. A repository that claims Clean Architecture is making a claim about testability at the boundaries, and the boundaries are where a mock would be a lie.

`test:staged` with `--findRelatedTests` is the hook for the commit stage, paired with Husky and lint-staged, and the `prepare` script runs `husky install` so the hooks are set up on install. The `check` script runs npm-check with the update flag, which is what keeps the dependency list honest.

The `--runInBand` and `--no-cache` flags on the base test command are a choice worth understanding. Serial execution is slower but it means the integration tests, which start a database, do not fight each other over ports and memory. It is a reasonable trade for a project with this many integration tests.

The coverage path feeds Coveralls, and the README carries the coverage badge, so the coverage number is tracked rather than aspirational.

Docker Compose runs the API against MongoDB 3 on Node 12

The Compose file is small and it dates the project precisely.

services:
  mongo:
    container_name: mongo-container
    image: mongo:3
    restart: always
    volumes:
      - ./data:/data/db
    ports:
      - "27017:27017"
  api:
    container_name: api-container
    image: node:12
    working_dir: /usr/src/clean-node-api
    command: bash -c "npm install --only=prod && npm run debug"
    environment:
      - MONGO_URL=mongodb://mongo:27017/clean-node-api
    ports:
      - "5050:5050"
      - "9222:9222"
    links:
      - mongo

The API container runs the `debug` script rather than `start`, which means it starts Node with the inspector attached on port 9222, and the Compose file publishes that port so you can attach a debugger from the host. That is a teaching setup, and a useful one, since stepping through the use case layer is exactly how you would learn the structure.

The `npm install --only=prod` in the command is a little odd for a container that then runs a development build, and it reflects the age of the project rather than a considered setup. The MongoDB 3 image and the Node 12 image are the clearest signals of when this was assembled.

The application scripts match the same vintage. The build is `rimraf dist && tsc -p tsconfig-build.json`, with a separate `tsconfig-build.json` alongside the main `tsconfig.json`, and a `postbuild` that uses copyfiles to copy the public directory into `dist/static`. The debug script is `nodemon -L --watch ./dist --inspect=0.0.0.0:9222 --nolazy ./dist/main/server.js`, and the entry point is `dist/main/server.js`, which tells you the source layout uses a `main` directory for the composition root and the server bootstrap.

The `up` and `down` scripts wrap docker-compose, and the app ports are 5050 for the API and 9222 for the inspector.

The dependency list describes a full stack, not a minimal one

The library list in the README is long, and reading it tells you which techniques the project is trying to demonstrate.

The application layer is Express with Apollo Server Express and GraphQL on top, plus GraphQL ISO Date, GraphQL Scalars and GraphQL Tools for the schema work. Security is Bcrypt for hashing, JsonWebToken for tokens, and Validator for input validation. Swagger is there for the API documentation, and the README points at a hosted API documentation page.

The test tooling is Faker for data, Supertest for HTTP assertions, MockDate for time control, Apollo Server Integration Testing for the GraphQL side, and the usual Jest family. The build side has Sucrase for fast transpilation, Nodemon for reload, Rimraf for cleaning, Module-Alias for path mapping and Copyfiles for the static assets.

Two entries stand out for what they imply about the design. Module-Alias is there because the Clean Architecture layout needs path aliases so that a domain file does not reach across layers with relative paths that are three directories deep. And the in-memory MongoDB server plus the test doubles library, Faker, MockDate, and the whole family of doubles, are what make the layers testable in isolation.

The `config/` directory at the root is part of the same story. It holds the environment configuration, and the README's mention of a Composition Root among the design patterns is what the directory is for: one place where the concrete implementations are chosen and wired together, so that the rest of the code depends on interfaces.

The last push to the repository was on 2026-09-09 and it is not archived, so the project is still being touched, although with no GitHub releases the version history is in the commits. The package version is 3.0.0, and the homepage is the author's site, with the Travis CI, Coveralls and Snyk badges all still in the README.

Editorial conclusion

Adopt clean-ts-api as a reference for how to layer a Node.js API, since the domain, use case, adapter and infrastructure split is the teaching point and the requirements documents show the design being driven by behaviour. Do not adopt it as a production starting point without modernising it, because the stack is old, with MongoDB 3 and Node 12 in the Compose file. Verify first that the Node and MongoDB versions in the Compose file match what you have, that the jest configuration separates unit from integration tests the way your pipeline expects, and that the GPL-3.0 licence is compatible with the way you intend to reuse the code.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. Project website
4. README
5. rmanguinho/clean-ts-api on GitHub