Tu Cielo de Noche — A Deep Dive into a Serverless Microservice Architecture

https://tucielodenoche.com

Overview

Tu Cielo de Noche is a microservice-driven SaaS that transforms astronomical data into personalized, printable star maps. Beyond aesthetics, it’s a production-grade experiment in distributed systems, event-driven design, and serverless orchestration — a real-world exploration of how modern web infrastructure can support both e-commerce and computational workloads at scale.

Architecture Summary

Frontend — Next.js 15 (App Router), TypeScript, Tailwind CSS
React-based UI for rendering live previews and managing checkout sessions.

Database & Storage — Supabase (PostgreSQL + Storage)
Persistent layer for orders, configuration metadata, and generated images.

Payments — Stripe
Handles checkout sessions and triggers webhook events on successful transactions.

Queue & Compute — AWS SQS + AWS Lambda (Dockerized)
Manages asynchronous workloads for map generation via a distributed message queue.

Image Rendering — Node Canvas (server) + HTML Canvas (client)
Dual rendering strategy for high-quality, print-ready images and instant previews.

Email Delivery — Resend
Automated order confirmations and receipt notifications.

Print Fulfillment — Prodigi API
Connects the system to on-demand printing and global shipping services.

This modular stack decouples the checkout lifecycle from the rendering pipeline, ensuring reliability and scalability under concurrent workloads.

Core Flow

1. Client Interaction: Users customize parameters (location, date, theme, labels) via a Next.js form, generating a live client-side canvas preview.
2. Checkout: Upon confirmation, Stripe Checkout handles the payment and stores minimal metadata (order ID, configuration hash).
3. Webhook Trigger: Stripe’s payment_intent.succeeded event fires a webhook to the Next.js API route.
4. Queue Dispatch: The webhook handler validates the signature and enqueues a job (order ID + map configuration) to AWS SQS.
5. Worker Execution: A Lambda consumer, containerized with native Node Canvas dependencies, consumes messages and renders the high-resolution image.
6. Upload + Notify: The Lambda uploads the final image to Supabase Storage and triggers a confirmation email via Resend.

This event-driven workflow decouples compute-heavy tasks from the main request cycle, enabling sub-second frontend response times.

Stripe Webhook Example (Simplified)

import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, { apiVersion: "2023-10-16" });

export async function POST(req: Request) {
  const sig = req.headers.get("stripe-signature");
  const rawBody = await req.text();
  if (!sig) return new Response("Missing signature", { status: 400 });

  const event = stripe.webhooks.constructEvent(rawBody, sig, process.env.STRIPE_WEBHOOK_SECRET!);

  if (event.type === "payment_intent.succeeded") {
    const intent = event.data.object as Stripe.PaymentIntent;
    const orderId = intent.metadata.orderId;
    await enqueueRenderJob(orderId, intent.metadata);
  }

  return Response.json({ received: true });
}

async function enqueueRenderJob(orderId: string, metadata: any) {
  // Publish to SQS — decoupled background processing
  console.log(`Queued order ${orderId} for map generation.`);
}

AWS Lambda Worker (SQS Consumer)

import { SQSEvent } from "aws-lambda";

export const handler = async (event: SQSEvent) => {
  for (const record of event.Records) {
    const { orderId, mapConfig } = JSON.parse(record.body);
    console.log(`Processing order ${orderId}`);

    // Generate star map (server-side rendering)
    await generateStarMap(orderId, mapConfig);
  }
};

async function generateStarMap(orderId: string, config: any) {
  // Celestial computations + Node Canvas rendering
  console.log(`Generating star map for ${orderId}...`);
  await new Promise((r) => setTimeout(r, 1500)); // simulate workload
  console.log(`Upload complete → order ${orderId}`);
}

Docker Deployment Notes

Node Canvas requires native binaries, making AWS Lambda deployments tricky. The solution was to containerize the worker with a single-architecture build:

docker build --platform linux/amd64 -t celestial-map-worker .

This guarantees binary compatibility with the Lambda runtime while maintaining full reproducibility.

Key Learnings

• Event-driven architecture simplifies scaling and failure isolation.
• Serverless compute (Lambda + SQS) is ideal for bursty, IO-bound workloads.
• Stripe webhooks provide reliable, idempotent workflow triggers.
• Supabase + S3-compatible storage offers a lightweight alternative to full AWS stacks.
• Containerization ensures consistent builds for Node Canvas and native libraries.

Outcome

Tu Cielo de Noche evolved from an artistic concept into a robust SaaS architecture — blending astronomy, engineering, and e-commerce. The platform now handles full payment-to-fulfillment automation, producing print-ready celestial maps without manual intervention.

This project became not just a product, but a living case study in modern microservice architecture for creative commerce.