typescript-decompiler/docs/explanation/tdfddd-manifesto.md

TDFDDD Manifesto

Type-Driven Functional Domain-Driven Design is the design discipline behind this template. In casual conversation we call it Functional Domain Modeling.

What the method is trying to achieve

The goal is not to move fast by skipping design. The goal is to make the important design decisions explicit enough that implementation becomes mechanical and review becomes reliable.

The core idea is simple:

Make illegal states unrepresentable.

Instead of writing more and more runtime checks, use types and explicit state shapes so invalid situations are harder to express in the first place.

The design pressure should come from the workflow

A common mistake is trying to invent the perfect domain model too early. That usually produces elegant-looking types that do not actually serve the workflow.

A better heuristic is:

Let the workflow dictate the state.

Start with the decision the system must make. Sketch the policy signature with temporary or incomplete types if needed. Once you know what information the workflow needs, model those concepts precisely.

This keeps the design grounded in real use instead of speculation.

Pure core, impure shell

We separate high-inference design work from mechanical implementation work.

• The policy is the pure core. It makes a domain decision from explicit inputs.
• The model applies a state transition using pure data transformations.
• The workflow is the impure shell. It gathers data, calls the policy, applies state changes, persists results, and invokes external capabilities.

This separation is what makes the method reviewable. A human can inspect the design in layers instead of trying to reason about everything at once.

Design before code, but not design as guesswork

You should not jump straight into implementation code. But that does not mean you need a perfect domain ontology before you start.

A practical sequence is:

1. Write the story in domain language.
2. Identify the command and possible events.
3. Sketch the policy signature.
4. Invent the minimum types required to make the decision precise.
5. Freeze the contract.
6. Translate the design into TypeScript and Effect.

That is why design artifacts matter. They preserve the reasoning that a human reviewer is validating.

Why the human reviewer matters in an LLM-first workflow

In an LLM-first workflow, the model can produce the first draft of the design artifacts. The human still has to judge whether the artifacts are sound.

The reviewer is checking questions like these:

• Did the model identify the right command and outcomes?
• Did it model state transitions instead of hiding them behind status flags?
• Did it choose types that encode the business constraints?
• Did it keep policies pure and move orchestration into workflows?
• Did it return domain facts instead of vague booleans?

The review process only works if the repository preserves examples, templates, and clear standards for comparison.

What a good finished design feels like

A good TDFDDD design usually has these properties:

• The story can be explained in domain language without mentioning framework details.
• The command, events, and state variants are easy to name.
• The policy signature makes the decision boundary obvious.
• The final implementation looks like translation, not invention.
• A reviewer can tell what is being verified at each phase.

Where to go next

• If you want to learn by imitation, start with ../tutorials/worked-example-truck-loading.md.
• If you want to practice manually, use ../tutorials/practicing-tdfddd-by-hand.md.
• If you want the formal phase breakdown, read ./tdfddd-protocol.md.
• If you want to review model output, use ../how-to/review-an-llm-generated-design.md and ../reference/review-checklist.md.