Developer Documentation
Architecture, API contracts, and contribution guidelines for ServiceCortex
Developer Documentation
Welcome to the ServiceCortex developer documentation. This is the internal reference for engineers building and maintaining the platform.
ServiceCortex is a Level 4 Modular Monolith built with Hexagonal Architecture on NestJS. The system comprises 30 domain modules, 147,831 lines of TypeScript, and a hybrid API strategy using GraphQL, REST, and WebSocket.
What you will find here
Architecture
System architecture, the Backend Constitution, module structure, event system, and API strategy. Start here if you are new to the codebase.
Contributing
Local development setup, coding standards, how to add a new module, and testing practices.
API Contracts
The @servicecortex/api-contracts package: Zod schemas for inputs and outputs, typed error codes, and shared enums.
Module Guides
Deep dives into individual domain modules — CRM, Jobs, Billing, Appointments, and Communications.
Quick orientation
| Layer | Purpose | Example |
|---|---|---|
apps/api | NestJS backend — all business logic | src/jobs/flows/job.flow.ts |
apps/web | Next.js primary frontend | Dashboard, CRM, scheduling UI |
apps/portal | Next.js client portal | Client-facing document signing, payments |
apps/marketing | Next.js marketing site | Public pages, lead capture |
apps/docs | Fumadocs documentation site | This site |
packages/api-contracts | Shared types, error codes, Zod schemas | JobsErrorCode, CreateJobInput |
packages/authz-core | Authorization engine | Permission definitions, role resolution |
packages/pricing-core | Pricing evaluation engine | Formula parsing, pricing rules |
packages/shared-types | Cross-package TypeScript types | Shared interfaces |
packages/shared-utils | Cross-package utilities | Common helpers |
Key numbers
- 30 Level 4 modules with hexagonal architecture
- 134 flow files (use case orchestrators)
- 85 repository adapters
- 60 domain policies (pure business rules)
- 68 HTTP controllers
- 35 GraphQL resolvers
- 15 event listeners
If you are onboarding, read the Architecture Overview first, then the Backend Constitution. Those two documents explain every decision in the codebase.