{"id":15745576,"url":"https://github.com/edugese/screenpulse-backend-api","last_synced_at":"2026-04-13T14:31:22.949Z","repository":{"id":213143083,"uuid":"733010588","full_name":"EduGese/ScreenPulse-backend-Api","owner":"EduGese","description":"Backend application built with Node.js and Express using TypeScript for strong and robust typing. It serves as the REST API integrated into the ScreenPulse-frontApp application.","archived":false,"fork":false,"pushed_at":"2025-11-17T20:01:51.000Z","size":20266,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"prod","last_synced_at":"2025-11-17T22:05:48.634Z","etag":null,"topics":["api-rest","backend","expressjs","mongodb","mongoose","nodejs","swagger-ui","typescript"],"latest_commit_sha":null,"homepage":"https://edugese.github.io/ScreenPulse-backend-Api/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EduGese.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2023-12-18T11:09:36.000Z","updated_at":"2025-11-17T20:01:54.000Z","dependencies_parsed_at":"2024-01-03T18:26:29.972Z","dependency_job_id":"fc719ae6-df07-46e9-8a2d-4359f88afc1a","html_url":"https://github.com/EduGese/ScreenPulse-backend-Api","commit_stats":null,"previous_names":["edugese/node-ts-mongodbatlas-api","edugese/screenpulse-backend-api"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/EduGese/ScreenPulse-backend-Api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EduGese%2FScreenPulse-backend-Api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EduGese%2FScreenPulse-backend-Api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EduGese%2FScreenPulse-backend-Api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EduGese%2FScreenPulse-backend-Api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EduGese","download_url":"https://codeload.github.com/EduGese/ScreenPulse-backend-Api/tar.gz/refs/heads/prod","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EduGese%2FScreenPulse-backend-Api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31757477,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T13:27:56.013Z","status":"ssl_error","status_checked_at":"2026-04-13T13:21:23.512Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":["api-rest","backend","expressjs","mongodb","mongoose","nodejs","swagger-ui","typescript"],"created_at":"2024-10-04T04:20:58.312Z","updated_at":"2026-04-13T14:31:22.931Z","avatar_url":"https://github.com/EduGese.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 ScreenPulse API REST  \n\n[![Lint and Test Validation](https://github.com/EduGese/ScreenPulse-backend-Api/actions/workflows/lint.yml/badge.svg)](https://github.com/EduGese/ScreenPulse-backend-Api/actions)\n[![Swagger UI](https://img.shields.io/badge/API%20Docs-Swagger-blue?logo=swagger)](https://edugese.github.io/ScreenPulse-backend-Api/)\n\nThis backend application, built with Node.js and Express, serves as the REST API for the [ScreenPulse-frontApp](https://github.com/EduGese/ScreenPulse-frontApp). It utilizes TypeScript to ensure strong and robust typing, ensuring code reliability and maintainability.\n\n## Introduction\nScreenPulse REST API acts as the backend server for the ScreenPulse-frontApp application, providing endpoints for user authentication, data management, and integration with external APIs such as OMDB.\n\n## 📦 Installation\n\n### Prerequisites\n- Node.js \u003e= 18.x\n- npm \u003e= 9.x\n- MongoDB Atlas account or local MongoDB instance\n\n### Quick Start\n\n1. **Clone the repository**\n```bash\n git clone https://github.com/EduGese/ScreenPulse-backend-Api.git\n\n```\n```bash\ncd ScreenPulse-backend-Api\n```\n2. **Install dependencies**\n```bash\nnpm install\n```\n3. **Set up environment variables**  \nCreate a `.env` file in the root directory. This file is required to configure the application's environment-specific settings such as database credentials, API keys, server ports, and security tokens. Without these, the application will not run correctly.\n\n\u003e _Refer to the [Configuration](#-configuration) section below for all required variables and example settings._\n\n---\n\n##### Notes on `.env` and `.env.production` files\n\n- `.env` is used for local development settings.\n- `.env.production` can be used to specify production-specific environment variables if you manage different configurations for development and production environments.\n- Ensure both files are created and properly configured if your deployment or local setup requires it.\n- These files should **never** be committed to version control to protect sensitive information.\n\n4. **Start the development server**\n```bash\nnpm run dev\n```\n\n## 📜 Available Scripts\n\n- `npm run test` – Run all unit tests using Jest.\n- `npm run test:watch` – Run tests in watch mode for active development.\n- `npm run dev` – Start the development server with hot reloading (Nodemon + ts-node).\n- `npm start` – Start the production server using the compiled JavaScript code.\n- `npm run build` – Compile the TypeScript source code to the `dist` directory.\n- `npm run build_run` – Compile the project and immediately start the server using the compiled output.\n- `npm run prod` – Run the server in production mode (sets `NODE_ENV=production`).\n- `npm run lint` – Run ESLint and automatically fix linting errors in the `src` folder.\n- `npm run format` – Format all source files in `src` using Prettier.\n- `npm run format:check` – Check file formatting with Prettier (does not modify files).\n- `npm run prepare` – Install Husky hooks for Git pre-commit and pre-push validation.\n\n## 🚀 Usage\n\nAfter starting the server, you can quickly test the API with:\n- Register a user:\n```bash\ncurl -X 'POST' \\\n  'http://localhost:9000/api/user/register' \\\n  -H 'accept: application/json' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n  \"name\": \"John Doe\",\n  \"email\": \"john@example.com\",\n  \"password\": \"P@ssw0rd\"\n}'\n```\n\n- Get a movie search\n```bash\ncurl -X 'GET' \\\n  'http://localhost:9000/api/omdb?title=robocop\u0026type=movie' \\\n  -H 'accept: application/json'\n```\n\n## ✨ Features \n- **Authentication:** User registration and login for authentication and authorization.\n- **Data Protection and Security:** Ensures secure password hashing and authentication.\n- **OMDB API Integration:** Retrieve movie, series, and video game information from the OMDB API.\n- **Favorites Management:** CRUD operations to manage user favorites in the database.\n\n## 🛠️ Technologies \u0026 Libraries Used \n- **Node.js:** Server-side JavaScript runtime environment.\n- **Express.js:** Web application framework for Node.js.\n- **Dotenv:** Library for managing environment variables.\n- **Bcryptjs:** Library for secure password hashing.\n- **Mongoose:** MongoDB object modeling tool.\n- **MongoDB Atlas:** Cloud-based database service.\n- **Axios:** Promise-based HTTP client for making requests to servers.\n- **Render:** Hosting service.\n- **Swagger UI:** Interactive API documentation and testing tool.\n- **Jest:** Unit testing framework for JavaScript and TypeScript\n\n\n## 📦 See Also\n\n- [ScreenPulse Frontend App](https://github.com/EduGese/ScreenPulse-frontApp) — Angular web client for this API.\n\n## 📚 Complete Documentation\n\nFor comprehensive technical documentation, architecture details, and development guides, visit our **[Technical Documentation](https://deepwiki.com/EduGese/ScreenPulse-backend-Api/1-overview)**.\n\nThe documentation includes:\n- **API Reference** with detailed endpoint documentation and examples\n- **System Architecture** with visual diagrams and design patterns\n- **Development Guides** covering workflow and best practices\n- **Security \u0026 Middleware** implementation details\n- **Database Models** and data flow documentation\n\nThis external documentation provides deep technical insights beyond the scope of this README.\n\n## ⚙️ Quality Assurance \u0026 Unit Testing Workflow\n\n[![Lint and Test Validation](https://github.com/EduGese/ScreenPulse-backend-Api/actions/workflows/lint.yml/badge.svg)](https://github.com/EduGese/ScreenPulse-backend-Api/actions)\n\nThis project implements a robust two-level code and test validation flow for maximum reliability:\n\n### 1. Local validation with Husky\n\n- **Pre-commit:** Runs `lint-staged` to ensure only staged files passing ESLint rules may be committed.\n- **Pre-push:** Runs both full-project lint and Jest unit tests before pushing. If either fails, the push is blocked.\n- This guarantees that only clean, well-tested, consistent code can reach the remote repository.\n\n### 2. Automated Lint and Tests with GitHub Actions\n\n- Every push or pull request to the `prod` branch triggers a workflow that runs both lint and all unit tests with Jest in a Linux environment through GitHub Actions.\n- Only if all linting passes and all unit tests succeed does GitHub report a green check.\n- Branch protection is enforced: only PRs that pass lint and testing are mergeable into `prod`.\n- This provides a second line of defense—quality is ensured even if local hooks are skipped.\n\n#### Example GitHub Actions Workflow\n```yaml\nname: Lint and Test Validation\n\non:\n  push:\n    branches: [prod]\n  pull_request:\n    branches: [prod]\n\njobs:\n  lint_and_test:\n    name: Lint and Test\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout code\n        uses: actions/checkout@v4\n      - name: Setup Node.js\n        uses: actions/setup-node@v4\n        with:\n          node-version: 20\n      - name: Install dependencies\n        run: npm install\n      - name: Run ESLint\n        run: npm run lint\n      - name: Run Jest unit tests\n        run: npm test\n\n```\n### 3. Unit Test Suite\n\nAutomated unit tests verify business logic for critical modules; coverage is checked as part of the workflow.\n- Unit tests are written using [Jest](https://jestjs.io/).\n- Test files are located alongside your source code, following the pattern `*.spec.ts`.\n- You can run all tests locally with `npm test`.\n- CI and production builds will fail if any unit test does not pass, ensuring only reliable code is deployed.\n\n## 📏 Development Conventions\n\n- **Commits:** Conventional Commits (e.g., `feat:`, `fix:`, `chore:`) for clarity and automated versioning.\n- **Testing:** Unit tests use `*.spec.ts` and are organized by module.\n- **Branching \u0026 PRs:** Feature branches and Pull Requests are used for all substantial changes; all changes must pass CI checks.\n- **Deployments:** Production code is only merged to `prod` after all status checks succeed.\n\n## 🔧 Configuration \nConfiguration settings—including database credentials, API keys, and CORS client URLs—are centralized in environment files (.env for development, .env.production for production). This approach ensures secure, portable, and maintainable environment management.\n\n**Example `.env` file:**\n```env\n# --- Node environment mode ---\nNODE_ENV=development        # 'development', 'production', or 'test'\n\n# --- MongoDB Atlas connection ---\nMONGODB_USER=yourUser           # Atlas database user\nMONGODB_PASSWORD=yourPassword   # Atlas database password\nMONGODB_CLUSTER=clusterId       # Atlas cluster identifier\nMONGODB_COLLECTION=collectionName  # Main database name\n\n# --- Port ---\nPORT=9000                      # Express server port\n\n# --- Client URLs for CORS (per environment) ---\nCLIENT_URL_DEV=http://localhost:4200      # Local frontend for development\nCLIENT_URL_PROD=https://yourdomain.com    # URL of deployed frontend (production)\nCLIENT_URL_TEST=http://localhost:4200\nGITHUB_CLIENT_URL=https://edugese.github.io # Static client for GitHub Pages\n\n# --- External services (OMDB) ---\nOMDB_APIKEY=your-omdb-key      # OMDB API Key\nOMDB_URL=http://www.omdbapi.com/\n\n# --- Security ---\nTOKEN_SECRET=your-jwt-secret   # JWT signing key\nAPI_KEY=your-custom-api-key    # API key for integrations or extra auth\n\n\n```\n\n## 🗄️ Database Connection: MongoDB Atlas \u0026 Local\n\u003e _See the [Configuration](#-configuration) section above for required environment variables._\n\nThis project uses [MongoDB Atlas](https://www.mongodb.com/atlas) — MongoDB's cloud database service — as the primary data store. The connection is managed via [Mongoose](https://mongoosejs.com/) and all configuration details are externalized in environment files (.env/*.env.production) for maximum flexibility and security.\n\n### How it works\n\n- **All database credentials and settings** are defined as environment variables (see the section \"Configuration\" in this README).\n- The connection string is built dynamically in `src/config/config.ts`, using the user, password, cluster name, and database/collection:\n\n```env\nmongodb+srv://\u003cUSER\u003e:\u003cPASSWORD\u003e@\u003cCLUSTER\u003e.mongodb.net/\u003cDB\u003e?retryWrites=true\u0026w=majority\n```\n\n- On startup, the app tries to connect to this MongoDB Atlas cluster using `mongoose.connect(config.mongo.url)`. On failure, errors are logged and the server does not start.\n\n### Switching to another database (e.g., local MongoDB)\n\nYou can easily connect the app to a different MongoDB instance (such as a local install) by overriding the corresponding environment variables:\n\n1. **Comment or remove** the Atlas-related variables in your `.env`.\n2. Add:\n   \n```env\nMONGODB_URI=mongodb://localhost:27017/your-local-db\n```\n3. In `src/config/config.ts`, adapt the code to prioritize this variable if defined:\n```ts\n// Example override logic\nconst MONGODB_URL = process.env.MONGODB_URI || mongodb+srv://${MONGODB_USER}:${MONGODB_PASSWORD}@${MONGODB_CLUSTER}.mongodb.net/${MONGODB_COLLECTION}?retryWrites=true\u0026w=majority;\n```\nSo, if you define MONGODB_URI, that value will be used; otherwise, the system will use the Atlas URI.\n4. **Restart your app**. The database connection will point to the local MongoDB instance.\n\n\u003e **Best practice:** Always use environment variables for all confidential connection data and never hardcode passwords, tokens, or URIs in source files. Document all configuration steps clearly for team collaboration and maintanability.\n\n### Atlas vs. Local: When to use each\n\n- **MongoDB Atlas (default):** Use for production deployments, staging, and shared environments. Advantages: backups, security, scalability.\n- **Local MongoDB:** Use for initial dev or quick testing when you have MongoDB locally installed and running (`mongod`).\n\n### Tips \u0026 Troubleshooting\n\n- Make sure your IP is whitelisted in Atlas when connecting from a new location.\n- If running locally, ensure MongoDB is started (`brew services start mongodb` en Mac, o `sudo systemctl start mongod` en Linux).\n- Rotate secrets regularly and use separate users for dev and prod.\n\n## 🧩 Modular Structure \nThe project follows a modular and layered architecture to ensure scalability, maintainability, and clarity. Below is an overview of the main directories and their responsibilities:\n\n```\napp.ts\n│\n├── config/\n│   └── config.ts\n├── errors/\n│   └── apiError.ts\n├── interfaces/\n│   ├── description.interface.ts\n│   ├── favorites.interface.ts\n│   ├── omdb.interface.ts\n│   └── user.interface.ts\n├── middlewares/\n│   ├── cors.ts, cors.spec.ts\n│   ├── errorHandler.ts, errorHandler.spec.ts\n│   ├── swaggerAuth.ts, swaggerAuth.spec.ts\n│   └── validate.ts\n├── models/\n│   ├── description.ts\n│   ├── favorites.ts\n│   └── user.ts\n├── modules/\n│   ├── index.ts\n│   ├── favorites/\n│   │   ├── favorites.controller.ts, favorites.controller.spec.ts\n│   │   ├── favorites.routes.ts\n│   │   ├── favorites.service.ts, favorites.service.spec.ts\n│   │   └── index.ts\n│   ├── omdb/\n│   │   ├── omdb.controller.ts, omdb.controller.spec.ts\n│   │   ├── omdb.routes.ts\n│   │   ├── omdb.service.ts, omdb.service.spec.ts\n│   │   └── index.ts\n│   └── user/\n│       ├── user.controller.ts, user.controller.spec.ts\n│       ├── user.routes.ts\n│       ├── user.service.ts, user.service.spec.ts\n│       └── index.ts\n├── scripts/\n│   └── generate-swagger-json.ts\n├── utils/\n│   └── swagger/\n│       ├── swagger.ts\n│       ├── parameters/\n│       │   ├── favorites.parameters.ts\n│       │   └── omdb.parameters.ts\n│       └── shemas/\n│           ├── favorites.schema.ts\n│           ├── global.schemas.ts\n│           ├── omdb.schemas.ts\n│           └── user.schemas.ts\n└── validators/\n    ├── favoritesValidator.ts\n    ├── omdbValidators.ts\n    └── userValidators.ts\n```\n\n## Contributing\nContributions are welcome! If you'd like to contribute to the project, please fork the repository, make your changes, and submit a pull request. Be sure to follow the project's coding standards and guidelines.\n\n## License\nThis project is licensed under the [MIT License](#).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedugese%2Fscreenpulse-backend-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fedugese%2Fscreenpulse-backend-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedugese%2Fscreenpulse-backend-api/lists"}