🛠️ Weekend Project: Advanced Backend & Apis

The Brief

You're building the backend API for a digital marketplace — a site where people buy and sell digital goods (e-books, design templates, small software tools). It's the perfect capstone because it touches every advanced topic in this module: several independent domains, money changing hands, spiky traffic during sales, and a real need to keep costs down when nobody's buying.

💡 How to use this lesson. Don't try to build all six services. The goal of a weekend project is a complete, working slice — one service, shipped and tested — plus a clear understanding of how the whole system fits together. You'll pick your slice in Milestone 1.

Functionally, the full marketplace needs to handle six domains. You'll design for all of them and build one:

The Milestone Map

The project is organized into five milestones. Each one has a clear deliverable, so you always know where you are and what "done" means. They loosely follow George Pólya's timeless problem-solving loop — understand, plan, do, review — which keeps you from coding before you know what you're building.

Milestone 1 — Understand & Scope

Deliverable: a one-page scope note that names your chosen service, its endpoints, and its non-functional targets.

Resist the urge to open your editor. First, get crisp on the problem. Answer these before writing any code:

To ground the design, sketch the primary buyer journey. Even a rough sequence diagram exposes the data each service needs and where they hand off to each other:

Write down, in a sentence each, your non-functional targets. These become the yardstick you'll measure against in Milestone 5, so make them specific and testable.

Milestone 2 — Architecture & Plan

Deliverable: an architecture diagram and a chosen tech stack for your service.

Here's the target system. Every domain becomes an independent service behind one API gateway, each owning its own data store. Your weekend focuses on one of these boxes — but designing the whole picture keeps your service's boundaries honest.

A sensible default stack

You can build this on any cloud, but a fully managed serverless stack keeps the weekend focused on your code, not on running servers. One reasonable set of choices:

Scaffold the project so all your services share one deployable repo:

# Create and initialise the project
mkdir digital-marketplace-api && cd digital-marketplace-api
npx serverless create --template aws-nodejs

# One directory per domain
mkdir -p services/{auth,products,orders,reviews,search,analytics}

# Shared runtime + dev dependencies
npm init -y
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb jsonwebtoken uuid joi
npm install --save-dev serverless-offline serverless-iam-roles-per-function

Milestone 3 — Build the Core

Deliverable: one service running locally with serverless offline, then deployed to AWS and reachable over HTTP.

We'll walk through the Products service as the reference build. It's the best first slice: no payment complexity, but it still exercises validation, auth, a database write, and event publishing.

The infrastructure (serverless.yml)

Declare the runtime, the products table, and the one function that creates a product. Everything is described as code, so your teammate — or future you — can reproduce it exactly:

service: digital-marketplace-api
frameworkVersion: '3'

provider:
  name: aws
  runtime: nodejs20.x
  stage: ${opt:stage, 'dev'}
  region: ${opt:region, 'us-east-1'}
  environment:
    PRODUCTS_TABLE: ${self:service}-products-${self:provider.stage}
  httpApi:
    cors: true

plugins:
  - serverless-offline
  - serverless-iam-roles-per-function

functions:
  createProduct:
    handler: services/products/create.handler
    events:
      - httpApi:
          path: /products
          method: post
    iamRoleStatements:
      - Effect: Allow
        Action: [dynamodb:PutItem]
        Resource: !GetAtt ProductsTable.Arn

resources:
  Resources:
    ProductsTable:
      Type: AWS::DynamoDB::Table
      Properties:
        TableName: ${self:provider.environment.PRODUCTS_TABLE}
        BillingMode: PAY_PER_REQUEST
        AttributeDefinitions:
          - AttributeName: id
            AttributeType: S
          - AttributeName: sellerId
            AttributeType: S
        KeySchema:
          - AttributeName: id
            KeyType: HASH
        GlobalSecondaryIndexes:
          - IndexName: SellerIdIndex
            KeySchema:
              - AttributeName: sellerId
                KeyType: HASH
            Projection:
              ProjectionType: ALL

The create handler

Notice the shape every good Lambda handler shares: authenticate, validate, do the work, respond — with each failure mode mapped to the right HTTP status. Never let a raw exception leak to the caller.

// services/products/create.js  — AWS SDK v3
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { DynamoDBDocumentClient, PutCommand } from '@aws-sdk/lib-dynamodb';
import { randomUUID } from 'node:crypto';
import Joi from 'joi';

