Scheduling Workbox System (sws2apps) API

Backend service for all sws2apps applications.

Requirements

• Node.js 24
• npm 11 or newer

Local development

Install the dependencies and create a local environment file:

npm install
cp .env.example .env

Review the values in .env before starting the API. The example configuration uses the local Firebase emulators and disables email delivery by default.

Start the development server with automatic reloads:

npm run dev

The API listens on port 8000 unless PORT is set to another valid port.

API contract

The dependency-free OpenAPI 3.1 contract documents the public HTTP interface. It currently covers public access, authentication, MFA, and all authenticated user account, congregation activity, and backup workflows. The congregation directory, application processing, meeting schedules, and visiting speaker workflows are also covered, along with invitation-based Pocket accounts, their cookie-authenticated workflows, global administration, and congregation administration. A contract test derives the route inventory from the Express route sources and fails when an implemented path or method differs from the documentation. When the server is running, Swagger UI is available at /api-docs and the raw contract is available at /api-docs/openapi.json.

API architecture

The versioned API is exposed under /api/v3. Preserve that public contract unless a change is explicitly documented as breaking.

New and migrated code follows this dependency direction:

routes -> controllers -> services -> repositories -> platform adapters

• Routes define paths, validation, authentication, and authorization.
• Controllers translate validated HTTP input into service calls and responses.
• Services own use cases and do not depend on Express request or response types.
• Repositories own persistence queries.
• Platform adapters wrap Firebase, email, logging, localization, and remote APIs.

Most application state is loaded into in-memory collections during startup. Treat those collections as caches and lookup indexes; creation, mutation, security, and cross-module workflows belong in services.

Source imports use the native Node.js subpath aliases defined in package.json:

• #config/* for validated application configuration.
• #domain/* for domain-neutral types and rules.
• #http/* for HTTP routing, middleware, and response handling.
• #modules/* for feature-module public APIs.
• #platform/* for external-system adapters.

Import feature business contracts through the module's index.ts rather than reaching into internal files. HTTP composition imports the module router through its dedicated routes.ts entrypoint.

Repository layout

• src/bootstrap: startup support used only while initializing the application.
• src/config: validated environment and server configuration.
• src/domain: framework-independent rules and reusable domain primitives.
• src/http: Express composition, middleware, validation, and response handling.
• src/modules: feature-owned routes, controllers, services, repositories, and types.
• src/platform: adapters for Firebase, email, logging, localization, encryption, and remote APIs.
• src/types: global declaration augmentation and genuinely cross-cutting record types.
• test: tests organized to mirror the source concerns.
• docs: architecture decisions and the versioned OpenAPI contract.

Module map

• administration: system administrator operations.
• auth: authentication, session creation, and passwordless sign-in.
• backups: backup validation, conflict detection, and persistence workflows.
• congregations: congregation entities, membership, creation, and applications.
• congregation-administration: congregation-scoped administration and security.
• feature-flags: flag lifecycle, assignments, and rollout evaluation.
• installations: application installation registration and persistence.
• meetings: schedule publication and visiting-speaker coordination.
• mfa: multi-factor enrollment and verification.
• pockets: Pocket authentication and user workflows.
• public-api: unauthenticated statistics transport.
• users: user accounts, sessions, membership, activity, and backups.

Verification

For source changes, run:

npm run build
npm run lint
npm test

The default test command uses Node.js's built-in test runner and does not require Firebase emulators. The Firebase integration suite requires Java 21; its script downloads the pinned Firebase CLI, starts isolated Authentication, Firestore, and Storage emulators for the organized-local project, and shuts them down afterward:

npm run test:firebase

No Firebase login or remote project is required for these tests. CI runs the build, lint, standard tests, and Firebase integration suite for pull requests and pushes to main. The same checks must pass before the production deployment can begin.

Localization

We support the localization of the email message generated by this API, based on UI language selected by the user. The translation process is handled on Crowdin. To help with localization, please read the TRANSLATION guide.