Scaffold the decisions that matter.

More than an empty folder tree.

A scaffold records decisions before implementation. It can include directories, module names, signatures, comments, examples and tests. The useful part is the responsibility each piece makes explicit.

In an existing project, start with its actual conventions. Do not impose a new architecture just because a template looks tidy.

Original teaching example

An invitation-acceptance feature

Scope the behaviour first: an invitation can be accepted once, before its expiry. The same instant is supplied to every policy check. The storage operation must prevent two concurrent requests from both accepting it.

src/
  domain/
    invite.ts          # expiry policy and domain types
    invite.test.ts     # boundary examples
  application/
    accept-invite.ts   # use case and repository interface
  adapters/
    invite-store.ts    # implements persistence
  http/
    accept-invite.ts   # validates input, maps response
docs/
  invite-contract.md   # behaviour and trade-offs

type Invite = {
  id: string;
  expiresAtMs: number;
  acceptedAtMs: number | null;
};

type Acceptance =
  | { ok: true; invite: Invite }
  | { ok: false; reason: "expired" | "already-accepted" };

// Pure policy. No database, HTTP request or system clock.
// Expired means nowMs >= expiresAtMs.
export function acceptInvite(
  invite: Invite,
  nowMs: number
): Acceptance {
  throw new Error("Not implemented");
}

This is a deliberately incomplete scaffold, not production-ready invitation code. The throwing stub makes missing implementation visible. Authentication, token verification, persistence and concurrency still need implementation and tests.

Before expiry

At 999 ms with expiry at 1,000 ms, acceptance succeeds.

At expiry

At 1,000 ms, return expired. The boundary is inclusive.

Already accepted

Return already-accepted, with no second side effect. Check this before expiry so the error precedence is explicit.

Concurrent requests

At most one storage operation succeeds. A pure function alone cannot enforce this.

Dependency boundary

A domain import of the database adapter fails an architecture check.

Turn the sketch into checks.

The scaffold supplies forward pressure. Behaviour tests, dependency rules and code review supply back pressure. A folder name does not prevent an invalid dependency; an executable rule can.

Implement the invitation acceptance use case.
Use the existing module boundaries and deployment command.
Read docs/invite-contract.md and the nearby adapter first.
Put expiry policy only in domain/invite.ts.
Do not add dependencies or change the public API.
Add boundary and concurrent-acceptance tests.
Report the diff, commands run and unresolved assumptions.
Stop if the persistence API cannot enforce one acceptance.

How much is enough?

If the language or domain is new to you, inspect a few relevant open-source projects, compare their trade-offs, and ask an experienced person to challenge your sketch. Test a small proof of concept before treating the structure as settled.

Review early enough to recognise drift. If an isolated attempt is unusable, keep the learning and discard only that attempt after preserving anything valuable. Never erase unrelated work.