Backend Architecture

A high-level guide to the BizTech backend: a Serverless Framework monorepo running 19 microservices on AWS Lambda with DynamoDB.

Tech Stack

Project Structure

serverless-biztechapp-1/
├── index.js                  # Local dev proxy, spawns all 19 services
├── handler.js                # Shared entry point (re-exported per service)
├── serverless.common.yml     # Shared Serverless config (provider, plugins)
├── sls-multi-gateways.yml    # Orchestrates deployment of all services
├── config.dev.json           # Dev environment config
├── config.staging.json       # Staging environment config
├── config.prod.json          # Production environment config
├── constants/                # Shared constants (tables, indexes, emails)
├── lib/                      # Shared libraries (DB, helpers, email, search)
├── scripts/                  # One-off admin/migration scripts
├── docs/api.yml              # OpenAPI 3.0 specification
└── services/                 # 19 microservices
    ├── hello/                # Health check + shared infra export
    ├── events/               # Event CRUD
    ├── registrations/        # Registration management
    ├── members/              # Membership management
    ├── users/                # User accounts
    ├── payments/             # Stripe checkout
    ├── teams/                # Team management + judging
    ├── profiles/             # Public profiles
    ├── emails/               # Email template CRUD
    ├── investments/          # Kickstart funding
    ├── qr/                   # QR code scanning
    ├── quests/               # Quest/achievement system
    ├── quizzes/              # Personality quizzes
    ├── interactions/         # Connections + WebSocket wall
    ├── bots/                 # Discord + Slack integrations
    ├── prizes/               # Prize catalog
    ├── transactions/         # Point transactions
    ├── stickers/             # Real-time voting system
    └── btx/                  # Stock exchange simulation

How Services Work

Each service is a self-contained Serverless Framework project with its own serverless.yml that defines Lambda functions and their HTTP routes.

Service File Structure

services/events/
├── serverless.yml          # Function definitions + routes
├── handler.js              # Lambda handlers (exported functions)
└── helpers.js              # Service-specific business logic (optional)

Anatomy of a serverless.yml

service: biztechapp-events
frameworkVersion: "3"

# Import shared config (provider, plugins, IAM roles)
custom: ${file(../../serverless.common.yml):custom}
provider: ${file(../../serverless.common.yml):provider}
plugins: ${file(../../serverless.common.yml):plugins}

functions:
  eventsGet:
    handler: handler.get           # Points to the exported 'get' function
    events:
      - httpApi:
          path: /events/{eventId}/{year}
          method: get
          authorizer:
            name: cognitoAuthorizer   # Requires Cognito JWT

Anatomy of a Handler

Every handler follows the same pattern:

import helpers from "../../lib/handlerHelpers.js";
import db from "../../lib/db.js";
import { EVENTS_TABLE } from "../../constants/tables.js";

export const get = async (event) => {
  try {
    // 1. Extract parameters
    const { eventId, year } = event.pathParameters || {};

    // 2. Validate input
    if (!eventId) return helpers.missingIdQueryResponse();

    // 3. Business logic
    const result = await db.getOne(eventId, EVENTS_TABLE, { year: parseInt(year) });

    if (!result) return helpers.notFoundResponse("Event not found");

    // 4. Return response
    return helpers.createResponse(200, result);

  } catch (err) {
    console.error(err);
    return helpers.createResponse(err.statusCode || 502, err.message);
  }
};

Service Overview

For detailed endpoint documentation, see the API Reference.

Next Steps

• Shared Libraries: Database layer, handler helpers, email, search, and SNS modules
• Services & Patterns: Environment config, API Gateway, local dev, testing, code patterns, and how to add a new service