Senses and skin

Humans experience the world through senses: sight, hearing, touch, a clock-like sense of time. A microservice senses the world through inputs. Some inputs arrive when someone talks to it directly; others arrive as background noise it has chosen to listen to.

The five senses of a microservice

The UI of your application is the most important sense of the whole society — it's how humans outside the system (your users) reach it. In this handbook, the UI (web app, mobile app, chat, email) is the eyes and ears of the ecosystem, and API Gateway is the ear canal that carries what users say to the right human.

Synchronous vs asynchronous senses

• Synchronous (someone is waiting): API requests. The caller stands in front of you until you answer. Respond quickly — slow answers frustrate everyone.
• Asynchronous (nobody is waiting): letters, announcements, schedules, files. You can take your time, retry if you fail, and handle bursts calmly.

The skin: deciding what gets in

Skin is a boundary. It lets good things in and keeps dirt out. For a service, the skin is its contract — what inputs it accepts — and validation that enforces it.

// skin/place-order.schema.ts — the shape of a valid "place order" request
import { z } from "zod";

export const PlaceOrder = z.object({
  tableNumber: z.number().int().min(1).max(50),
  items: z
    .array(z.object({ menuItemId: z.string().min(1), quantity: z.number().int().min(1).max(20) }))
    .min(1),
  notes: z.string().max(200).optional(),
});

export type PlaceOrder = z.infer<typeof PlaceOrder>;

// senses/place-order.http.ts — the ear: thin handler, validates at the skin, passes to the brain
import type { APIGatewayProxyEventV2, APIGatewayProxyResultV2 } from "aws-lambda";
import { PlaceOrder } from "../skin/place-order.schema";
import { placeOrder } from "../brain/place-order";
import { menu } from "../memory/menu";            // adapters that give the brain what it needs
import { orderMemory } from "../memory/order-memory";
import { voice } from "../voice/event-voice";

export const handler = async (event: APIGatewayProxyEventV2): Promise<APIGatewayProxyResultV2> => {
  const parsed = PlaceOrder.safeParse(JSON.parse(event.body ?? "{}"));
  if (!parsed.success) {
    return { statusCode: 400, body: JSON.stringify({ error: "Invalid order", details: parsed.error.issues }) };
  }
  const order = await placeOrder(parsed.data, { menu, memory: orderMemory, voice });
  return { statusCode: 201, body: JSON.stringify(order) };
};

(This example uses the zod library for schemas; any validation approach works. API Gateway REST APIs can also validate request bodies before your code runs.)

Rules for healthy senses

1. Keep handlers thin. A sense organ passes signals to the brain — it doesn't think. Handlers parse, validate and delegate.
2. Validate everything at the skin. Never let unvalidated input reach the brain or memory.
3. Expect noise. Events and messages can arrive twice or out of order. Design for it (see voice and hearing).
4. Protect against overload. Throttle APIs; put a queue in front of slow work so bursts become a manageable stream.
5. Document your senses. Other teams need to know which inputs you accept: an API specification for requests, event schemas for events.

The senses in AWS, summarised

Written by Bipin Singh

Senior Full-Stack Engineer · AI & AWS. I design and build serverless systems on AWS — and love explaining them simply.

Work with me