Architecture Decision Records

Formal record of significant technical decisions. Status: Accepted unless noted otherwise.

ADR-0001: Turborepo Monorepo Orchestration

Status: Accepted

Date: 2026-07-06

Deciders: Li Hong

Context

NovaDesk contains five applications, six backend services, and eight shared packages in a single repository. We need build orchestration that:

Parallelizes tasks across workspaces
Caches build outputs between CI runs and local development
Respects dependency order (packages before services before apps)
Keeps CI fast enough for a solo maintainer workflow

Decision

Adopt pnpm workspaces for dependency linking and Turborepo 2 for task pipelines (build, lint, test, typecheck, dev).

Pipeline rules in turbo.json:

build depends on ^build (upstream packages first)
Outputs cached: .next/**, dist/**
dev is persistent and uncached

Alternatives considered

Alternative	Rejected because
Nx	Heavier configuration for portfolio scope; Turborepo sufficient
Lerna	Less active ecosystem; weaker caching story
Separate repos	Loses atomic cross-service changes and shared CI
npm workspaces only	No task caching or pipeline DAG

Consequences

Positive

Single pnpm turbo build validates entire monorepo
CI time reduced via remote-aware cache keys
Clear task graph visible in turbo.json

Negative

Turborepo adds a dependency and learning curve
Cache invalidation requires discipline on env var changes

Compliance

Aligns with 00-Vision.md goal of demonstrating monorepo engineering maturity.

↑ Back to Engineering index

ADR-0002: NestJS for Backend Microservices

Status: Accepted

Date: 2026-07-06

Deciders: Li Hong

Context

NovaDesk requires six backend services with consistent patterns for authentication guards, validation, OpenAPI documentation, health checks, and testing. Framework choice affects hiring signal, maintainability, and integration with TypeScript monorepo tooling.

Decision

Use NestJS 10 for all backend services:

@novadesk/gateway — API Gateway
@novadesk/auth-service — Identity provider
@novadesk/notification-service — Email and notifications
@novadesk/helpdesk-api — HelpDesk domain API
@novadesk/analytics-api — Analytics domain API
@novadesk/realtime-chat-service — WebSocket messaging

Each service is a standalone NestJS application with its own Dockerfile, captain-definition, and database schema where applicable.

Alternatives considered

Alternative	Rejected because
Fastify standalone	Less structure for multi-module domains; Spell used Fastify but NovaDesk needs consistency across 6 services
Express	No built-in DI, module system, or OpenAPI integration
Go microservices	Breaks TypeScript end-to-end; shared types with frontend lost
Single Express monolith	Does not demonstrate service boundary thinking

Consequences

Positive

Uniform module/guard/interceptor patterns via @novadesk/auth and @novadesk/logger
Swagger auto-generated per service
Jest/Vitest testing with Nest testing utilities

Negative

NestJS boilerplate per service
Cold start slightly higher than minimal Fastify (acceptable for portfolio)

Compliance

Documented in service READMEs and 03-Coding-Standards.md.

↑ Back to Engineering index

ADR-0003: Next.js App Router for Frontends

Status: Accepted

Date: 2026-07-06

Deciders: Li Hong

Context

NovaDesk has four SaaS applications plus a public marketing/documentation website. Frontend technology must support SSR for SEO (website), client-heavy dashboards (HelpDesk, Analytics), and shared UI components across apps.

Decision

Use Next.js 14 with App Router for all frontends:

App	Package	Purpose
Website	`@novadesk/website`	Portfolio, case studies, engineering docs
HelpDesk	`@novadesk/helpdesk-saas`	Ticket management UI
Analytics	`@novadesk/analytics-dashboard`	KPI dashboards
Admin	`@novadesk/admin-panel`	Platform administration
Chat	`@novadesk/realtime-chat`	Realtime messaging UI

Conventions:

Server Components by default
Client Components only for interactivity (forms, charts, WebSocket)
Feature-Sliced Design folder structure in SaaS apps
Shared UI from @novadesk/ui

Alternatives considered

Alternative	Rejected because
Vite + React SPA	No SSR for website; worse SEO for portfolio
Remix	Smaller hiring signal; team familiarity with Next.js
Pages Router	App Router is current standard; RSC benefits

Consequences

Positive

One React framework across all apps
SSG for case studies and engineering pages
API routes only at integration boundaries (contact form proxy)

Negative

App Router complexity for WebSocket-heavy chat
Multiple Next.js builds in CI (mitigated by Turborepo cache)

Compliance

Matches 03-Coding-Standards.md frontend conventions.

↑ Back to Engineering index

ADR-0004: PostgreSQL as Primary Data Store

Status: Accepted

Date: 2026-07-06

Deciders: Li Hong

Related: 17-Data-Architecture.md

Context

Services need durable relational storage with ACID guarantees, migration tooling, and TypeScript integration. HelpDesk requires complex tenant-scoped queries; Auth requires transactional consistency for credentials and tokens.

Decision

Use PostgreSQL 16 as the primary database with Prisma 5 ORM per service.

Database ownership:

Service	Database	Notes
Auth Service	`auth_db`	Users, roles, tenants, refresh tokens
HelpDesk API	`helpdesk_db`	Tickets, customers, workspaces
Notification	`notification_db`	Templates, delivery log
Analytics API	`analytics_db`	Metrics aggregates

No cross-service database access. Services communicate via HTTP APIs only.

Redis is used for cache, rate limiting, pub/sub, and BullMQ queues — not as primary store.

Alternatives considered

Alternative	Rejected because
MongoDB	Weaker relational modeling for multi-tenant RBAC
MySQL	PostgreSQL JSON and extension ecosystem preferred
Shared database	Violates service boundary isolation
Supabase/Firebase	External dependency; less control for portfolio demo

Consequences

Positive

Prisma schema as living documentation
Migration history per service
Strong consistency for auth and billing-adjacent data

Negative

Multiple PostgreSQL instances in production (or schemas with strict isolation)
Prisma migration coordination across services

Compliance

Aligned with 17-Data-Architecture.md.

↑ Back to Engineering index

ADR-0005: Docker Containerization Strategy

Status: Accepted

Date: 2026-07-06

Deciders: Li Hong

Related: 06-DevOps.md, DEPLOY-CAPROVER.md

Context

NovaDesk must run identically in local development and production. Twelve deployable units (6 services + 5 apps + nginx) require reproducible builds and independent deploy capability.

Decision

Container-first deployment:

Local: docker-compose.yml with PostgreSQL, Redis, Nginx, and all services
Production: CapRover with per-component captain-definition and Git webhook deploy
Multi-stage Dockerfiles — build stage (pnpm + turbo) → slim runtime (Node 20 Alpine)

Each service/app has:

Dockerfile at package root
captain-definition pointing to Dockerfile path
Environment variables documented in .env.example

Nginx routes path prefixes to containers — single domain, multiple apps.

Alternatives considered

Alternative	Rejected because
PM2 on VPS	No isolation; harder to replicate locally
Kubernetes	Operational overhead excessive for solo portfolio
Serverless (Lambda)	WebSocket and long-running workers poorly suited
Vercel-only	Backend microservices need persistent processes

Consequences

Positive

docker compose up gives full stack locally
Independent service deploys on CapRover
Demonstrates DevOps competence to reviewers

Negative

Image build time in CI
CapRover-specific deploy knowledge required

Compliance

Documented in 06-DevOps.md and infrastructure/caprover/README.md.

↑ Back to Engineering index

ADR-0006: Shared Packages for Cross-Cutting Concerns

Status: Accepted

Date: 2026-07-06

Deciders: Li Hong

Context

Six services and five applications duplicate auth logic, env validation, logging format, UI primitives, and API types without shared packages. Duplication causes drift and undermines the monorepo value proposition.

Decision

Create eight workspace packages under packages/:

Package	Responsibility
`@novadesk/tsconfig`	TypeScript base configs
`@novadesk/eslint-config`	ESLint flat config
`@novadesk/config`	Zod env schemas
`@novadesk/shared`	Types, enums, utilities
`@novadesk/logger`	Structured Pino logging
`@novadesk/auth`	JWT utils, guards, decorators
`@novadesk/sdk`	HTTP client for service calls
`@novadesk/ui`	Design system components

Dependency rules:

Packages may not import from services/ or apps/
Apps and services consume packages via workspace:*
UI package is framework-aware but primitives stay portable

Alternatives considered

Alternative	Rejected because
Copy-paste utils	Drift between services; poor reviewer signal
npm published packages	Overhead for private portfolio monorepo
Single `common` package	God package anti-pattern; boundaries blur

Consequences

Positive

Auth guard behavior identical across all NestJS services
UI consistency across four Next.js apps
Single place to update logging format

Negative

Package versioning discipline required
Breaking changes ripple via Turborepo rebuild

Compliance

Milestone M1 deliverable per 09-Roadmap.md.

↑ Back to Engineering index

ADR-0007: API Gateway as Single Entry Point

Status: Accepted

Date: 2026-07-06

Deciders: Li Hong

Related: 01-Architecture.md, 07-Security.md

Context

Multiple backend services expose REST APIs. Clients should not hold service-specific URLs, CORS policies, or JWT validation logic. A single perimeter simplifies security, rate limiting, and observability.

Decision

Implement API Gateway (@novadesk/gateway) as the sole HTTP entry point for backend APIs:

Responsibilities:

JWT validation (RS256 via JWKS from Auth Service)
Rate limiting (Redis-backed sliding window)
Request ID assignment and propagation
Reverse proxy to target service by path prefix
WebSocket upgrade proxy for Realtime Chat
CORS policy enforcement
Circuit breaker for unhealthy upstreams (configurable)

Clients call /api/v1/* only. Internal service URLs are not exposed to browsers.

Nginx sits in front for TLS termination and static path routing to Next.js apps.

Alternatives considered

Alternative	Rejected because
Direct service access	CORS and auth duplicated per service
Kong/AWS API Gateway	External dependency; less code visibility in portfolio
GraphQL federation	REST aligns with NovaDesk API standards; simpler for reviewers
Service mesh (Istio)	Operational complexity unjustified

Consequences

Positive

Single place for auth, rate limits, and request logging
Services trust gateway-injected identity headers on internal network
Clear diagram for architecture interviews

Negative

Gateway becomes critical path — requires health monitoring and horizontal scale plan
Added network hop latency (minimal on same host/Docker network)

Compliance

Documented in 16-Service-Catalog.md and request flow page.

↑ Back to Engineering index