Services

The eTeamups Platform is composed of five in-repo microservices plus two frontend applications that live in separate repositories. Each service is a standalone Express application bootstrapped by the shared libs/server library.

Service Bootstrap Pattern

All HTTP services share the same startup flow:

1. libs/server/src/run.ts reads a server.config.*.ts file passed as a CLI argument.
2. It creates a Server instance with the config (process name, port, middleware list).
3. The Server class creates an Express app, registers a rate limiter (100 req / 15 min), JSON body parsing, and health-check endpoints (/_ping, /health).
4. It dynamically imports and instantiates each middleware listed in the config. Middleware classes extend BasicMiddleware and register their own Express routers.
5. The server starts listening on 0.0.0.0:<port>.

Auth Service

Responsibilities

• Passwordless authentication using email-based OTP with PKCE.
• JWT access and refresh token generation.
• Token refresh endpoint.
• API version reporting.

Middleware Chain

Endpoints

POST /login

Initiates the authentication flow.

Request body (validated by Zod):

{
  "emailAddress": "user@example.com",
  "codeChallenge": "<base64url-encoded SHA-256 hash, 43-128 chars>"
}

Flow:

1. Looks up an active account by email in MongoDB.
2. Generates an 8-digit OTP and stores it with the code challenge.
3. Enqueues an email job via MessageQueue to deliver the OTP.
4. Returns JWT access token (15-day expiry) and refresh token (7-day expiry).

Response (200):

{
  "accessToken": "<jwt>",
  "refreshToken": "<jwt>"
}

POST /verify

Verifies the OTP and the PKCE code verifier.

Request body:

{
  "otp": "12345678",
  "codeVerifier": "<original code verifier string, 43-128 chars>"
}

Requires: Authorization: Bearer <accessToken> header (the token returned from /login).

Flow:

1. Decodes the JWT to extract the email address.
2. Looks up the account and a matching pending, non-expired OTP record.
3. Verifies that SHA256(codeVerifier) matches the stored codeChallenge.
4. Marks the OTP as used and activates the account.

Response (200):

{
  "error": false,
  "message": "OTP verified successfully"
}

POST /token

Exchanges a valid refresh token for a new access/refresh token pair.

Requires: Authorization: Bearer <refreshToken> header.

Response (200):

{
  "accessToken": "<jwt>",
  "refreshToken": "<jwt>"
}

GET /version

Returns the current API version string.

Response (200): v0.0.1

Profile Service

Responsibilities

• User profile management (the “me” endpoint).
• Team CRUD operations.
• Teammate CRUD operations within teams.

Middleware Chain

Endpoints

Me (User Profile)

Teams

Teammates

Organisation Service

Responsibilities

• Organisation CRUD.
• Account management within organisations.
• Master data catalogues: countries, industries, functions, education levels, study majors, locations, skills.

Middleware Chain

Endpoints

Each master data resource follows a standard CRUD pattern:

The available resources are:

Media Service

Responsibilities

• Serving media assets (images, files) to frontend clients.
• Media uploads are stored in a Docker volume (media_uploads mapped to /app/uploads).
• Nginx is configured with a larger client_max_body_size (100 MB) for the /media path.

Middleware Chain

Endpoints

Message Queue Worker

Responsibilities

• Processes jobs from the email-queue in Redis.
• Sends emails via the Resend API using EmailClient.send_email_now().
• Handles graceful shutdown on SIGTERM and SIGINT.

How It Works

The worker is a standalone Node.js process (not an Express server). It creates a BullMQ Worker instance that:

1. Connects to Redis using the configured host and port.
2. Listens for jobs on the email-queue.
3. For each job, parses the job data and calls EmailClient.send_email_now(body, to).
4. On success, marks the job complete. On failure, BullMQ retries with exponential backoff.

See Message Queue for full details.

Admin Portal (Separate Repository)

The Admin Portal is a frontend application deployed as a Docker container alongside the platform services. It depends on all five backend services being healthy before starting. It is served through Nginx at admin.zeswa.com.

Zeswa Hub (Separate Repository)

The Zeswa Hub is the public-facing frontend application. Like the Admin Portal, it runs in its own container and is proxied through Nginx. It also depends on all backend services being healthy.

Service Dependency Graph

Resource Limits (Docker)

Each container has configured CPU and memory limits: