Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/reds-skywalker/Lightpress/llms.txt

Use this file to discover all available pages before exploring further.

The microservices/ directory is the core of the Lightpress backend. Each subdirectory is a self-contained Node.js service with its own package.json, Dockerfile, and environment configuration. Services communicate with each other through well-defined interfaces — either synchronous HTTP calls or asynchronous events — and are deployed independently so that a change to one service never requires a full-stack redeploy.

​
Service organization

Each service lives in its own directory under microservices/. This gives you clear ownership boundaries: one team or one pull request per service. 
microservices/
├── auth/
│   ├── src/
│   ├── package.json
│   ├── Dockerfile
│   └── .env.example
├── users/
│   ├── src/
│   ├── package.json
│   └── Dockerfile
├── billing/
│   ├── src/
│   ├── package.json
│   └── Dockerfile
└── notifications/
    ├── src/
    ├── package.json
    └── Dockerfile
The names above are illustrative. Your actual service names are determined by the subdirectories you add under microservices/. Follow the same structure for each: a src/ directory, a Dockerfile, and a .env.example.

​
Core services

Lightpress is designed around the bounded contexts common to SaaS products. Each service owns a single domain.

Auth service

Issues and validates JWTs. Handles sign-up, login, password reset, and token refresh. Every other service validates tokens against this service’s public key.

Users service

Manages user profiles, roles, and account settings. The auth service creates a user record here on sign-up; the client reads from here to populate the UI.

Billing service

Integrates with a payment provider (e.g., Stripe) to manage subscriptions, invoices, and plan changes. Emits events when a subscription status changes.

Notifications service

Sends email and in-app notifications. Subscribes to events from other services (e.g., a billing event triggers a receipt email) rather than being called directly.

​
Service communication patterns

Services use two communication patterns depending on whether the caller needs an immediate response.
Use direct HTTP calls when the caller must wait for a result — for example, the client asking the users service to return a profile.
// Inside a service — calling another service by its Docker Compose name
const response = await fetch('http://users-service:3001/users/me', {
  headers: { Authorization: req.headers.authorization },
});
const user = await response.json();
In production, inter-service calls go through an internal ALB or AWS App Mesh service discovery — not through the public-facing ALB. This keeps internal traffic off the public internet.
Keep synchronous calls for reads and immediate writes. Use events for side effects. This prevents cascading failures — if the notifications service is down, billing still works.

​
Independent deployability

Each service has its own Dockerfile and is built separately in the CI pipeline. You can update, scale, and roll back any single service without touching the others.
1

Build a single service image

docker build -t lightpress-auth ./microservices/auth
2

Push to Amazon ECR

aws ecr get-login-password --region us-east-1 | \
  docker login --username AWS --password-stdin \
  <account-id>.dkr.ecr.us-east-1.amazonaws.com

docker tag lightpress-auth \
  <account-id>.dkr.ecr.us-east-1.amazonaws.com/lightpress-auth:latest

docker push \
  <account-id>.dkr.ecr.us-east-1.amazonaws.com/lightpress-auth:latest
3

Deploy to ECS

Update the ECS service to pull the new image. The CloudFormation templates in infraestructure/cloudformation/ define the ECS task definitions for each service.
aws ecs update-service \
  --cluster lightpress-prod \
  --service auth-service \
  --force-new-deployment

​
Local vs production differences

In local development, Docker Compose orchestrates all services. Services find each other by their Compose service name (e.g., http://auth-service:3000).
  • No AWS credentials required for core functionality
  • Use LocalStack to emulate SQS, S3, and other AWS services locally
  • Hot-reload (e.g., nodemon) is enabled inside each service container
  • A single docker compose up starts every service and the client
# docker-compose.yml excerpt
services:
  auth-service:
    build: ./microservices/auth
    ports:
      - "3001:3000"
    env_file: ./microservices/auth/.env
  users-service:
    build: ./microservices/users
    ports:
      - "3002:3000"
    env_file: ./microservices/users/.env
In production, each service runs as an ECS task behind an Application Load Balancer. AWS manages container placement, health checks, and rolling deployments.
  • Services discover each other through AWS Cloud Map or the internal ALB
  • Secrets (database credentials, API keys) are stored in AWS Secrets Manager and injected as environment variables at runtime
  • Auto-scaling rules in CloudFormation scale each service’s task count independently based on CPU/memory metrics
  • CloudWatch collects logs from every container via the awslogs log driver
Staging mirrors production but runs in a separate AWS account or VPC. The same CloudFormation templates deploy to staging with different parameter values (smaller instance sizes, separate database). Use staging to validate a service before promoting to production.

​
Adding a new service

1

Create the service directory

mkdir -p microservices/my-service/src
2

Initialize a Node.js project

# Inside microservices/my-service/
npm init -y
npm install express
3

Add a Dockerfile

Follow the same multi-stage Dockerfile pattern used by the existing services: a builder stage that compiles TypeScript, and a lean runner stage that copies only the compiled output.
4

Register in Docker Compose

Add a service block in docker-compose.yml so the new service starts alongside the others during local development.
5

Add a CloudFormation task definition

Create or update a CloudFormation template in infraestructure/cloudformation/ to define the ECS task definition and service for production deployment.

Build docs developers (and LLMs) love

Get started for freeTalk to us