Server Common
server-common is the server runtime foundation shared by all server entry points (API, hook, job). It contains the bootstrap logic, configuration loading, dependency wiring, and shared infrastructure helpers. It defines how the server starts and executes, not what the application does.
On This Page
- Purpose
- Design Principles
- File Organization
- Standard Files
- Connection Lifecycle in the Loader
- Boundary Rules
- Mental Model
- Further Reading
Purpose
- Provide the server runtime foundation for all server entry points (API, hook, job)
- Hold bootstrap logic, configuration loading, dependency wiring, shared infrastructure helpers, static fonts, and static data files
- Define how the server starts, initializes, and executes - not what the application does
- All server modules may depend on
server-common, butserver-commonmust never depend on domain or business logic
Design Principles
| Principle | Detail |
|---|---|
| No business or domain logic | Belongs in server-service |
| No entity-specific workflows | Belongs in server-service |
| Infrastructure-first | Concerned with HOW the server runs |
| Execution-context-aware | Same code works in Docker and Lambda |
| Deterministic and predictable initialization | No surprises on cold start |
| Explicit dependency loading and injection | Everything goes through Lib |
| One-time initialization where possible | Heavy work happens once, not per request |
| Reusable across APIs, hooks, jobs, workers | Single foundation for every entry point |
| Safe in multiple execution environments | Docker, Lambda, cron, workers |
File Organization
Directory: src/server/common/
File names are role-based, not feature-based. There is no user.js here - users live in model/, controller/, and service/.
Standard Files
| File | Role | Detail |
|---|---|---|
handler.js | Runtime Entry Handler | First executable entry point (e.g., Lambda handler). Standalone - no shared dependencies. Executed before the project loader |
config.js | Configuration File | Static configuration defaults and constants. Default environment values. No process.env reads |
loader.js | Loader / Bootstrap | Loads configuration (static + environment overrides), initializes shared dependencies (helpers, SDKs, clients), exposes the shared Lib and Config containers. Full detail in server-loader.md |
functions.js | Shared Execution Helpers | Standardizes execution patterns across APIs and services. Wraps request initialization and response formatting. Holds reusable constants, enums, and shared definitions. Example: successResponse(data), errorResponse(error) |
auth.js | Auth Module | Validates API authentication (API keys, secrets, cookies). Used by externally exposed endpoints (APIs, hooks). Decides API scope: public, protected, admin |
data/ | Static Data Files | Static JSON data files used by the application |
font/ | Static Font Files | Font files used by the application |
Connection Lifecycle in the Loader
The composition root loads helper-instance into Lib once. Each load creates an independent process cleanup queue. Loading it more than once splits registrations across queues and makes shutdown incomplete.
The entry point supplies the runtime policy when it calls the loader:
| Runtime profile | CLOSE_ON_CLEANUP | Effect |
|---|---|---|
| Persistent process | false | Shared resources stay open across requests and close during graceful shutdown |
| Request-isolated process | true | Shared resources close during runInstanceCleanup |
The composition root reads the environment and converts it into explicit configuration. Modules receive configuration through the loader and do not detect the platform themselves. See Connection Lifecycle for the full doctrine.
Boundary Rules
server-common must NOT
- Contain business or domain logic
- Reference entities (user, order, message, ...)
- Implement API endpoints
- Implement cron or job logic directly
- Call into
server-service,server-controller, orserver-interfaces
Allowed dependencies
catalog-corecatalog-server- External SDKs and libraries
Disallowed dependencies
- Client code
- Client helper modules
Mental Model
A simple test for whether a piece of code belongs in server-common:
| Question | Lives in |
|---|---|
| "How does the server start and safely execute?" | server-common |
| "What does the application do?" | server-service |
| "How is this exposed?" | server-interfaces |
If the answer touches the domain (users, orders, surveys, ...), it does not belong in server-common.
Further Reading
- Server Loader - the full bootstrap and dependency injection contract
- Server Interfaces - how the standardized request/response shapes are wired
- Connection Lifecycle - three lifetimes, two teardown scopes, the deployment rule
- Server Service Modules - where the business logic actually lives
- Architectural Philosophy - the high-level rules