High-performance backend service for the Storagie platform, engineered with NestJS and Fastify. This system adheres to Domain-Driven Design (DDD) principles and utilizes a robust event-driven architecture to ensure scalability and maintainability.
- Global Authentication System: Implements secure, passwordless magic link authentication using JWT (Access and Refresh tokens) with automatic cookie management. Security is enforced globally via guards, with explicit opt-in for public endpoints.
- Modular Architecture: Implementation of Clean Architecture with strict separation of concerns across Domain, Application, and Infrastructure layers.
- Advanced Data Management: PostgreSQL integration via Prisma ORM, featuring custom extensions for comprehensive Soft Delete and Restore capabilities.
- Asynchronous Processing: Integrated BullMQ configuration for handling background jobs and reliable email delivery.
- High Performance: Built on Fastify for high-throughput HTTP handling, complemented by Redis caching strategies.
- Observability: Centralized, structured logging system using Pino for detailed operational insights.
The application is built on a modern, type-safe stack:
- Runtime: Node.js 20+
- Framework: NestJS 11 (Fastify adapter)
- Database: PostgreSQL 16 with Prisma 7 (driver adapters)
- Cache: Redis (IORedis)
- Queue System: BullMQ
- Logging: Pino
- Node.js 20 or higher
- Docker and Docker Compose (for infrastructure)
- pnpm package manager
-
Install dependencies:
pnpm install
-
Configure environment:
cp .env.example .env # For local dev: edit .env and change postgres/redis/mailhog → localhost
Start the complete development environment:
# Build and start all services (API + Postgres + Redis + MailHog)
docker compose up -d --build
# View logs
docker compose logs -f apiMigrations run automatically on container startup.
Run infrastructure in Docker, API locally:
# Start infrastructure only
docker compose up -d postgres redis mailhog
# Run API locally
pnpm dev
# Apply migrations
pnpm db:migrateThe API will be available at http://localhost:8000.
The codebase follows a modular structure to isolate features and infrastructure:
src/
├── config/ # Centralized configuration with validation
├── modules/ # Feature using Domain-Driven Design
│ └── auth/ # Authentication and Session management
│ └── user/ # User domain and profile management
└── shared/
├── constants/ # Dependency Injection tokens and system constants
└── infrastructure/
├── database/ # Prisma configuration and extensions
├── cache/ # Cache abstraction (Redis/Memory)
├── queue/ # Async job processing
├── logging/ # System-wide logging
└── email/ # Email delivery providers
Detailed architectural and operational documentation is available in the /docs directory:
| Topic | Description |
|---|---|
| Architecture | high-level design patterns and principles |
| Authentication | Security flows, tokens, and guards |
| Database | Schema design and ORM usage |
| Configuration | Environment setup and validation |
| Queue System | Background job processing |
| Logging | Log aggregation and standards |
| API Documentation | Swagger/Scalar setup and usage |
Interactive API documentation is available at /docs when running the server. This documentation is powered by Scalar and provides:
- Complete API endpoint reference
- Request/response schemas
- Authentication requirements
- Try-it-out functionality
| Script | Description |
|---|---|
pnpm dev |
Start development server with hot reload |
pnpm dev:apm |
Development with New Relic APM enabled |
pnpm build |
Compile project for production |
pnpm prod |
Start production server |
pnpm prod:apm |
Production with New Relic APM |
pnpm lint |
Run static analysis (Biome) |
pnpm format |
Format codebase (Biome) |
pnpm db:migrate |
Apply database migrations (dev) |
pnpm db:migrate:prod |
Apply migrations (production) |
Please refer to the .agents/rules/ directory for comprehensive coding guidelines, naming conventions, and architectural rules enforced in this project.
Private Repository. All rights reserved.