Skip to content

Monorepo Structure

The Trove codebase is a single Nx monorepo managed with pnpm. All applications and shared libraries live in the same repository, enabling shared types, utilities, and consistent tooling across the entire platform.

Requirements

Tool Version
Node.js >= 22
pnpm >= 10
Nx 20.4.2

Repository Layout

trove/
├── apps/
│   ├── api/                  # NestJS REST API
│   ├── api-e2e/              # API end-to-end tests
│   ├── admin-portal/         # Brand management SPA (React + Vite)
│   ├── admin-portal-e2e/     # Admin portal end-to-end tests
│   ├── customer-frontend/    # Gift recipient storefront (React + Vite)
│   ├── customer-frontend-e2e/
│   └── worker/               # Async job processor (NestJS + SQS)
│
├── libs/
│   ├── api/
│   │   ├── data-access/      # Database entities, repositories, MikroORM config
│   │   └── shared/           # Shared DTOs, types, and utilities used by the API
│   ├── frontend/             # Shared UI components, hooks, and utilities
│   └── shared/               # Cross-cutting types and utilities used across all apps
│
├── database/
│   ├── migrations/           # 150+ MikroORM migration files
│   └── seeders/              # 37+ seed scripts for dev/staging environments
│
├── nx.json                   # Nx workspace configuration
├── package.json              # Root package with shared dev dependencies
└── pnpm-workspace.yaml       # pnpm workspace definition

Applications

API (apps/api)

The core backend service. See the API page for full details.

  • Framework: NestJS 11 + Fastify
  • Port: 3000 (default)
  • Entry point: apps/api/src/main.ts

Admin Portal (apps/admin-portal)

The brand-facing management interface. See the Admin Portal page for full details.

  • Framework: React 18 + Vite 6
  • Port: 8080 (default)
  • Multi-tenant: Subdomain-based ({vendor}.localhost:8080 in development)

Customer Frontend (apps/customer-frontend)

The storefront presented to gift recipients.

  • Framework: React 18 + Vite 6
  • Served per-brand based on storefront configuration

Worker (apps/worker)

Async job processor that polls AWS SQS queues and handles background tasks.

  • Framework: NestJS
  • Queue: AWS SQS
  • Handlers: Email, exports, imports, invoice, orders-push, products, Shopify webhook, Slack notification, sync

Shared Libraries

libs/api/data-access

Database layer shared across the API and Worker. Contains:

  • MikroORM entity definitions
  • Repository classes
  • Database connection configuration

libs/api/shared

Shared API-layer code:

  • DTOs (Data Transfer Objects)
  • Request/response types
  • Validation utilities
  • Constants used across the API

libs/frontend

Shared frontend code used by both admin-portal and customer-frontend:

  • Reusable React components
  • Shared hooks
  • Common utility functions

libs/shared

Cross-cutting code used by all applications:

  • TypeScript types and interfaces
  • Domain enums and constants
  • Utility functions with no framework dependency

Database

The database/ directory contains all schema management assets:

  • Migrations (database/migrations/) - 150+ sequential migration files. Applied in order to build or update the schema. Run via MikroORM CLI.
  • Seeders (database/seeders/) - 37+ seed scripts used to populate development and staging environments with test data.

Common Commands

# Run pending migrations
pnpm nx run api:migration:up

# Create a new migration
pnpm nx run api:migration:create

# Run seeders
pnpm nx run api:seed

Nx Workspace

Nx provides task orchestration, caching, and dependency graph management across all apps and libraries.

Common Nx Commands

# Run the API in development
pnpm nx serve api

# Run the admin portal
pnpm nx serve admin-portal

# Run the worker
pnpm nx serve worker

# Build all apps
pnpm nx run-many --target=build --all

# Run all tests
pnpm nx run-many --target=test --all

# Visualise the dependency graph
pnpm nx graph

Affected Commands

Nx can determine which apps and libraries are affected by a change - useful in CI to avoid running tests for unmodified code:

pnpm nx affected --target=test
pnpm nx affected --target=build

CI/CD

The monorepo uses GitHub Actions for CI/CD. Pipelines leverage Nx affected commands to only build and test what has changed.

See Git Branching & Deployment Workflow for the full deployment process.