const db = DynamoDBDocumentClient.from(new DynamoDBClient({}));

const schema = Joi.object({
  title: Joi.string().max(120).required(),
  description: Joi.string().max(5000).required(),
  price: Joi.number().positive().required(),
  category: Joi.string().required(),
  files: Joi.array().items(
    Joi.object({
      name: Joi.string().required(),
      type: Joi.string().required(),
      url: Joi.string().uri().required(),
    })
  ).min(1).required(),
});

const json = (statusCode, body) => ({
  statusCode,
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(body),
});

export const handler = async (event) => {
  try {
    // 1. Authenticate — the gateway put the verified claims here
    const sellerId = event.requestContext?.authorizer?.jwt?.claims?.sub;
    if (!sellerId) return json(401, { error: 'Unauthorized' });

    // 2. Validate
    const { error, value } = schema.validate(JSON.parse(event.body));
    if (error) return json(400, { error: 'Validation Error', details: error.details });

    // 3. Do the work
    const now = new Date().toISOString();
    const product = {
      id: randomUUID(),
      sellerId,
      ...value,
      status: 'active',
      createdAt: now,
      updatedAt: now,
    };
    await db.send(new PutCommand({ TableName: process.env.PRODUCTS_TABLE, Item: product }));

    // 4. Respond
    return json(201, product);
  } catch (err) {
    console.error('createProduct failed', err);
    return json(500, { error: 'Internal Server Error' });
  }
};

Run it, then ship it

# Run the whole stack on your laptop
npx serverless offline

# In another terminal, hit the local endpoint
curl -X POST http://localhost:3000/products \
  -H 'Content-Type: application/json' \
  -d '{"title":"Icon Pack","description":"200 SVGs","price":9,"category":"design","files":[{"name":"pack.zip","type":"application/zip","url":"https://example.com/pack.zip"}]}'

# When it works locally, deploy to the cloud
npx serverless deploy --stage dev

{
  "id": "6f1c...",
  "sellerId": "auth0|...",
  "title": "Icon Pack",
  "price": 9,
  "status": "active",
  "createdAt": "2026-08-01T..."
}

When you see that 201, Milestone 3 is done: you have a real, deployed, authenticated endpoint that writes to a database. Everything after this is making it resilient.

Milestone 4 — Add the Advanced Patterns

Deliverable: at least one advanced pattern implemented and demonstrably working (show it failing gracefully, not just succeeding).

Pick one of the three patterns below to implement this weekend. Each solves a distinct distributed-systems problem. Read all three so you understand the trade-offs, then go deep on one.

Pattern A — CQRS (separate reads from writes)

Command Query Responsibility Segregation means the code that changes data and the code that reads it are separate, and can even use different data stores. Products are written to DynamoDB (great for single-item writes) but read through a search index (great for full-text queries). A write publishes an event; a small indexer keeps the read side up to date.

// services/products/create.js — emit an event after the write (CQRS write side)
import { EventBridgeClient, PutEventsCommand } from '@aws-sdk/client-eventbridge';
const bus = new EventBridgeClient({});

await bus.send(new PutEventsCommand({
  Entries: [{
    Source: 'marketplace.products',
    DetailType: 'ProductCreated',
    Detail: JSON.stringify(product),
    EventBusName: 'default',
  }],
}));
// A separate indexer Lambda listens for ProductCreated and writes to the search index.
// The read side (search.js) then queries the index, never the write DB.

Pattern B — Saga (safe multi-step transactions)

An order spans several services — charge the card, grant access, notify the buyer. You can't wrap that in one database transaction. A saga runs each step as its own local transaction and defines a compensating action to undo it if a later step fails. AWS Step Functions is a natural fit: each state is a Lambda, and Catch blocks route failures to the rollback path.

{
  "Comment": "Order processing saga",
  "StartAt": "ProcessPayment",
  "States": {
    "ProcessPayment": {
      "Type": "Task",
      "Resource": "${ProcessPaymentFunction.Arn}",
      "Next": "GrantAccess",
      "Catch": [{ "ErrorEquals": ["PaymentFailedError"], "Next": "FailOrder" }]
    },
    "GrantAccess": {
      "Type": "Task",
      "Resource": "${GrantAccessFunction.Arn}",
      "Next": "NotifyBuyer",
      "Catch": [{ "ErrorEquals": ["AccessError"], "Next": "RefundPayment" }]
    },
    "NotifyBuyer": { "Type": "Task", "Resource": "${NotifyBuyerFunction.Arn}", "Next": "CompleteOrder" },
    "CompleteOrder": { "Type": "Task", "Resource": "${CompleteOrderFunction.Arn}", "End": true },
    "RefundPayment": { "Type": "Task", "Resource": "${RefundPaymentFunction.Arn}", "Next": "FailOrder" },
    "FailOrder": { "Type": "Task", "Resource": "${FailOrderFunction.Arn}", "End": true }
  }
}

