Services Package

@sustentus/services holds the platform’s server-side business logic — database access, AI, email, notifications, and shared utilities. It is consumed by apps/web (and other apps) through scoped entrypoints, never a single root import.

Overview

Entrypoints (import the right one)

import { … } from "@sustentus/services/server";   // DB connections, server-only logic
import { … } from "@sustentus/services/shared";   // isomorphic utilities + types
import { … } from "@sustentus/services/db";        // models + db services
import { … } from "@sustentus/services/ai";        // BRD agent + AI utilities
import { … } from "@sustentus/services/email";     // Resend + React Email sending
import { … } from "@sustentus/services/blob";      // Vercel Blob upload/download
import { … } from "@sustentus/services/utils";     // general helpers
import { … } from "@sustentus/services/types";     // shared types
import { … } from "@sustentus/services/linear-error"; // error reporting to Linear

In apps/web, use /server and /shared (ESLint enforces this) — never the root @sustentus/services.

Source structure

packages/services/src/
├── db/             # Mongoose models, db services, plugins, connection cache
├── ai/             # BRD agent (brd/), config, AI utilities
├── email/          # Resend client + React Email templates
├── notifications/  # Per-resource notifyX (persist to Mongo, publish to Ably)
├── blob/           # Vercel Blob helpers
├── linear/         # Linear error reporting
├── server/ · shared/ · types/ · utils/   # entrypoint barrels
└── index.ts

AI

./ai contains the runtime AI built on the Vercel AI SDK:

• BRD agent (ai/brd/) — a tool-loop agent that qualifies a customer’s need into a business-requirements document through a guided conversation. Used by apps/web.
• Expert-fit scoring (db/services/matching/) — generateObject scoring of expert↔lead fit.

Models are routed through the AI Gateway (anthropic/claude-haiku-4.5).

Notifications

A per-resource architecture. External callers use the notifyX functions exported from @sustentus/services/server (e.g. notifyBidSubmitted, notifyInvoicePaid, notifyServiceLeadCsatRequested). These persist a notification to MongoDB and publish it to Ably for real-time delivery. The notifications/core/** primitives are internal — never imported from outside the package. Full contract: packages/services/AGENTS.md.

Development

pnpm services:dev      # TSUP watch mode
pnpm services:build    # build to dist/

Apps pick up changes automatically via the workspace link once the package is built.

Learn more

• UI package · Repository structure
• Technology stack