Modular monolith or microservices

-- One database, one schema per module
CREATE SCHEMA catalog;
CREATE SCHEMA booking;

CREATE TABLE catalog.services (
  id text PRIMARY KEY,
  title text NOT NULL,
  duration_min integer NOT NULL CHECK (duration_min > 0),
  price_kzt integer NOT NULL,
  archived boolean NOT NULL DEFAULT false
);

-- booking stores the service id, but catalog owns the row:
-- no cross-module foreign key, the id is checked through the catalog API
CREATE TABLE booking.bookings (
  id uuid PRIMARY KEY,
  service_id text NOT NULL,
  master_id text NOT NULL,
  client_phone text NOT NULL,
  starts_at timestamptz NOT NULL,
  ends_at timestamptz NOT NULL
);

-- each module's code connects with its own role and sees only its schema
CREATE ROLE booking_module NOLOGIN;
GRANT USAGE ON SCHEMA booking TO booking_module;
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA booking TO booking_module;

SET ROLE booking_module;
INSERT INTO booking.bookings VALUES
  (gen_random_uuid(), 'haircut', 'm1', '+77011234567', '2026-10-12 10:00+00', '2026-10-12 11:00+00');
SELECT service_id, master_id FROM booking.bookings;
SELECT title FROM catalog.services;

$ docker exec -i kb-pg-modulnyj-monolit psql -U postgres < check.sql
SET
INSERT 0 1
 service_id | master_id
------------+-----------
 haircut    | m1
(1 row)

ERROR:  permission denied for schema catalog
LINE 1: SELECT title FROM catalog.services;
                          ^

import { type ServiceRow, ServicesStore } from "./internal/services-store.js";

// Public API of the catalog module: the only file other modules may import
export type BookableService = { id: string; title: string; durationMin: number };

export interface CatalogApi {
  findBookableService(id: string): Promise<BookableService | null>;
}

export function createCatalogModule(seed: ServiceRow[] = []) {
  const store = new ServicesStore();
  seed.forEach((row) => store.add(row));

  const api: CatalogApi = {
    async findBookableService(id) {
      const row = store.find(id);
      if (!row || row.archived) return null;
      // price and archive flag stay inside the module
      return { id: row.id, title: row.title, durationMin: row.durationMin };
    },
  };
  return { api, admin: { addService: (row: ServiceRow) => store.add(row) } };
}

import { randomUUID } from "node:crypto";
import type { InProcessEvents } from "../../shared/events.js";
import type { CatalogApi } from "../catalog/index.js";
import { BookingsStore, overlaps } from "./internal/schedule.js";

// Public API of the booking module: its input, its errors and its events
export type BookInput = { serviceId: string; masterId: string; clientPhone: string; startsAt: Date };
export type BookingCreated = {
  type: "booking.created";
  bookingId: string;
  masterId: string;
  clientPhone: string;
  serviceTitle: string;
  startsAt: string;
};

export class BookingError extends Error {
  constructor(readonly code: "UNKNOWN_SERVICE" | "SLOT_TAKEN") {
    super(code);
  }
}

export function createBookingModule(deps: {
  catalog: CatalogApi;
  events: InProcessEvents<BookingCreated>;
}) {
  const store = new BookingsStore();

  return {
    async book(input: BookInput): Promise<{ bookingId: string; endsAt: Date }> {
      // Another module is reached only through its public API
      const service = await deps.catalog.findBookableService(input.serviceId);
      if (!service) throw new BookingError("UNKNOWN_SERVICE");

      const endsAt = new Date(input.startsAt.getTime() + service.durationMin * 60_000);
      const slot = { startsAt: input.startsAt, endsAt };
      if (store.forMaster(input.masterId).some((b) => overlaps(b, slot))) {
        throw new BookingError("SLOT_TAKEN");
      }

      const booking = { id: randomUUID(), ...input, endsAt };
      store.add(booking);
      await deps.events.publish({
        type: "booking.created",
        bookingId: booking.id,
        masterId: booking.masterId,
        clientPhone: booking.clientPhone,
        serviceTitle: service.title,
        startsAt: booking.startsAt.toISOString(),
      });
      return { bookingId: booking.id, endsAt };
    },
  };
}

// In-process event bus: modules talk without importing each other's internals.
// If a module becomes a service, a message broker takes this place.
type Handler<E> = (event: E) => void | Promise<void>;

export class InProcessEvents<E extends { type: string }> {
  private readonly handlers = new Map<string, Handler<E>[]>();

  subscribe<T extends E["type"]>(type: T, handler: Handler<Extract<E, { type: T }>>): void {
    const list = this.handlers.get(type) ?? [];
    list.push(handler as Handler<E>);
    this.handlers.set(type, list);
  }

  async publish(event: E): Promise<void> {
    for (const handler of this.handlers.get(event.type) ?? []) {
      await handler(event);
    }
  }
}

import type { InProcessEvents } from "../../shared/events.js";
import type { BookingCreated } from "../booking/index.js";

// Notifications know the booking event contract, not the booking tables
export function createNotificationsModule(deps: { events: InProcessEvents<BookingCreated> }) {
  const outbox: string[] = [];

  deps.events.subscribe("booking.created", (event) => {
    outbox.push(`${event.clientPhone}: ${event.serviceTitle}, ${event.startsAt}`);
  });

  return { sent: () => [...outbox] };
}

import { createBookingModule, type BookingCreated } from "./modules/booking/index.js";
import { createCatalogModule } from "./modules/catalog/index.js";
import { createNotificationsModule } from "./modules/notifications/index.js";
import { InProcessEvents } from "./shared/events.js";