Pattern C — Circuit breaker (stop cascade failures)

When a dependency like the search index gets slow or unavailable, hammering it makes things worse. A circuit breaker counts recent failures; once it trips it fails fast (or returns a fallback) for a cooldown period, then cautiously tests the water again. Three states: CLOSED (normal), OPEN (failing fast), and HALF-OPEN (probing recovery).

// lib/circuitBreaker.js — a small, dependency-free breaker
export class CircuitBreaker {
  constructor({ failureThreshold = 5, resetTimeout = 30000, fallback } = {}) {
    this.failureThreshold = failureThreshold;
    this.resetTimeout = resetTimeout;
    this.fallback = fallback;
    this.state = 'CLOSED';
    this.failures = 0;
    this.nextAttempt = 0;
  }

  async exec(fn, ...args) {
    if (this.state === 'OPEN') {
      if (Date.now() < this.nextAttempt) {
        if (this.fallback) return this.fallback(...args);
        throw Object.assign(new Error('Circuit open'), { name: 'CircuitBreakerError' });
      }
      this.state = 'HALF-OPEN'; // time to probe
    }
    try {
      const result = await fn(...args);
      this.failures = 0;
      this.state = 'CLOSED';
      return result;
    } catch (err) {
      this.failures++;
      if (this.state === 'HALF-OPEN' || this.failures >= this.failureThreshold) {
        this.state = 'OPEN';
        this.nextAttempt = Date.now() + this.resetTimeout;
      }
      throw err;
    }
  }
}

// services/products/search.js — read side guarded by the breaker + a DB fallback
import { CircuitBreaker } from '../../lib/circuitBreaker.js';

const breaker = new CircuitBreaker({
  failureThreshold: 3,
  resetTimeout: 20000,
  fallback: scanDynamoForProducts, // degrade to a simple DB scan
});

export const handler = async (event) => {
  const term = event.queryStringParameters?.q ?? '';
  const products = await breaker.exec(searchOpenSearch, term);
  return {
    statusCode: 200,
    headers: { 'Content-Type': 'application/json', 'Cache-Control': 'max-age=60' },
    body: JSON.stringify({ products }),
  };
};

Milestone 5 — Harden & Reflect

Deliverable: a short reflection note scoring your build against your Milestone 1 targets, plus at least two concrete hardening steps applied.

Pólya's last step is the one beginners skip: look back. Walk your build through four lenses and note both what you did and what you'd do next.

Security

• Done well: managed auth (Cognito), input validation on every handler, errors that never leak internals, least-privilege IAM per function.
• Next: rate limiting at the gateway, a WAF for common attacks, encryption of sensitive fields at rest.

Performance

• Done well: a read side backed by a search index, short-lived caching headers, indexes matched to your query patterns.
• Next: edge caching with a CDN, right-sized Lambda memory, pagination on every list endpoint.

Cost

• Done well: everything scales to zero; DynamoDB on-demand means no idle capacity to pay for.
• Next: budget alerts, provisioned capacity only where load is predictable, tiered storage for large files.

Resilience

• Done well: your chosen pattern (circuit breaker fallback, or saga compensations) keeps a partial failure from becoming a total outage.
• Next: dead-letter queues for failed events, structured logging with correlation IDs, an alarm on saga failure rate.

Completion Checklist

You've finished the weekend project when every box below is ticked. Print it, or copy it into your notes:

What Good Looks Like

Use this rubric to judge your own build honestly. Aim for "Solid" across the board before reaching for "Excellent" in any one row.

Summary & Quiz

📚 Further Reading

• microservices.io — Microservices pattern catalog
• Martin Fowler — CQRS
• AWS — The Saga pattern with Lambda & Step Functions
• Serverless Framework documentation

🚀 What's Next?

You've built and hardened a backend — the natural next question is how to prove it keeps working as it grows. Module 27 opens with the principles of software testing: what to test, at what level, and why a good test suite is what lets you refactor and ship with confidence.