Software architecture

  frameworks & drivers  (Bun.serve, Hono, Postgres, Stripe)
        │ implements / calls
  adapters              (http routes, pg repository, clients)
        │ depends on
  application           (use cases, ports = interfaces)
        │ depends on
  domain                (entities, value objects, events)

import { err, ok, type Result }
  from "../../../shared/result";
 
declare const brand: unique symbol;
type Brand<T, B extends string> = T & { [brand]: B };
 
export type OrderId = Brand<string, "OrderId">;
export type Cents = Brand<number, "Cents">;
 
export function cents(
  n: number,
): Result<Cents, "bad-amount"> {
  return Number.isInteger(n) && n >= 0
    ? ok(n as Cents)
    : err("bad-amount");
}
 
export type OrderLine = Readonly<{
  sku: string;
  qty: number;
  price: Cents;
}>;
 
export type Order = Readonly<{
  id: OrderId;
  status: "draft" | "placed";
  lines: readonly OrderLine[];
}>;
 
export type OrderPlaced = Readonly<{
  type: "order.placed";
  orderId: OrderId;
  total: Cents;
  at: Date;
}>;
 
export type PlaceError = "empty-order" | "already-placed";
 
export function place(
  order: Order,
  at: Date,
): Result<{ order: Order; event: OrderPlaced }, PlaceError> {
  if (order.status === "placed") {
    return err("already-placed");
  }
  if (order.lines.length === 0) return err("empty-order");
  const total = order.lines.reduce(
    (sum, l) => sum + l.qty * l.price,
    0,
  ) as Cents;
  return ok({
    order: { ...order, status: "placed" },
    event: {
      type: "order.placed",
      orderId: order.id,
      total,
      at,
    },
  });
}

// The only file other modules may import.
export { makePlaceOrder } from "./application/place-order";
export type { PlaceOrder } from "./application/place-order";
export type {
  Order,
  OrderId,
  OrderPlaced,
} from "./domain/order";

const viaIndex = {
  group: ["@/modules/*/*/**"],
  message: "import another module via its index",
};
const pure = {
  group: ["**/infra/**", "**/http/**",
    "hono", "bun", "drizzle-orm*"],
  message: "domain must stay pure",
};
 
export default [
  {
    files: ["src/modules/**/*.ts"],
    rules: {
      "no-restricted-imports": ["error",
        { patterns: [viaIndex] }],
    },
  },
  {
    // a later match replaces the options: repeat viaIndex
    files: ["src/modules/*/domain/**/*.ts"],
    rules: {
      "no-restricted-imports": ["error",
        { patterns: [viaIndex, pure] }],
    },
  },
];

export type Ok<T> = { readonly ok: true; readonly value: T };
export type Err<E> = {
  readonly ok: false;
  readonly error: E;
};
export type Result<T, E> = Ok<T> | Err<E>;
 
export const ok = <T>(value: T): Ok<T> => ({
  ok: true,
  value,
});
export const err = <E>(error: E): Err<E> => ({
  ok: false,
  error,
});

import { z } from "zod";
 
const Config = z.object({
  DATABASE_URL: z.url(),
  PORT: z.coerce.number().int().default(3000),
  LOG_LEVEL: z
    .enum(["debug", "info", "warn", "error"])
    .default("info"),
});
 
export type Config = Readonly<z.infer<typeof Config>>;
 
export function loadConfig(
  env: Record<string, string | undefined>,
): Config {
  const parsed = Config.safeParse(env);
  if (!parsed.success) {
    throw new Error("Invalid configuration", {
      cause: z.prettifyError(parsed.error),
    });
  }
  return Object.freeze(parsed.data);
}

import { expect, test } from "bun:test";
import { Glob } from "bun";
 
const FORBIDDEN = /\/infra\/|\/http\/|^hono|^bun$/;
const IMPORT = /from\s+["']([^"']+)["']/g;
 
test("domain code imports no infrastructure", async () => {
  const bad: string[] = [];
  const glob = new Glob("src/modules/*/domain/**/*.ts");
  for await (const file of glob.scan(".")) {
    const src = await Bun.file(file).text();
    for (const m of src.matchAll(IMPORT)) {
      const spec = m[1] ?? "";
      if (FORBIDDEN.test(spec)) bad.push(`${file}: ${spec}`);
    }
  }
  expect(bad).toEqual([]);
});

import type { Order, OrderId, OrderPlaced }
  from "../domain/order";
 
export interface OrderRepository {
  findById(id: OrderId): Promise<Order | null>;
  save(order: Order): Promise<void>;
}
export interface EventPublisher {
  publish(events: readonly OrderPlaced[]): Promise<void>;
}
export interface Clock {
  now(): Date;
}

import type { Order, OrderId } from "../domain/order";
import type { OrderRepository } from "../application/ports";
 
export class InMemoryOrders implements OrderRepository {
  readonly #rows = new Map<OrderId, Order>();
 
  constructor(seed: readonly Order[] = []) {
    for (const o of seed) this.#rows.set(o.id, o);
  }
  async findById(id: OrderId): Promise<Order | null> {
    return this.#rows.get(id) ?? null;
  }
  async save(order: Order): Promise<void> {
    this.#rows.set(order.id, order);
  }
}

import { err, ok, type Result }
  from "../../../shared/result";
import { place, type Order, type OrderId, type PlaceError }
  from "../domain/order";
import type { Clock, EventPublisher, OrderRepository }
  from "./ports";
 
