Factory docs, home
Page navigation

Pre-release documentation. Proposed designs are labelled in the page; acceptance evidence is maintained in the build review. Local paths appear as placeholders. Current state: Build review.

Proposed E39 Module and E40 decision step. No guide, code or catalogue exists yet. The owner asked on 2 October 2026 for a dedicated Module that knows the industry's architecture styles, design patterns and engineering practice, is consulted when a new Product starts or a major feature is added, and weighs delivery speed against production readiness. This page records that request, the owner's answers to the interview that followed, and where each answer lands in the delivery plan. It grants no model use, repository access or authority.

What it is for

A solo prototype can use a plain structure and move fast. A feature in a large codebase serving many users needs careful integration with what is already there. The Module recommends architecture and engineering practice in proportion to what the owner says the Product needs, explains what that choice costs, and drafts an Architecture Decision Record (ADR). The Knowledge capture and retrieval Workflow documents the decisions; Verification checks that the built change follows them.

The project intent already reserves an "Architecture and knowledge" boundary for "Module/API contracts, current dependency map and decisions", and asks for deep modules in John Ousterhout's sense (P-C04). The Delivery domain owns "design, implementation and repair of a Slice" (design). No Module does this today.

Owner decisions, 2 October 2026

QuestionDecisionWhere it lands
Its own Module, or part of Knowledge?Its own Module, covering architecture and engineering practice, not architecture alone. Knowledge documents the decisions it makes.E39 contract; E40 records
How is "proportionate" decided?No numeric cut-offs. The owner declares a delivery mode up front, and the Module explains the consequences of that choice. The mode roughly follows users served, appetite for speed and whether the Product is an MVP.E39, delivery modes
What if the real scale differs?Observe it. Usage and health facts are compared with the declared mode, and a mismatch prompts a mode review.E39, observed scale
Which sources and languages?The six books proposed, plus each language's own guides. The Module recommends the language: TypeScript on Node.js by default, Rust where performance is critical, Kotlin for Android, Swift for iOS and macOS.E39 catalogue
Who accepts an ADR?An independent reviewer model chosen through Intelligence; the owner is not asked.E40 acceptance
What counts as a major feature, and what format?Decided through Intelligence for each Slice, with a deterministic floor. The record follows the Product's own convention.E40 triggers and records
May it read a Product's code?Yes, read-only and bounded.E39 analysis
Who writes the catalogue?The coordinator drafts, an independent reviewer checks, and no quotation is published.E39 catalogue
First consumer?The Factory's own repository; its recorded decisions seed the test scenarios.E39 proof
Do Repair and Simplification consult it?Yes, when a reproduction or a refactor points at structure.E40 triggers

The interview also settled the composition map questions: keep inferred Workflow links and their ensemble plates, marked as planned; name a Module's sub-parts where they are significant; consolidate the maps into levels of detail; show this proposed Module on the published map; and have Marketing check competitors through Discovery sources. The owner asked to prioritise the credential broker under E20, and to hand artwork generation to the Codex harness. One question was not answered explicitly: whether an outer Workflow should run Implementation, Verification and Release in turn. The map shows the suggested default, an End-to-end delivery Workflow, as planned, until the owner confirms or removes it.

Delivery modes

The owner chooses a mode for each Product and may choose another for one major feature. The examples are a guide to the conversation, not thresholds; the Module explains each mode's consequences before the choice is recorded.

ModeTypical signsWhat it favoursWhat it gives upADR depth
PrototypeLearning whether an idea works; expected to be thrown awaySpeed, the fewest moving partsDurability, migration pathsOne paragraph
MVPFirst real users; moving fast matters mostSpeed, one deployable unit, managed servicesScale headroom, some operating polishShort record
ProductA growing user base, several contributorsClear Module boundaries, tests and release safetySome speedFull record
ScaleA large codebase or user base, or strict availability, data or compliance obligationsCompatibility, incremental migration, rollout and rollback plansSpeed of large changesFull record with integration plan

The mode is recorded with the Product's Project guidance and pinned in every recommendation, so a later reader can see which mode a decision assumed.

Observed scale

The declared mode is the owner's statement; observations test it. Usage, traffic and error facts arrive as Operational Signals (E37 plans PostHog, Sentry and Datadog sources), and Portfolio supplies contributors and codebase growth. When observations diverge from the mode, for example an MVP with tens of thousands of active users, the Module proposes a mode review with the evidence. It never changes the mode itself, and an unknown observation is named, never assumed small.

No separate Workflow is needed for this now: the facts belong to the Operations domain, and the Module only reads them. If usage reporting grows into its own job, it becomes a Workflow then.

How a decision flows

  1. A Slice is framed. Intelligence's classifier, or the deterministic floor (a new Product, data store, dependency, deployable unit, public API or schema change, or a change across Module boundaries), says whether it needs a consult.
  2. The Module reads the context profile, the declared mode and a bounded read-only analysis of the code, then drafts a proposed ADR from its catalogue.
  3. An independent reviewer model, chosen through Intelligence and never the drafting model, accepts or rejects it. While no reviewer is qualified, the ADR stays proposed and its Slice waits unless the owner overrides.
  4. Knowledge records the decision. The record reaches the Product's repository as a Candidate through Repository and the Product gate, like any edit.
  5. Implementation builds within the decision, and Assurance's conformance Scenarios check the Candidate independently.
  6. Observed scale, repeated failures or a retired dependency can trigger a revisit. Nothing is superseded automatically.

What this does not establish

  • No guide, contract, catalogue entry, model qualification or reviewer exists. The Module appears on the composition map as Proposed.
  • The delivery modes and the decision flow are designs to prove under E39 and E40, not behaviour.
  • Storage and retrieval of records must be reconciled with the Knowledge design draft (KN0) before the first record is written.

Source: docs/architecture-practice.md