Architecture

The big picture

 Browser                          One VPS · Docker Compose
 ───────                          ────────────────────────
 Website  (apps/web)  ─┐
 Panel    (apps/app)  ─┼─▶ Caddy (TLS, headers) ─▶ Next.js 15 ──withOrg(orgId)──▶ PostgreSQL 16
 Portals  (apps/app)  ─┘                              │                          (row-level security)
                                                      ├──▶ S3 file storage (SeaweedFS locally)
                                                      └──▶ Mail · Stripe · FMCSA (behind interfaces)
                                 Worker (pg-boss) ─────────────────────────────▶ PostgreSQL

The website and the panel are two separate Next.js applications that share one public address: the website proxies /app to the panel, and Caddy does the same in production. A visitor never sees a second port or host.

The repository

The stack

Do not add alternatives to these.

How a page reads

export default async function Page() {
  const access = await guardPage('loads');   // permission check + the org's dataset
  const rows = await loadBoard(access);       // apps/app/lib/data/<module>.ts
  return <LoadBoard rows={rows} />;
}

guardPage(module) checks the signed-in user's permission on the server (and writes security.access_denied if refused), then loads the org's data for the request (lib/data/dataset.ts → lib/demo/store.ts ds()). The calculations in lib/demo/* (risk, aging, desks, reports) read that dataset, so screens get real data in the shape they already use.

How a save writes

Every write is a server action in _actions.ts next to its page, wrapped in runAction(), always in this order:

requireAccess(module, action)          // permission, on the server
  → schema.parse(input)                // Zod
  → rule from packages/core            // throw RuleError with a plain-words message
  → withOrg(orgId, async (db) => {
      ...writes
      await writeAudit(db, actor, {...})
      await notify(db, to, {...})
    })
  → revalidatePath(...)

runAction() turns a refusal into a message the form shows. Details on Building a module.

Tenancy

Each brokerage is an Org. Every tenant table has an orgId column. withOrg(orgId, fn) opens a transaction that sets the org for Postgres row-level security and adds orgId to every Prisma query; creates never pass orgId (it defaults from the session setting). See Your data for the user-facing version.

The database

About 50 Prisma models, including Org, User, Role, PortalUser, Customer, Carrier, FactoringCompany, Load, LoadStop, LoadLeg, Charge, Quote, Appointment, LoadFeedEntry, Invoice, Advance, DebitCreditNote, CreditRequest, PayableRequest, ExpenseRow, Commission, Document, DeliveryOrder, ArrivalNotice, Attachment, AuditEvent, Notification, PortalSubmission, PortalPermission, Integration, UserPreference, Draft, and the SaaS tables (plans, billing events, platform audit). The schema is in packages/db/prisma/schema.prisma.

Related

• Local setup
• Building a module
• Security controls