Monorepo

Refract is a pnpm workspace monorepo. All the code — backend, frontend, shared contracts, pluggable tool implementations — lives in a single repo, managed by a single pnpm-lock.yaml. Once you understand the workspace layout, the architecture becomes much easier to navigate.

Workspace layout

apps/
├── backend/                  ← Node.js API server (Express + GraphQL)
├── portal/                   ← React SPA (Vite + Apollo Client)
├── marketing/                ← Astro marketing site
├── shared/                   ← Shared types and Zod schemas
├── tools/
│   ├── queue/
│   │   ├── bullmq/           ← BullMQ queue implementation
│   │   └── sqs/              ← AWS SQS queue implementation
│   ├── logger/
│   │   ├── pino/             ← Pino logger implementation
│   │   └── console/          ← Console logger implementation
│   └── metrics/
│       └── statsd/           ← StatsD metrics implementation
└── ...                       ← Other workspace apps/packages

This is defined in pnpm-workspace.yaml:

packages:
  - "apps/backend"
  - "apps/marketing"
  - "apps/portal"
  - "apps/shared"
  - "apps/tools/*/*"

The glob apps/tools/*/* means any directory two levels deep under apps/tools/ is a workspace package. Adding a new tool implementation is as simple as creating the directory — pnpm picks it up automatically on the next make deps-install.

How packages reference each other

There are two kinds of dependencies here: Static dependencies (solid lines) — declared in package.json with workspace:*. The backend and all tool packages depend on apps/shared this way. pnpm resolves workspace:* to the local package, so you always get the version in the repo. Dynamic dependencies (dashed lines) — tool packages are not statically imported. The backend’s loaders (tools/queue/loader.ts, tools/logger/loader.ts, etc.) use dynamic import() to load the right implementation at runtime, based on the client value in the environment’s config. This is what makes the tool system pluggable — swap the config value and nothing else changes.

`apps/shared` — the contract layer

apps/shared is the source of truth for types and Zod schemas that both the backend and tool packages need to agree on. Things like QueueType, LoggerType, and MetricsType live here. If you’re adding a new pluggable tool:

Define its contract interface and Zod config schema in apps/shared/src/.
Build the tool package in apps/tools/<tool>/<implementation>/ satisfying that interface.
Write the loader in apps/backend/src/tools/<tool>/loader.ts.

This separation means tool packages never import from the backend, and the backend only knows about tool packages through the shared interface — not their implementation details.

💡 Tip: after changing anything in apps/shared, run make build module=shared (or make build-all) before running backend tests. The backend’s TypeScript compilation needs the compiled apps/shared/dist/ to resolve the types.

Adding a new tool implementation

Let’s say you want to add a Redis-backed queue as an alternative to BullMQ:

Create the package directory:

apps/tools/queue/redis/
├── package.json
├── tsconfig.json
├── eslint.config.mjs
└── src/
    └── index.ts

Implement the interface from apps/shared:

import type { QueueType } from 'tooling-shared';

export const buildRedisQueueClient = async (config, tools): Promise<QueueType> => {
  // ...
};

Run make deps-install — pnpm detects the new package and wires up the workspace links.
Add the package name to the loader in apps/backend/src/tools/queue/loader.ts.
Add the new client value to the config schema in apps/shared and apps/backend/src/configuration/validate.ts.

Build and test:

make build-all
make test module=backend

See Tooling System for the full loader pattern.

Dependency management

# Sync all workspace deps (host IDE tree + backend/consumer runtime volumes)
make deps-install

# Update a specific package across the workspace
make pnpm-update package=stripe

# Update all packages
make pnpm-update-all

Never run pnpm install directly on the host. make deps-install runs inside Docker, uses the frozen lockfile when possible, and syncs both the host node_modules/ (for IDE types) and each service’s runtime volumes.

Runtime vs IDE dependencies: make deps-install syncs the host tree and both runtime volumes. Backend and consumer each run pnpm install on boot; after pulling new tooling-* packages, run make deps-install if consumer logs show TS2307 or MODULE_NOT_FOUND. For a full volume reset, use make deps-fix.

Dependency troubleshooting FAQ

Symptom	Fix
You changed dependencies in a `package.json`	`make deps-install`
Your IDE can’t resolve types	`make deps-install`
Backend or consumer logs `MODULE_NOT_FOUND` / `TS2307` on `tooling-*`	`make deps-fix`
You want the clean slate reset	`make fresh-start`

What’s next?

Tooling System — the loader pattern and how pluggable tools are swapped at runtime.
Configuration System — how the client config value drives which tool gets loaded.
TypeScript — tsconfig setup per package.

Getting Started

Architecture

Frontend

Deployment

Quality

Reference

Monorepo

Monorepo

Workspace layout

How packages reference each other

`apps/shared` — the contract layer

Adding a new tool implementation

Dependency management

Dependency troubleshooting FAQ

What’s next?

​Monorepo

​Workspace layout

​How packages reference each other

​apps/shared — the contract layer

​Adding a new tool implementation

​Dependency management

​Dependency troubleshooting FAQ

​What’s next?

Monorepo

Workspace layout

How packages reference each other

`apps/shared` — the contract layer

Adding a new tool implementation

Dependency management

Dependency troubleshooting FAQ

What’s next?