// One process, one deployment: modules are wired together here
export function createApp() {
  const events = new InProcessEvents<BookingCreated>();
  const catalog = createCatalogModule([
    { id: "haircut", title: "Haircut", durationMin: 60, priceKzt: 8000, archived: false },
    { id: "beard", title: "Beard trim", durationMin: 30, priceKzt: 4000, archived: true },
  ]);
  const booking = createBookingModule({ catalog: catalog.api, events });
  const notifications = createNotificationsModule({ events });
  return { catalog, booking, notifications };
}

import { describe, expect, it } from "vitest";
import { createApp } from "../src/app.js";
import { BookingError } from "../src/modules/booking/index.js";

const at = (iso: string) => new Date(iso);

describe("modular monolith: booking through public APIs", () => {
  it("books a slot and notifies through an in-process event", async () => {
    const app = createApp();
    const { endsAt } = await app.booking.book({
      serviceId: "haircut",
      masterId: "m1",
      clientPhone: "+77011234567",
      startsAt: at("2026-10-12T10:00:00Z"),
    });

    expect(endsAt).toEqual(at("2026-10-12T11:00:00Z"));
    expect(app.notifications.sent()).toEqual([
      "+77011234567: Haircut, 2026-10-12T10:00:00.000Z",
    ]);
  });

  it("rejects an overlapping slot for the same master", async () => {
    const app = createApp();
    const base = { serviceId: "haircut", masterId: "m1", clientPhone: "+77011234567" };
    await app.booking.book({ ...base, startsAt: at("2026-10-12T10:00:00Z") });

    await expect(
      app.booking.book({ ...base, startsAt: at("2026-10-12T10:30:00Z") }),
    ).rejects.toEqual(new BookingError("SLOT_TAKEN"));
    // back-to-back is fine: intervals are half-open
    await app.booking.book({ ...base, startsAt: at("2026-10-12T11:00:00Z") });
    expect(app.notifications.sent()).toHaveLength(2);
  });

  it("does not book archived or unknown services", async () => {
    const app = createApp();
    const input = { masterId: "m1", clientPhone: "+77011234567", startsAt: at("2026-10-12T10:00:00Z") };

    await expect(app.booking.book({ ...input, serviceId: "beard" })).rejects.toMatchObject({
      code: "UNKNOWN_SERVICE",
    });
    await expect(app.booking.book({ ...input, serviceId: "nope" })).rejects.toBeInstanceOf(BookingError);
  });
});

/** @type {import('dependency-cruiser').IConfiguration} */
module.exports = {
  forbidden: [
    {
      name: "modules-only-via-public-api",
      comment: "Another module is reachable only through its index.ts",
      severity: "error",
      from: { path: "^src/modules/([^/]+)/" },
      to: {
        path: "^src/modules/",
        pathNot: ["^src/modules/$1/", "^src/modules/[^/]+/index\\.ts$"],
      },
    },
    {
      name: "shared-knows-no-modules",
      comment: "shared is a toolbox, not a back door between modules",
      severity: "error",
      from: { path: "^src/shared/" },
      to: { path: "^src/modules/" },
    },
    {
      name: "no-circular",
      comment: "Module dependencies must form a directed acyclic graph",
      severity: "error",
      from: {},
      to: { circular: true },
    },
    {
      name: "not-to-unresolvable",
      severity: "error",
      from: {},
      to: { couldNotResolve: true },
    },
  ],
  options: {
    doNotFollow: { path: "node_modules" },
    tsPreCompilationDeps: true,
    tsConfig: { fileName: "tsconfig.json" },
  },
};

$ npx tsc --noEmit && npx vitest run --reporter=verbose

 ✓ test/app.test.ts > modular monolith: booking through public APIs > books a slot and notifies through an in-process event 3ms
 ✓ test/app.test.ts > modular monolith: booking through public APIs > rejects an overlapping slot for the same master 1ms
 ✓ test/app.test.ts > modular monolith: booking through public APIs > does not book archived or unknown services 1ms

 Test Files  1 passed (1)
      Tests  3 passed (3)

$ npx depcruise src --config .dependency-cruiser.cjs

✔ no dependency violations found (8 modules, 11 dependencies cruised)

--- a/src/modules/booking/index.ts
+++ b/src/modules/booking/index.ts
@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import type { InProcessEvents } from "../../shared/events.js";
 import type { CatalogApi } from "../catalog/index.js";
+import type { ServiceRow } from "../catalog/internal/services-store.js";
 import { BookingsStore, overlaps } from "./internal/schedule.js";
 
 // Public API of the booking module: its input, its errors and its events
@@ -12,6 +13,7 @@ export type BookingCreated = {
   clientPhone: string;
   serviceTitle: string;
   startsAt: string;
+  priceKzt?: ServiceRow["priceKzt"];
 };
 
 export class BookingError extends Error {
--- a/src/modules/catalog/index.ts
+++ b/src/modules/catalog/index.ts
@@ -1,5 +1,9 @@
+import type { BookingCreated } from "../booking/index.js";
 import { type ServiceRow, ServicesStore } from "./internal/services-store.js";
 
+// catalog wants to count popular services from booking events
+export type PopularityInput = Pick<BookingCreated, "serviceTitle">;
+
 // Public API of the catalog module: the only file other modules may import
 export type BookableService = { id: string; title: string; durationMin: number };

$ npx tsc --noEmit && npx vitest run
      Tests  3 passed (3)
$ npx depcruise src --config .dependency-cruiser.cjs

  error no-circular: src/modules/booking/index.ts →
      src/modules/catalog/index.ts →
      src/modules/booking/index.ts
  error modules-only-via-public-api: src/modules/booking/index.ts → src/modules/catalog/internal/services-store.ts

x 2 dependency violations (2 errors, 0 warnings). 8 modules, 13 dependencies cruised.