Northstar Platform

A production-grade backend system demonstrating how I design, secure, test, and ship real platforms.

View Source Code →

---

Overview

Northstar is a service marketplace backend built to production standards. This is not a tutorial project or proof-of-concept—it is a complete, deployable system with enterprise-grade architecture, security, and testing.

The codebase exists specifically for technical evaluation. Every architectural decision, security implementation, and test case is inspectable.

Problem Statement

Modern service marketplaces require infrastructure beyond basic CRUD operations:

• Multi-role authorization — Different access levels for customers, providers, staff, and administrators
• Complex workflows — Service requests move through multiple states with validation at each transition
• Background processing — Notifications, cleanup tasks, and async operations
• Audit requirements — Complete traceability for compliance
• Horizontal scalability — Architecture that scales without rewrites

Northstar addresses these requirements with a clean, modular architecture.

Architecture

System Design

Request Flow Overview (Simplified)

╔═══════════════════════════════════════════════════════════════════╗
║                      ⬢  API GATEWAY  (NestJS)                      ║
║            JWT Auth  ·  Rate Limiting  ·  Request Validation       ║
╚═══════════════════════════════════╤═══════════════════════════════╝
                                    │
                                    ▼
                ┌───────────────────────────────────────┐
                │          DOMAIN SERVICES              │
                │  ┌─────────────┬─────────────────┐   │
                │  │  Service    │  User           │   │
                │  │  Requests   │  Management     │   │
                │  ├─────────────┴─────────────────┤   │
                │  │       Admin & Audit           │   │
                │  └───────────────────────────────┘   │
                └───────────────────┬───────────────────┘
                                    │
                                    ▼
                ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐
                  INFRASTRUCTURE LAYER
                │                                   │
                    Redis        PostgreSQL    BullMQ
                │   Cache        (Prisma)      Queue │
                └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘

Key Decisions

Layered Architecture — Controllers handle HTTP concerns only. Services contain business logic. Prisma handles data access. No leaky abstractions.

Event-Driven Patterns — Domain events decouple workflows. A service request status change triggers notifications without tight coupling.

Repository Pattern — Prisma provides type-safe queries. Data access is abstracted, testable, and replaceable.

DTO Validation — Every API input is validated through class-validator DTOs. Invalid requests never reach business logic.

Security Implementation

Security is foundational, not bolted on.

Authentication & Authorization

Role-Based Access Control

ADMIN
├── Full system configuration
├── User management
├── Audit log access
└── All resource access

BUSINESS (Provider)
├── Respond to service requests
├── Manage business profile
└── View own responses

STAFF
├── Review incoming requests
├── Manage request workflows
└── Access operational reports

CUSTOMER
├── Create service requests
├── Manage own requests
└── View request history

API Security

• Rate limiting (100 req/min per client)
• Helmet security headers
• CORS configuration
• Input sanitization
• Audit logging for sensitive operations

Data Model

Core Entities

User — Identity with role assignment and status management

ServiceRequest — Primary business entity with workflow states:

• DRAFT → SUBMITTED → IN_REVIEW → ACCEPTED → IN_PROGRESS → COMPLETED
• CANCELLED (terminal state from any active state)

ProviderResponse — Quotes and proposals from business users

AuditLog — Immutable record of system events with metadata

Database Design

• 12+ strategic indexes for query performance
• Soft deletes for data recovery
• JSON fields for flexible metadata
• Proper foreign key constraints
• Cascading delete rules

Background Processing

Job Queue Architecture

BullMQ handles async operations:

• Email notifications — Queued to prevent request blocking
• Audit log cleanup — Scheduled removal of old records
• Retry logic — Exponential backoff for transient failures
• Idempotency — Duplicate job prevention

Observability

• Structured logging with Pino
• Correlation IDs across requests
• Prometheus-compatible metrics endpoint
• Health check endpoints for orchestration

Testing Strategy

Test Coverage

Unit Tests:        13+ test cases
E2E Tests:         15+ integration tests
Coverage:          Comprehensive across modules

What's Tested

• Service layer business logic
• Authorization guard behavior
• API contract validation
• Error handling paths
• Database operations

Technology Stack

Deployment

Infrastructure Requirements

Minimum:

• Node.js 20+
• PostgreSQL 12+
• Redis 6+

Production:

• Docker/Kubernetes deployment
• Load balancer
• SSL termination
• Database connection pooling

Configuration

Environment-based configuration with validation at startup. Missing required variables cause immediate failure with clear error messages.

Project Metrics

• 100+ TypeScript files with strict typing
• 9 feature modules with clear boundaries
• 20+ API endpoints with full documentation
• 28+ test cases across unit and E2E
• 15+ documentation files

What This Demonstrates

This project proves capability in:

• System Design — Clean architecture that scales
• Security Engineering — Defense in depth, not afterthought
• Testing Discipline — Comprehensive coverage, not checkbox
• Production Thinking — Deployment-ready, not demo-only
• Documentation — Clear, maintainable, professional

---

Role: Backend Architect & Developer
Status: Production Ready
License: MIT

Inspect the Code →