export type PlaceOrderError = PlaceError | "not-found";
export type PlaceOrder = (
  id: OrderId,
) => Promise<Result<Order, PlaceOrderError>>;
 
export const makePlaceOrder = (deps: {
  orders: OrderRepository;
  events: EventPublisher;
  clock: Clock;
}): PlaceOrder => async (id) => {
  const order = await deps.orders.findById(id);
  if (!order) return err("not-found");
  const placed = place(order, deps.clock.now());
  if (!placed.ok) return placed;
  await deps.orders.save(placed.value.order);
  await deps.events.publish([placed.value.event]);
  return ok(placed.value.order);
};

import { expect, test } from "bun:test";
import type { Cents, Order, OrderId, OrderPlaced }
  from "../domain/order";
import { InMemoryOrders } from "../infra/in-memory-orders";
import { makePlaceOrder } from "./place-order";
 
const draft: Order = {
  id: "o1" as OrderId,
  status: "draft",
  lines: [{ sku: "tea", qty: 2, price: 450 as Cents }],
};
 
test("placing a draft publishes order.placed", async () => {
  const sent: OrderPlaced[] = [];
  const placeOrder = makePlaceOrder({
    orders: new InMemoryOrders([draft]),
    events: { publish: async (e) => void sent.push(...e) },
    clock: { now: () => new Date(0) },
  });
  const r = await placeOrder(draft.id);
  expect(r.ok).toBe(true);
  expect(sent[0]?.total).toBe(900 as Cents);
});

import type { OrderId } from "../domain/order";
import type { PlaceOrder, PlaceOrderError }
  from "../application/place-order";
 
const STATUS: Record<PlaceOrderError, number> = {
  "not-found": 404,
  "empty-order": 422,
  "already-placed": 409,
};
 
export const placeOrderRoute =
  (placeOrder: PlaceOrder) =>
  async (id: string): Promise<Response> => {
    const r = await placeOrder(id as OrderId);
    return r.ok
      ? Response.json(r.value)
      : Response.json(
          { error: r.error },
          { status: STATUS[r.error] },
        );
  };

type Handler<E> = (event: E) => Promise<void>;
type Of<E, T> = Extract<E, { type: T }>;
 
export function createEventBus<E extends { type: string }>(
  onError: (error: unknown, event: E) => void,
) {
  const handlers = new Map<E["type"], Handler<E>[]>();
  return {
    on<T extends E["type"]>(type: T, fn: Handler<Of<E, T>>) {
      const h: Handler<E> = (e) => fn(e as Of<E, T>);
      handlers.set(type, [...(handlers.get(type) ?? []), h]);
    },
    async publish(events: readonly E[]): Promise<void> {
      for (const e of events) {
        const hs = handlers.get(e.type) ?? [];
        const rs = await Promise.allSettled(
          hs.map((h) => h(e)),
        );
        for (const r of rs)
          if (r.status === "rejected") onError(r.reason, e);
      }
    },
  };
}

import { loadConfig } from "./config";
import { createEventBus } from "./shared/event-bus";
import { makePlaceOrder, type OrderPlaced }
  from "./modules/orders";
import { InMemoryOrders }
  from "./modules/orders/infra/in-memory-orders";
import { placeOrderRoute }
  from "./modules/orders/http/routes";
 
const config = loadConfig(process.env);
const bus = createEventBus<OrderPlaced>((error, e) =>
  console.error("handler failed", e.type, error));
bus.on("order.placed", async (e) => console.info(e.orderId));
 
const place = placeOrderRoute(makePlaceOrder({
  orders: new InMemoryOrders(), // swap for a pg adapter
  events: bus,
  clock: { now: () => new Date() },
}));
Bun.serve({
  port: config.PORT,
  routes: {
    "/orders/:id/place": { POST: (r) => place(r.params.id) },
  },
});

# 7. Start as a modular monolith
 
- Status: Accepted
- Date: 2026-09-25
- Deciders: platform team
 
## Context
Three developers, one product, domain still changing.
We expect orders, billing and catalog to evolve apart.
 
## Decision
One Bun service with modules under `src/modules/*`,
each with a public `index.ts`. Boundaries enforced by
dependency-cruiser in CI. Each module owns its tables.
 
## Consequences
+ One deploy, simple local dev, refactors are cheap.
+ A module can later become a service along its API.
- Needs discipline: CI rules must stay green.
- Shared DB instance: one module can still hog it.
 
## Alternatives considered
Microservices per module: rejected, no ops capacity.

/** @type {import("dependency-cruiser").IConfiguration} */
export default {
  forbidden: [
    { name: "domain-not-to-infra", severity: "error",
      from: { path: "^src/modules/[^/]+/domain/" },
      to: { path: "(/infra/|/http/|^node_modules/)" },
    },
    { name: "only-via-public-api", severity: "error",
      from: { path: "^src/modules/([^/]+)/" },
      to: {
        path: "^src/modules/[^/]+/.+",
        pathNot: ["^src/modules/$1/", "index\\.ts$"],
      },
    },
    { name: "no-circular", severity: "error",
      from: {}, to: { circular: true } },
  ],
  options: {
    doNotFollow: { path: "node_modules" },
    tsConfig: { fileName: "tsconfig.json" },
  },
};

bunx depcruise src --config .dependency-cruiser.mjs
bunx depcruise src --output-type dot | dot -T svg > deps.svg