{"id":50870233,"url":"https://github.com/isogram/ts-backend","last_synced_at":"2026-06-15T04:33:49.110Z","repository":{"id":355221614,"uuid":"1092686644","full_name":"isogram/ts-backend","owner":"isogram","description":"Enterprise-grade NestJS backend with JWT auth, file storage, email service, Redis caching, and distributed tracing","archived":false,"fork":false,"pushed_at":"2026-05-02T13:00:50.000Z","size":193,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-15T04:33:48.429Z","etag":null,"topics":["distributed-tracing","email-service","enterprise","file-upload","jwt-authentication","nestjs","postgresql","redis","rest-api","typescript"],"latest_commit_sha":null,"homepage":"","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/isogram.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":"2025-11-09T05:11:16.000Z","updated_at":"2026-05-02T13:00:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/isogram/ts-backend","commit_stats":null,"previous_names":["isogram/ts-backend"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/isogram/ts-backend","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isogram%2Fts-backend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isogram%2Fts-backend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isogram%2Fts-backend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isogram%2Fts-backend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/isogram","download_url":"https://codeload.github.com/isogram/ts-backend/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isogram%2Fts-backend/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34348291,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["distributed-tracing","email-service","enterprise","file-upload","jwt-authentication","nestjs","postgresql","redis","rest-api","typescript"],"created_at":"2026-06-15T04:33:48.984Z","updated_at":"2026-06-15T04:33:49.100Z","avatar_url":"https://github.com/isogram.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TS Backend\n\nA comprehensive NestJS backend boilerplate with batteries included. This project provides a robust foundation for building scalable, secure, and maintainable Node.js applications.\n\n## Features\n\n- **Authentication**: JWT and OAuth2 authentication\n- **Authorization**: Role-based access control with admin and user routes separation\n- **Database Integration**: TypeORM with PostgreSQL\n- **API Routing**: NestJS Express integration\n- **Error Handling**: Custom error classes and global error filter\n- **Structured Logging**: Winston logger with request ID and correlation ID\n- **Distributed Tracing**: X-Trace-ID header propagation with AsyncLocalStorage context\n- **Queue Processing**: Bull with Redis integration and admin UI\n- **Caching**: NestJS Cache Manager with memory/Redis store\n- **File Upload**: Multer with AWS S3 / MinIO integration\n- **Containerization**: Docker and Docker Compose support\n- **Serverless**: AWS Lambda deployment configuration\n- **API Documentation**: Swagger / OpenAPI integration\n- **Security**: Helmet, CORS, rate limiting\n\n## Architecture Overview\n\n### Project Structure\n\n```plaintext\nsrc/\n├── config/             # Configuration files for different components\n├── database/           # Database seeders and related tools\n├── middleware/         # Custom middleware\n├── migrations/         # Database migrations\n├── modules/            # Feature modules (auth, users, files, etc.)\n│   ├── auth/           # Authentication\n│   │   ├── controllers/\n│   │   ├── dto/        # Data Transfer Objects\n│   │   ├── entities/   # Database entities\n│   │   ├── strategies/ # Auth strategies (JWT, OAuth2)\n│   ├── users/          # User management\n│   │   ├── controllers/\n│   │       ├── users.controller.ts      # Public user endpoints\n│   │       └── admin-users.controller.ts # Admin user management\n│   └── files/          # File uploads\n│       ├── controllers/\n│           ├── files.controller.ts      # Public file endpoints\n│           └── admin-files.controller.ts # Admin file management\n├── shared/             # Shared components\n│   ├── decorators/     # Custom decorators (@Public, @Roles)\n│   ├── exceptions/     # Exception classes\n│   ├── filters/        # Global filters (error handling)\n│   ├── guards/         # Auth guards (JWT, Roles)\n│   ├── interceptors/   # Request interceptors (logging)\n│   ├── modules/        # Shared modules (logger, queue)\n│   └── services/       # Shared services (email, storage, etc.)\n└── main.ts             # Application entry point\n```\n\n## Key Concepts\n\n### Authentication and Authorization\n\nThe application implements a robust authentication system using JWT tokens:\n\n1. **JWT Authentication**: Secure token-based authentication with refresh token support\n2. **OAuth2 Integration**: Support for social logins (Google, GitHub, Facebook)\n3. **Role-Based Access Control**: Users are assigned roles (user, admin, super_admin)\n4. **Public Endpoints**: Use the `@Public()` decorator to exempt routes from authentication\n\n```typescript\n// Example of a secured admin-only endpoint\n@Controller('admin/users')\n@UseGuards(JwtAuthGuard, RolesGuard)\n@Roles(UserRole.ADMIN, UserRole.SUPER_ADMIN)\nexport class AdminUsersController {\n    // Admin-only endpoints\n}\n\n// Example of a public endpoint\n@Public()\n@Post('login')\nasync login(@Body() loginDto: LoginDto): Promise\u003cLoginResponse\u003e {\n    // Authentication logic\n}\n```\n\n### Admin vs Regular User Routes\n\nThe application separates admin routes from regular user routes:\n\n1. **Admin Routes**: Protected with `@Roles(UserRole.ADMIN)` and prefixed with `/admin/`\n2. **Regular User Routes**: Available to authenticated users, with permissions based on resource ownership\n3. **Role-Based Authorization**: Using guards to enforce role requirements across the application\n\n### Database Configuration\n\nThe application has three database configuration files for different purposes:\n\n1. **`src/config/database.config.ts`**: Source of truth for database configuration\n2. **`src/app.module.ts`**: Configures TypeORM for NestJS dependency injection\n3. **`src/data-source.ts`**: Standalone DataSource for TypeORM CLI and migrations\n\nSee `docs/database-configuration.md` for details on why this structure is used.\n\n### Queue System\n\nThe application uses Bull with Redis for background job processing:\n\n1. **Queue Management**: Process tasks asynchronously (emails, file processing)\n2. **Admin UI**: Bull-Board dashboard available at `/admin/queues` for monitoring jobs\n3. **Multiple Processors**: Different processors handle different types of jobs\n\nSee `docs/queue-system.md` for details on the queue architecture.\n\n### File Storage\n\nThe application supports multiple storage options:\n\n1. **S3-Compatible Storage**: Works with AWS S3, MinIO, and other S3-compatible storage\n2. **Local File Storage**: For development or smaller deployments\n3. **File Access Control**: Files can be public or private with access control\n\n### Caching\n\nThe application provides a flexible caching system:\n\n1. **In-Memory Cache**: Default for development\n2. **Redis Cache**: For production environments (see `docs/redis-caching.md`)\n3. **Cache Decorators**: Easy-to-use cache annotations for controllers\n\n## Getting Started\n\n### Prerequisites\n\n- Node.js (v16+)\n- Docker and Docker Compose (for local development)\n- PostgreSQL (if not using Docker)\n- Redis (if not using Docker)\n\n### Installation\n\n```bash\nnpm install\n```\n\n### Environment Setup\n\nCopy the example environment file:\n\n```bash\ncp .env.example .env\n```\n\nThen edit the `.env` file with your specific configuration.\n\n### Running with Docker Compose (Recommended)\n\n```bash\n# Start all services\ndocker-compose up\n\n# Start in detached mode\ndocker-compose up -d\n\n# Stop all services\ndocker-compose down\n```\n\n### Running Without Docker\n\n```bash\n# Development mode\nnpm run start\n\n# Watch mode\nnpm run start:dev\n\n# Production mode\nnpm run start:prod\n```\n\n## Database Management\n\n### Configuration\n\nThe database configuration can be found in `src/config/database.config.ts` and key options in `.env`:\n\n```env\nDATABASE_TYPE=postgres\nDATABASE_HOST=localhost\nDATABASE_PORT=5432\nDATABASE_USERNAME=postgres\nDATABASE_PASSWORD=postgres\nDATABASE_NAME=ts_backend\nDATABASE_SYNCHRONIZE=false  # Should be false in production\nDATABASE_LOGGING=true\nDATABASE_MIGRATIONS_RUN=true\n```\n\n### Migrations\n\nFor production environments, use database migrations:\n\n```bash\n# Create a new migration (empty)\nnpm run migration:create -- --name=MigrationName\n\n# Generate a migration from entity changes\nnpm run migration:generate -- --name=MigrationName\n\n# Run migrations\nnpm run migration:run\n\n# Revert the last migration\nnpm run migration:revert\n```\n\n### Database Seeding\n\nTo seed your database with initial data:\n\n```bash\n# Run all seeders\nnpm run db:seed\n```\n\n## Queue Management\n\nThe application uses Bull with Redis for background job processing. Access the dashboard at:\n\n```\nhttp://localhost:3000/admin/queues\n```\n\nUsername: admin  \nPassword: password\n\n## API Documentation\n\nSwagger API documentation is available at:\n\n```\nhttp://localhost:3000/api/docs\n```\n\n## Security Measures\n\nThe application implements several security best practices:\n\n1. **Helmet**: Sets HTTP security headers\n2. **Rate Limiting**: Protects against brute force attacks\n3. **CORS**: Controls cross-origin requests\n4. **Validation**: Validates all incoming data with DTO schemas\n5. **Password Hashing**: Uses bcrypt for secure password storage\n\n## Deployment\n\n### Docker / ECS\n\n```bash\n# Build the Docker image\ndocker build -t ts-backend .\n\n# Run the container\ndocker run -p 3000:3000 ts-backend\n```\n\n### AWS Lambda\n\n```bash\n# Install serverless framework\nnpm install -g serverless\n\n# Deploy to AWS\nserverless deploy\n```\n\n## Development Guidelines\n\n### Adding New Features\n\n1. Create a new module in the `src/modules` directory\n2. Implement entities, DTOs, services, and controllers\n3. Follow the separation of admin vs. regular user routes\n4. Add appropriate guards and decorators for security\n\n### Testing\n\n```bash\n# Unit tests\nnpm run test\n\n# E2E tests\nnpm run test:e2e\n\n# Test coverage\nnpm run test:cov\n```\n\n## Documentation\n\nSee the `docs` folder for detailed documentation on various aspects of the application:\n\n- [Database Configuration](docs/database-configuration.md)\n- [Queue System](docs/queue-system.md)\n- [Redis Caching](docs/redis-caching.md)\n- [Path Aliases](docs/path-aliases.md)\n- [Queue Dashboard](docs/queue-dashboard.md)\n- [Logging](docs/logging.md)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fisogram%2Fts-backend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fisogram%2Fts-backend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fisogram%2Fts-backend/lists"}