Repository Structure

A detailed breakdown of the Sustentus monorepo directory structure.

Root


sustentus/
├── apps/                   # Applications (see below)
├── packages/               # Shared packages (ui, services)
├── pipeline/               # The /pipeline delivery pipeline (ICM workspace)
├── .github/                # Labels, PR template, CI workflows
├── package.json            # Root workspace scripts
├── pnpm-workspace.yaml      # Workspace globs: apps/*, packages/*
├── turbo.json              # Turborepo task graph + caching
├── CLAUDE.md · CONVENTIONS.md   # Agent identity + canonical code rules
└── tsconfig.json

Applications


apps/
├── web/            # Main platform — Next.js 16, App Router + Turbopack, port 3000
│   ├── app/        # Routes, route handlers, (app) segments per persona
│   ├── components/ # Feature components (UI primitives come from @sustentus/ui)
│   ├── lib/        # Server-action helpers (zodToActionError, resolveActionContext, runActionBody)
│   └── AGENTS.md   # apps/web-specific rules
├── dashboards/     # Role-based dashboards — Next.js 16, port 3005 (local UI, Recharts)
├── marketing/      # Marketing site — Next.js 15, port 3001 (Clerk, waitlist, pricing)
├── docs/           # This Nextra site — app/business + app/technical
├── help/           # Help & support centre — Nextra
└── storybook/      # Storybook 10 — documents @sustentus/ui, port 3002

Packages


packages/
├── ui/             # @sustentus/ui — shared shadcn (New York) components
│   └── src/        # components + lib/utils (cn); barrel-exported from src/index.ts
└── services/       # @sustentus/services — business logic, DB, AI, email
    └── src/
        ├── db/             # Mongoose models, services, plugins, connection
        ├── ai/             # BRD agent + AI utilities (Vercel AI SDK)
        ├── email/          # Resend + React Email sending
        ├── notifications/  # Per-resource notifyX (persists to Mongo, publishes to Ably)
        ├── blob/           # Vercel Blob upload/download
        ├── linear/         # Linear error reporting
        ├── server/ · shared/ · types/ · utils/   # entrypoint barrels
        └── index.ts

@sustentus/services exposes scoped entrypoints — import the right one: ./server, ./shared, ./types, ./db, ./ai, ./email, ./blob, ./utils, ./linear-error. In apps/web, use /server and /shared (ESLint enforces this), never the root export.

Configuration

TypeScript — each package extends the root tsconfig.json; strict mode.
ESLint — root config enforces arrow functions, curly: all, type over interface, and the @sustentus/services import restrictions.
Prettier — root config; the Husky + lint-staged pre-commit hook auto-formats staged files.

Build artifacts (git-ignored)

.next/ — Next.js build cache (apps)
dist/ — package bundles (TSUP output for ui, services)
node_modules/ — dependencies