typescript-decompiler/docs/reference/conventions.md

Project Conventions

This page is the quick reference for conventions that a human reviewer is likely to check first. For the philosophy behind these conventions, read the explanation docs.

Naming

• Use domain language, not generic programmer words.
• Prefer explicit lifecycle states such as DraftItem or ActiveOrder over one object with a broad status field.
• Use nouns for stateful objects, past-tense facts for events, and imperative verb phrases for commands.
• Maintain a project-wide shared language in shared-language.md.
• Maintain bounded-context shared language in design/workflows/<bounded-context-slug>/shared-language.md.
• Record feature-level naming decisions in design/feature/<feature-slug>/discovery.md and slice-level naming decisions in the workflow artifacts.
• See naming-lexicon.md, shared-language.md, and ../explanation/naming-for-domain-modeling.md for guidance.

Design artifact shape

A complete operational design set now usually includes:

• feature discovery in design/feature/<feature-slug>/discovery.md
• feature decomposition in design/feature/<feature-slug>/design.md
• bounded-context shared language in design/workflows/<bounded-context-slug>/shared-language.md
• slice discovery, core sketch, and F# blueprint under design/workflows/<bounded-context-slug>/<workflow-slug>/
• status tracking in design/feature/<feature-slug>/status.md

Use design-artifact-template.md for by-hand practice and design-artifact-structure.md for the repository artifact layout.

Documentation organization

This repo uses a modified Diátaxis structure:

• docs/tutorials/ for learning by example and practice
• docs/how-to/ for specific tasks such as reviewing LLM output
• docs/explanation/ for philosophy and architectural reasoning
• docs/reference/ for templates, checklists, and stable lookup material

Code structure pointers

• src/contexts/ is the default home for business code.
• Each context keeps its own models, policies, workflows, translators, adapters, and other seams as needed.
• src/workflows/ is reserved for top-level workflows that coordinate multiple contexts.
• src/shared/ should contain only tiny ubiquitous primitives and low-meaning technical building blocks.

Module boundaries

• Cross-context imports should go through the target context's public API.
• Do not import another context's internal implementation files.
• When data crosses context boundaries, prefer translation at the edge over sharing one rich domain type everywhere.

Decision preference

• Prefer correctness, simplicity, and elegance over backwards compatibility.
• If compatibility would preserve a worse design, require an explicit reason before keeping it.
• Prefer combined local logic by default during initial implementation.
• Extract a new layer, module, or helper only when it materially improves nameability, testability, reuse, boundary clarity, or duplicated complexity.
• Good names can expose a useful seam, but naming alone does not justify extra indirection.

Review reminder

When in doubt, compare the artifact being reviewed against:

• ../tutorials/worked-example-truck-loading.md
• review-checklist.md
• design-artifact-template.md