{"id":45269996,"url":"https://github.com/maurolps/ratemypet","last_synced_at":"2026-04-01T19:04:22.179Z","repository":{"id":308271691,"uuid":"1029258573","full_name":"maurolps/ratemypet","owner":"maurolps","description":"Enterprise-grade Node.Js + Typescript backend. Showcasing Clean Architecture, SOLID and TDD patterns for a highly testable and scalable API.","archived":false,"fork":false,"pushed_at":"2026-03-26T21:18:50.000Z","size":1926,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-27T08:57:39.254Z","etag":null,"topics":["backend","clean-architecture","design-patterns","docker","github-actions","nodejs","postgresql","showcase","solid-principles","swagger","tdd","testcontainers","typescript","vitest"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maurolps.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-30T19:01:01.000Z","updated_at":"2026-03-26T21:18:53.000Z","dependencies_parsed_at":"2025-08-05T04:19:15.811Z","dependency_job_id":"b014ab92-ee69-4ecd-bd0a-3f104c776bfb","html_url":"https://github.com/maurolps/ratemypet","commit_stats":null,"previous_names":["maurolps/ratemypet"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/maurolps/ratemypet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maurolps%2Fratemypet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maurolps%2Fratemypet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maurolps%2Fratemypet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maurolps%2Fratemypet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maurolps","download_url":"https://codeload.github.com/maurolps/ratemypet/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maurolps%2Fratemypet/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291033,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backend","clean-architecture","design-patterns","docker","github-actions","nodejs","postgresql","showcase","solid-principles","swagger","tdd","testcontainers","typescript","vitest"],"created_at":"2026-02-21T01:00:47.037Z","updated_at":"2026-04-01T19:04:22.146Z","avatar_url":"https://github.com/maurolps.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ratemypet\n\n[![GitHub Actions CI](https://github.com/maurolps/ratemypet/actions/workflows/ci.yml/badge.svg)](https://github.com/maurolps/ratemypet/actions/workflows/ci.yml) \n[![Coverage Status](https://coveralls.io/repos/github/maurolps/ratemypet/badge.svg?branch=feature/uc001-enhance)](https://coveralls.io/github/maurolps/ratemypet?branch=feature/uc001-enhance)\n[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](https://opensource.org/licenses/MIT) \n[![SemVer](https://img.shields.io/badge/release-SemVer-blue)](https://github.com/maurolps/ratemypet/tags)\n![Status](https://img.shields.io/badge/status-Active%20Development-orange)\n\u003cbr\u003e\n![PostgreSQL](https://img.shields.io/badge/PostgreSQL-17%2B-336791?logo=postgresql)\n![Docker](https://img.shields.io/badge/Docker-ready-2496ED?logo=docker)\n[![OpenAPI](https://img.shields.io/badge/API-OpenAPI%2FSwagger-85EA2D?logo=swagger)](#)\n\nThis project showcases a **scalable and maintainable** backend implementation in **NodeJs** and **TypeScript**. Modern development best practices are enforced with **Design Patterns**, **Clean Architecture**, **TDD**, **SOLID principles**.\n\n\n ## Summary: \n- [Overview](#overview)\n- [Architecture](#architecture)\n- [Tech Stack](#tech-stack)\n- [Folder Structure](#folder-structure)\n- [Scripts](#scripts)\n- [Getting Started](#getting-started)\n- [Conventions](#conventions)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## Overview\n\nRateMyPet is a social web app where users can post photos of their pets ( dogs or cats ), and receive feedback, likes, and fun AI-generated content. See more about the **product vision**, **requirements**, **diagrams** and more in the [docs](./docs/).\n\n## Architecture \n\n*UC-002 LoginUser - Clean Architecture based | [Mermaid diagram](./docs/diagrams/backend/UC-002-login-architecture.md)*\n\u003cimg alt=\"UC002 Architecture Diagram\" src=\"https://raw.githubusercontent.com/maurolps/ratemypet/refs/heads/main/docs/assets/uc002-diagram.png\" width=\"700\" /\u003e\n\n**The layers are structured as follows:**\n\n- **Domain**: entities, contracts \n- **Application**: usecases, app business rules, services, ports, repository interfaces, custom error\n- **Presentation**: controllers, validator, DTOs, error presenter\n- **Infrastructure**: libs/frameworks adapters\n- **Main**: entrypoint, composition root (dependency injection/inversion), http server setup\n\n## Tech Stack\n\n- **Runtime:** `Nodejs` + `Typescript`\n- **Http:** `Express` (modular structure)\n- **Relational Database:** `PostgreSQL` (local or `Docker`),  versioned migrations with `dbmate`, pooling connection, singleton instance\n- **Code Quality:** `Biome` (lint/format), `Conventional Commits`, `Husky`\n- **Testing:** `Vitest`, `Supertest`(e2e), `TestContainers`(integration)\n- **API Docs:** `Swagger/OpenAPI` documentation on `/docs` endpoint\n- **Security:** Server-side validator, Authentication (`JWT`, refresh tokens, token rotation), Headers (helmet, cors), Rate-limit, Hasher, .env\n- **Error Handling:** Custom AppError class, internal error logging, error handler middleware, error codes catalog\n- **CI/CD:** `GitHub Actions` (typecheck, lint, tests, coverage)\n\n\u003e See more about the features and technical goals in the [Product Vision](./docs/product-vision.md)\n\n## Folder Structure\n\n```shell\n#v0.2.0 \n\n/src/main\n\t├── composition           # composition root, factories, dependency injection\n\t├── config                # env\n\t├── http                  # http server setup (Express)\n\t│   ├── adapters\n\t│   ├── middlewares\n\t│   └── routes\n\t└── layers                # core\n\t    ├── application\n\t    │   ├── errors\n\t    │   ├── ports\n\t    │   ├── repositories\n\t    │   └── usecases\n\t    ├── domain\n\t    │   ├── entities\n\t    │   └── usecases\n\t    ├── infra\n\t    │   ├── db\n\t    │   └── security\n\t    └── presentation\n\t        ├── contracts\n\t        ├── controllers\n\t        ├── dtos\n\t        ├── errors\n\t        ├── http\n\t        └── validation\n/tests                       # tests (unit, integration, e2e)\n```\n\n## Scripts\n\n```shell\n# from package.json v0.2.0\n\u003e npm run \u003cscript\u003e\n\n{\n\n  \"prepare\":          # set up git hooks for husky\n  \"dev\":              # run development mode with hot-reload,\n  \"start\":            # run the prod server from backend/dist\n  \"debug\":            # start with inspector and source maps\n\n  \"typecheck\":        # typeScript type checking\n  \"lint\":             # lint/format code with Biome,\n  \"lint:ci\":          # run Biome in CI mode (no writes), fail on issues\n\n  \"build\":            # bundle, clean and minify into backend/dist\n  \"build:debug\":      # inline source maps, no minify,code splitting\n\n  \"test\":             # run unit and integration test\n  \"test:watch\":       # watch mode for unit tests (TDD loop)\n  \"test:coverage\":    # run tests and generate coverage\n  \"test:staged\":      # for pre-commit\n  \"test:integration\": # run only the integration tests\n\n  \"db:up\":            # start Postgres container\n  \"db:down\":          # stop and remove the container,\n  \"db:init\":          # bring up the database and apply all migrations\n  \"db:reset\":         # remove the database with volumes (clean slate)\n  \"migrate\":          # apply pending migrations with dbmate \n  \"migrate:new\":      # create a new timestamped migration file with dbmate\n\n  \"docker:start\":     # start all dev services in the foreground\n  \"docker:up\":        # start all dev services in the background (detached)\n  \"docker:down\":      # stop and remove all dev services\n  \"docker:rebuild\":   # rebuild images  (required on deps change)\n  \n}\n\n```\n\n## Getting Started\n\n### Prerequisites\n\n- Nodejs 22+\n- Docker\n\n### Clone and install\n\n1. *Clone*\n```shell\n\n\u003e git clone https://github.com/maurolps/ratemypet.git\n\u003e cd ratemypet\n\n```\n\n2. *Install deps*\n```shell\n\u003e npm install # or npm ci to guarantee clean install\n```\n\n### Start\n\n- **Start with Docker** \n\n```shell\n\u003e npm run docker:start # or docker:up to detached mode\n\n# First run builds images, sets up Postgres with the dev user/password and do migrations.\n# App starts in dev mode with hot-reload.\n```\n\n- **Local**\n\n```shell\n# Note that docker still required for testcontainers (used in e2e and integration tests)\n\n# 1. Start the database container\n\u003e npm run db:up\n# (Or use a local Postgres install and config DATABASE_URL, check config/env.ts)\n\n# 2. Run the migrations\n\u003e npm run migrate\n\n# 3. Run the app in dev mode\n\u003e npm run dev\n\n```\n\n## Conventions\n\n### Commits and Naming\n\n- **Conventional Commits**: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`\n- **Naming**: `PascalCase` (classes/interfaces/types), `camelCase` (vars/functions)\n\n### Testing\n\n- **Files**:  `*.spec.ts` (unit), `*.test.ts` (integration), `*.e2e.test.ts` (e2e)\n- **Principles**: TDD, `AAA `Pattern (Arrange, Act, Assert), Red Green Refactor\n- **Coverage**: 100% across all layers\n\n### Branching \u0026 Versioning\n\n- **Flow**: Based on `GitHub Flow`. Create branches from `main` (e.g., `feature/uc001-domain`, `fix/uc001-db`)\n- **Pull Requests**: Always with green `CI` ( use draft to trigger CI test )\n- **SemVer Tags for milestones**: v0.1.0 (setup), v0.2.0 (UC-001), v1.0.0 (MVP)\n\n--- \n\n## Contributing\n\nI built this project to learn and share, your ideas and contributions are welcome!\n\nPlease check out [Contributing Guide](./CONTRIBUTING.md) for details on the workflow.\n\n## License\n\n[MIT](./LICENSE) - **Feel free to fork, improve, break, learn :D**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaurolps%2Fratemypet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaurolps%2Fratemypet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaurolps%2Fratemypet/lists"}