docs: Add readme

Author: d-arsya

.gitignore

@@ -54,3 +54,6 @@ pids
 
 # Diagnostic reports (https://nodejs.org/api/report.html)
 report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+plans
+agent

README.md

@@ -1,98 +1,127 @@
-<p align="center">
-  <a href="http://nestjs.com/" target="blank"><img src="https://nestjs.com/img/logo-small.svg" width="120" alt="Nest Logo" /></a>
-</p>
-
-[circleci-image]: https://img.shields.io/circleci/build/github/nestjs/nest/master?token=abc123def456
-[circleci-url]: https://circleci.com/gh/nestjs/nest
-
-  <p align="center">A progressive <a href="http://nodejs.org" target="_blank">Node.js</a> framework for building efficient and scalable server-side applications.</p>
-    <p align="center">
-<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/v/@nestjs/core.svg" alt="NPM Version" /></a>
-<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/l/@nestjs/core.svg" alt="Package License" /></a>
-<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/dm/@nestjs/common.svg" alt="NPM Downloads" /></a>
-<a href="https://circleci.com/gh/nestjs/nest" target="_blank"><img src="https://img.shields.io/circleci/build/github/nestjs/nest/master" alt="CircleCI" /></a>
-<a href="https://discord.gg/G7Qnnhy" target="_blank"><img src="https://img.shields.io/badge/discord-online-brightgreen.svg" alt="Discord"/></a>
-<a href="https://opencollective.com/nest#backer" target="_blank"><img src="https://opencollective.com/nest/backers/badge.svg" alt="Backers on Open Collective" /></a>
-<a href="https://opencollective.com/nest#sponsor" target="_blank"><img src="https://opencollective.com/nest/sponsors/badge.svg" alt="Sponsors on Open Collective" /></a>
-  <a href="https://paypal.me/kamilmysliwiec" target="_blank"><img src="https://img.shields.io/badge/Donate-PayPal-ff3f59.svg" alt="Donate us"/></a>
-    <a href="https://opencollective.com/nest#sponsor"  target="_blank"><img src="https://img.shields.io/badge/Support%20us-Open%20Collective-41B883.svg" alt="Support us"></a>
-  <a href="https://twitter.com/nestframework" target="_blank"><img src="https://img.shields.io/twitter/follow/nestframework.svg?style=social&label=Follow" alt="Follow us on Twitter"></a>
-</p>
-  <!--[![Backers on Open Collective](https://opencollective.com/nest/backers/badge.svg)](https://opencollective.com/nest#backer)
-  [![Sponsors on Open Collective](https://opencollective.com/nest/sponsors/badge.svg)](https://opencollective.com/nest#sponsor)-->
-
-## Description
-
-[Nest](https://github.com/nestjs/nest) framework TypeScript starter repository.
-
-## Project setup
-
+# Nothing Backend - NestJS Scaffold Template
+
+A progressive and production-ready NestJS scaffold template designed for scalability, type-safety, and clean architecture. This project serves as a foundation for building robust e-commerce or catalog-based backends.
+
+## 🚀 Tech Stack
+
+- **Framework:** [NestJS v11](https://nestjs.com/) (Express-based)
+- **Language:** TypeScript (ES2023)
+- **Database:** PostgreSQL with [TypeORM](https://typeorm.io/)
+- **Validation:** [Zod](https://zod.dev/) via `nestjs-zod` for absolute type safety.
+- **Authentication:** JWT (Passport.js strategy) with Access & Refresh token rotation.
+- **File Storage:** AWS S3 / MinIO integration via AWS SDK v3.
+- **API Documentation:** Integrated Swagger UI (OpenAPI 3.0).
+- **Tooling:** ESLint, Prettier, Jest.
+
+## 🏗️ Architectural Decisions
+
+### 1. Modular Structure
+The application is organized into domain-driven modules located in `src/modules`. Each module is self-contained, encapsulating its own controllers, services, entities, and DTOs.
+- `AuthModule`: Identity and access management.
+- `UsersModule`: Profile and user management.
+- `ProductsModule`: Catalog and inventory management.
+- `CategoriesModule`: Hierarchical classification.
+
+### 2. Path Aliases
+To avoid deep relative imports (`../../../../`), the project uses TypeScript path aliases defined in `tsconfig.json`:
+- `@modules/*` -> `src/modules/*`
+- `@common/*` -> `src/common/*`
+- `@config/*` -> `src/config/*`
+- `@database/*` -> `src/database/*`
+- `@helpers/*` -> `src/helpers/*`
+
+### 3. Response & Error Standardization
+The backend enforces a strict design system for API communication:
+- **Success Interceptor**: All successful responses are automatically wrapped in a standard `ApiResponse` structure:
+  ```json
+  {
+    "success": true,
+    "message": "Success",
+    "data": { ... },
+    "meta": { ... } // Optional (e.g., pagination)
+  }
+  ```
+- **Global Exception Filter**: Errors are caught and formatted consistently by the `HttpExceptionFilter`, ensuring even internal errors return a safe and readable JSON response.
+
+### 4. Schema-First Validation
+We use `zod` for all DTOs. This ensures that validation and TypeScript types are always in sync. Use the `ZodValidationPipe` (global) to handle input validation automatically.
+
+---
+
+## 🛠️ Getting Started
+
+### Prerequisites
+- Node.js (v18+)
+- PostgreSQL
+- S3 Compatible Storage (MinIO or AWS S3)
+
+### Installation
 ```bash
-$ npm install
+npm install
 ```
 
-## Compile and run the project
-
+### Environment Setup
+Copy `.env.example` to `.env` and fill in your credentials:
 ```bash
-# development
-$ npm run start
-
-# watch mode
-$ npm run start:dev
-
-# production mode
-$ npm run start:prod
+cp .env.example .env
 ```
 
-## Run tests
-
+### Running the App
 ```bash
-# unit tests
-$ npm run test
-
-# e2e tests
-$ npm run test:e2e
+# Development
+npm run start:dev
 
-# test coverage
-$ npm run test:cov
+# Production Build
+npm run build
+npm run start:prod
 ```
 
-## Deployment
+### API Documentation
+Once the app is running, visit:
+- **Swagger UI**: `http://localhost:3000/docs`
+- **Static Spec**: `src/swagger.json`
 
-When you're ready to deploy your NestJS application to production, there are some key steps you can take to ensure it runs as efficiently as possible. Check out the [deployment documentation](https://docs.nestjs.com/deployment) for more information.
+---
 
-If you are looking for a cloud-based platform to deploy your NestJS application, check out [Mau](https://mau.nestjs.com), our official platform for deploying NestJS applications on AWS. Mau makes deployment straightforward and fast, requiring just a few simple steps:
+## 📘 Integration Guide (For AI Agents & Developers)
 
-```bash
-$ npm install -g @nestjs/mau
-$ mau deploy
-```
-
-With Mau, you can deploy your application in just a few clicks, allowing you to focus on building features rather than managing infrastructure.
+When building new features on top of this scaffold, follow these guidelines to maintain consistency:
 
-## Resources
+### 1. Adding a New Module
+Use the NestJS CLI or create a directory in `src/modules/[feature]`:
+1. **Define Entity**: Create `entities/[feature].entity.ts` using TypeORM decorators.
+2. **Define Schema/DTO**: Create `dto/[feature].dto.ts` using `zod` schemas.
+3. **Service**: Implement business logic in `[feature].service.ts`.
+4. **Controller**: Define endpoints in `[feature].controller.ts`.
+5. **Module**: Wire everything in `[feature].module.ts` and import it into `AppModule`.
 
-Check out a few resources that may come in handy when working with NestJS:
+### 2. Working with Standard Responses
+You do not need to wrap your data in `success` or `message` keys manually in the controller. Return the raw data (or a promise), and the `ResponseInterceptor` will handle the wrapping.
+- **Custom Message**: If you need a specific message, return an object like `{ data, message: 'Your message' }`.
 
-- Visit the [NestJS Documentation](https://docs.nestjs.com) to learn more about the framework.
-- For questions and support, please visit our [Discord channel](https://discord.gg/G7Qnnhy).
-- To dive deeper and get more hands-on experience, check out our official video [courses](https://courses.nestjs.com/).
-- Deploy your application to AWS with the help of [NestJS Mau](https://mau.nestjs.com) in just a few clicks.
-- Visualize your application graph and interact with the NestJS application in real-time using [NestJS Devtools](https://devtools.nestjs.com).
-- Need help with your project (part-time to full-time)? Check out our official [enterprise support](https://enterprise.nestjs.com).
-- To stay in the loop and get updates, follow us on [X](https://x.com/nestframework) and [LinkedIn](https://linkedin.com/company/nestjs).
-- Looking for a job, or have a job to offer? Check out our official [Jobs board](https://jobs.nestjs.com).
+### 3. Storage Integration
+Use the `S3Helper` from `@helpers/s3.helper`:
+```typescript
+constructor(private readonly s3Helper: S3Helper) {}
 
-## Support
-
-Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please [read more here](https://docs.nestjs.com/support).
+async upload(file: Express.Multer.File) {
+  return await this.s3Helper.uploadFile(file, 'folder-name');
+}
+```
 
-## Stay in touch
+### 4. Authentication & RBAC
+Protect routes using the built-in guards:
+- **JWT Protection**: `@UseGuards(JwtAuthGuard)`
+- **Role Based Access**: `@Roles(Role.Admin)` + `@UseGuards(JwtAuthGuard, RolesGuard)`
 
-- Author - [Kamil Myśliwiec](https://twitter.com/kammysliwiec)
-- Website - [https://nestjs.com](https://nestjs.com/)
-- Twitter - [@nestframework](https://twitter.com/nestframework)
+### 5. Database Conventions
+- Always use `uuid` for primary keys.
+- Use `CreateDateColumn` and `UpdateDateColumn` for auditing.
+- Prefer relations over manual ID handling where possible.
 
-## License
+---
 
-Nest is [MIT licensed](https://github.com/nestjs/nest/blob/master/LICENSE).
+## 🛡️ Design System & Standards
+- **Naming**: camelCase for variables/functions, PascalCase for classes, kebab-case for files.
+- **Comments**: We follow the **NO non-essential comments** rule. Code should be self-documenting. Use comments only for complex algorithmic logic.
+- **Git**: Commits should be descriptive. Feature branches are preferred.

package.json

@@ -20,8 +20,8 @@
     "test:watch": "jest --watch",
     "test:cov": "jest --config ./jest.json --coverage",
     "test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand"
-    },
-    "dependencies": {
+  },
+  "dependencies": {
     "@aws-sdk/client-s3": "^3.1037.0",
     "@nestjs/common": "^11.0.1",
     "@nestjs/core": "^11.0.1",
@@ -41,8 +41,8 @@
     "swagger-ui-express": "^5.0.1",
     "typeorm": "^0.3.28",
     "zod": "^4.3.6"
-    },
-    "devDependencies": {
+  },
+  "devDependencies": {
     "@eslint/eslintrc": "^3.2.0",
     "@eslint/js": "^9.18.0",
     "@nestjs/cli": "^11.0.0",
@@ -67,8 +67,8 @@
     "tsconfig-paths": "^4.2.0",
     "typescript": "^5.7.3",
     "typescript-eslint": "^8.20.0"
-    },
-    "jest": {
+  },
+  "jest": {
     "moduleFileExtensions": [
       "js",
       "json",
@@ -88,7 +88,9 @@
       "<rootDir>/src/**/*.integration-spec.ts",
       "<rootDir>/test/**/*.e2e-spec.ts"
     ],
-    "setupFilesAfterEnv": ["<rootDir>/test/setup-jest.ts"],
+    "setupFilesAfterEnv": [
+      "<rootDir>/test/setup-jest.ts"
+    ],
     "coverageThreshold": {
       "global": {
         "branches": 100,
@@ -97,7 +99,5 @@
         "statements": 100
       }
     }
-    }
-    }
-
-}
+  }
+}