Project Structure

The eTeamups Platform is a TypeScript monorepo that contains multiple backend microservices, shared libraries, email templates, infrastructure configuration, and operational scripts in a single repository.

Root Directory Layout

eteamups-platform/
  services/            # Microservice source code
  libs/                # Shared libraries used by all services
  emails/              # Email templates (React Email, MJML, compiled HTML)
  nginx/               # Nginx reverse proxy configuration
  docker/              # Dockerfiles for containerised builds
  scripts/             # Operational and deployment shell scripts
  swagger/             # Generated OpenAPI specifications
  docs/                # Project documentation
  ssl/                 # Generated SSL certificates (git-ignored)
  logs/                # Runtime log files (git-ignored)
  dist/                # Compiled JavaScript output (git-ignored)
  package.json         # Root package manifest with all npm scripts
  tsconfig.json        # TypeScript compiler configuration
  docker-compose.local.yml   # Docker Compose for local development
  docker.local.env     # Reference environment variables for local dev
  instrumentation.ts   # OpenTelemetry instrumentation bootstrap

services/ – Microservices

Each directory under services/ is a self-contained microservice. Every service follows the same internal structure.

Service List

Internal Service Layout

Each runnable service (auth, profile, organisation, media) follows this pattern:

services/{name}/
  src/
    config/
      server.config.dev.ts     # Development configuration
      server.config.prod.ts    # Production configuration
    middleware/
      {Feature}Middleware.ts   # Route-mounting middleware classes
    modules/
      routes/
        {feature}/
          {action}.ts          # Individual route handlers
      error_messages/
        {feature}.ts           # Centralised error message constants
      utils/
        Assert.ts              # Assertion helpers for request validation
    index.ts                   # (optional) barrel exports

Example – Auth service modules:

services/auth/src/modules/routes/
  login/login.ts       # POST login (request OTP)
  verify/verify.ts     # POST verify OTP
  token/token.ts       # Token refresh / management
  version/version.ts   # Version endpoint

Example – Organisation service modules:

services/organisation/src/modules/routes/
  account/             # CRUD for accounts
  country/             # CRUD for countries
  educationLevel/      # CRUD for education levels
  function/            # CRUD for job functions
  industry/            # CRUD for industries
  location/            # CRUD for locations
  organisation/        # CRUD for organisations
  skill/               # CRUD for skills
  study-major/         # CRUD for study majors

Config-Driven Server Startup

Services do not have their own main() entry point. Instead, startup is handled by the shared server framework:

1. libs/server/src/run.ts reads a config file path from CLI arguments.
2. The config file is loaded via ConfigFileResolver, which supports .ts, .js, and .json files.
3. The config file exports an IServerConfig object:

// IServerConfig interface
interface IServerConfig {
  processName: string;       // Display name shown in the startup banner
  port: number;              // TCP port the service listens on
  baseUrl: string;           // Base URL for the service
  logLevel?: "debug" | "info";
  middlewares?: IMiddleware[];// Middleware classes to auto-load
}

interface IMiddleware {
  path: string;              // Relative path from project root to middleware file
}

4. A Server instance is created with the config. It sets up Express with rate limiting, JSON body parsing, URL encoding, health endpoints (/_ping and /health), and then dynamically imports and instantiates each middleware class listed in the config.

Example config (services/auth/src/config/server.config.dev.ts):

const config: IServerConfig = {
  processName: "Auth Server",
  port: 9000,
  baseUrl: "http://localhost",
  logLevel: "debug",
  middlewares: [
    { path: "services/auth/src/middleware/AuthMiddleware.ts" },
    { path: "services/auth/src/middleware/TokenMiddleware.ts" },
    { path: "services/auth/src/middleware/VerifyMiddleware.ts" },
  ]
};

Each middleware extends BasicMiddleware (from services/common/) and registers Express routes on the app instance in its constructor.

The Store – Data Access Layer

services/store/ is not a runnable service. It is the shared data layer used by all services.

services/store/src/
  dto/                # TypeScript interfaces for each entity
    IAccount.ts
    IOtp.ts
    ITeam.ts
    ...
  schema/             # Mongoose schema definitions
    AccountSchema.ts
    OtpSchema.ts
    TeamSchema.ts
    ...
  model/              # Model classes extending BaseModel
    AccountModel.ts
    OtpModel.ts
    TeamModel.ts
    BaseModel.ts      # Abstract base class
    ...
  seed/               # Seed data files (.js)
    accounts.js
    countries.js
    industries.js
    skills.js
    ...

BaseModel Pattern

All model classes extend the generic BaseModel<T> abstract class, which wraps common Mongoose operations:

The BaseModel constructor automatically triggers the MongoDB connection singleton (MongooseClient.getInstance()) so that any model usage ensures a live database connection.

libs/ – Shared Libraries

Shared code is organised into focused libraries under libs/.

Logger

The Logger class (libs/utility/src/Logger.ts) wraps Winston and provides static methods: log, info, error, debug, warn. Logs are written to:

• Console (with colour and timestamp formatting)
• error.log (error-level entries only)
• combined.log (all levels)
• OpenTelemetry transport (for forwarding to SigNoz or other OTLP backends)

The log level is controlled by the LOG_LEVEL environment variable (defaults to info).

MessageQueue

The MessageQueue class (libs/message-queue/MessageQueue.ts) is a singleton that wraps a BullMQ Queue named "email-queue". It connects to Redis using REDIS_HOST and REDIS_PORT from the environment. It provides addJob and getJob methods. The worker process is started separately via npm run message-queue.

emails/ – Email Templates

emails/
  admin_otp.tsx       # React Email component for OTP emails
  html/               # Compiled HTML templates (used at runtime)
  mjml/               # MJML source templates (compiled to HTML)

The platform uses three email authoring approaches:

1. React Email (.tsx files) – Component-based email templates for the development workflow. Run npm run email:dev to start a preview server on port 3010.
2. MJML – Responsive email markup compiled to HTML.
3. Compiled HTML – Final templates in emails/html/ are used at runtime by EmailUtility.compile(), which performs {{variable}} substitution.

nginx/ – Reverse Proxy

nginx/
  nginx.conf           # Production Nginx main config
  nginx.local.conf     # Local development Nginx main config
  conf.d/
    local.conf         # Local server blocks (HTTP redirect + HTTPS proxy)
    eteamups.conf      # Production server blocks

The local Nginx configuration (conf.d/local.conf) acts as an API gateway:

Since Nginx runs in a Docker container but the services run on the host, host.docker.internal is used to route traffic from the container to the host machine.

docker/ – Dockerfiles

docker/
  Dockerfile.auth           # Auth service image
  Dockerfile.profile        # Profile service image
  Dockerfile.organisation   # Organisation service image
  Dockerfile.media          # Media service image
  Dockerfile.message-queue  # Message queue worker image
  Dockerfile.nginx          # Nginx reverse proxy image

Each service Dockerfile compiles TypeScript to JavaScript and runs the production entry point (e.g., npm run auth:prod). Production builds use NODE_OPTIONS=--max-old-space-size=512 and -r ./dist/instrumentation.js for OpenTelemetry auto-instrumentation.

scripts/ – Operational Scripts

The scripts/ directory contains shell scripts for development, deployment, and operations:

swagger/ – OpenAPI Specifications

Generated OpenAPI specifications are stored in swagger/:

swagger/
  zeswa-hub-open-api.json
  zeswa-hub-open-api.yaml

Regenerate them with:

npm run swagger:generate

This runs scripts/generate-swagger.ts, which introspects the running service routes and produces the spec.