Software engineered around your business.

1# ADR 0007: Start as a modular monolith
2Status: Accepted
3 
4Context
5  Three teams, one domain, modest first-year load.
6Decision
7  One deployable; one module per bounded context.
8  Modules call each other's public interfaces only.
9  No module reads another module's tables.
10Consequences
11  + one pipeline, simple local transactions
12  - boundaries must be enforced by tooling
13Revisit when
14  a module needs independent scaling or releases.

1export class WorkOrder {
2  complete(by: TechnicianId, at: Instant) {
3    if (this.status !== "in_progress")
4      throw new InvalidTransition(this.status, "completed");
5    if (this.checklist.hasOpenRequiredItems())
6      throw new ChecklistIncomplete(this.id);
7    if (!this.assignees.includes(by))
8      throw new NotAssigned(by, this.id);
9 
10    this.status = "completed";
11    return new WorkOrderCompleted(this.id, by, at);
12  }
13}

1/v1/work-orders/{id}/complete:
2  post:
3    operationId: completeWorkOrder
4    x-permission: work_order:complete
5    parameters:
6      - $ref: '#/components/parameters/IdempotencyKey'
7    responses:
8      '200': { $ref: '#/components/responses/WorkOrder' }
9      '409': { $ref: '#/components/responses/InvalidTransition' }
10      '422': { $ref: '#/components/responses/ValidationProblem' }
11      '429': { $ref: '#/components/responses/RateLimited' }

1CREATE TABLE work_orders (
2  id           uuid PRIMARY KEY,
3  tenant_id    uuid NOT NULL REFERENCES tenants (id),
4  site_id      uuid NOT NULL REFERENCES sites (id),
5  status       text NOT NULL CHECK (status IN
6    ('requested','scheduled','in_progress','completed','cancelled')),
7  version      int  NOT NULL DEFAULT 0,
8  completed_at timestamptz,
9  CHECK (status <> 'completed' OR completed_at IS NOT NULL)
10);
11CREATE INDEX ON work_orders (tenant_id, status, site_id);
12ALTER TABLE work_orders ENABLE ROW LEVEL SECURITY;

1export const policies = {
2  "work_order:complete": ({ actor, resource }) =>
3    actor.tenantId === resource.tenantId &&
4    (actor.role === "dispatcher" ||
5      (actor.role === "technician" &&
6        resource.assigneeIds.includes(actor.id))),
7 
8  "invoice:void": ({ actor, resource }) =>
9    actor.tenantId === resource.tenantId &&
10    actor.role === "finance_admin",
11} satisfies PolicyMap;
12// Every policy has a test per role: authz/policies.test.ts

1export const options = {
2  scenarios: {
3    morning_peak: {
4      executor: "ramping-arrival-rate",
5      stages: [
6        { target: 40,  duration: "5m" },  // today's peak
7        { target: 400, duration: "15m" }, // 10x headroom
8      ],
9    },
10  },
11  thresholds: {
12    "http_req_duration{route:complete}": ["p(95)<300"],
13    http_req_failed: ["rate<0.001"],
14  },
15};

1slo: complete-work-order
2journey: Technician completes a work order
3indicator:
4  good:  status < 500 and latency < 300ms
5  total: POST /v1/work-orders/*/complete
6objective: 99.5%   # rolling 28 days
7alerts:
8  - burn_rate: 14.4  window: 1h  action: page
9  - burn_rate: 6     window: 6h  action: ticket
10runbook: runbooks/work-orders.md#slow-completion

1describe("WorkOrder.complete", () => {
2  it("rejects open required checklist items", () => {
3    const order = aWorkOrder().inProgress()
4      .withChecklist([{ required: true, done: false }]);
5    expect(() => order.complete(tech, now))
6      .toThrow(ChecklistIncomplete);
7  });
8 
9  it("completes exactly once", () => {
10    const order = aWorkOrder().inProgress().build();
11    order.complete(tech, now);
12    expect(() => order.complete(tech, now))
13      .toThrow(InvalidTransition);
14  });
15});

1deploy-production:
2  needs: [e2e-staging, migration-check]
3  environment: production
4  steps:
5    - run: ./deploy canary --weight 5
6    - run: ./verify slo complete-work-order --for 10m
7    - run: ./deploy promote --weight 100
8    - if: failure()
9      run: ./deploy rollback

1Cadence
2  weekly     dependency update PRs, CI-gated
3  monthly    security patches, error-budget review
4  quarterly  runtime and framework upgrades,
5             backup restore drill
6  yearly     architecture review against real load
7 
8Debt register
9  DEBT-014   invoice PDFs rendered synchronously
10             cost: slows completion at peak
11             fix:  move to worker queue  (est. 3d)