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.

Six views, from broad to detailed. All are proposals; the contracts they rely on are in design. The implementation plan index connects these proposals to bounded packets, prerequisites and completion evidence.

The cloud orchestration proposal and owner-presence proposal preserve unfinished designs. Their owner decisions and provider qualification remain open; the historical audit disposition explains the retained evidence limits.

Adoption layers

Module → Workflow → Factory is the required direction of composition. A Module is a bounded building block. A Workflow performs a complete job using Modules or other Workflows. Factory connects those jobs into the full lifecycle. Research, implementation, verification and marketing must each be adoptable without running that entire lifecycle.

LayerExamplesConsumer supplies
ModuleCommand journal, Evidence store, Execution, repository operationsOnly the module's declared configuration and dependencies
WorkflowResearch, implementation, verification, marketingJob inputs and explicitly required collaborators, permissions and limits
FactoryPortfolio coordination and the complete lifecycleSelected Workflows, product configuration and operating policy

Lower layers do not import Factory orchestration or require unrelated Portfolio, Dashboard or global state. Dependencies between Modules and between Workflows are explicit and acyclic; concrete wiring belongs at the consuming boundary. A Workflow calls another through its public contract, never its internal state. Domains still own decisions, and Recipes still describe versioned procedures: neither is a synonym for Workflow.

This is an adoption boundary, not a deployment topology. The current Node.js/SQLite/Git implementation and a single application can remain. Platform requirements must be declared; replacing a safety boundary requires equivalent evidence. Independent adoption defines the proof and records current gaps; no standalone package or complete Workflow is accepted by this diagram.

The future Temporal Planning Module adds sourced date relationships, capacity forecasts and material windows. It combines temporal, research and business-value causes into Events and Command proposals; a separately commissioned adapter checks current authority and delivers them. E36 extends the plan beyond the fixed 23-family audit. The existing four Workflows and E35 composition do not require it.

Future Operational Signal Intake and Repair connect commissioned service observations to independently validated repairs and scoped production evidence. Urgent harm uses independent Operations restoration first. Temporal and business Signals may join the causal record; current authority still governs each dispatch, and source triage remains separate from resolution.

1. Value lifecycle

Customer availability is distinct from assessment, the recorded comparison of observed results with the intended outcome. Supported, rejected and inconclusive assessments all guide the next decision; only an outcome assessed as supported counts as a value win.

Value lifecycle: independent checks and customer observations guide the next Slice.

Open diagram 1 at full size.

View diagram source (Mermaid)
flowchart LR
  OB[Business objective] --> PB[Customer problem]
  PB --> SL[Validated slice]
  SL --> CA[Candidate]
  CA --> VD{Independent verdict}
  VD -->|failed or inconclusive| CA
  VD -->|verified| RL[Safe release and confirmed availability]
  RL --> OC[Assessment]
  OC -->|feedback signals| PB
  OC --> KR{Keep, renew or retire}
  KR -->|renew| SL
  KR -->|retire| RT[Retire with migration]

2. Domains and recovery

Five domains own decisions and three shared foundations serve them. Recovery lives outside the factory.

Decision domains, shared foundations and independent recovery.

Open diagram 2 at full size.

View diagram source (Mermaid)
flowchart TB
  subgraph FA[Factory application]
  PR[Planning: value, priority, retirement] -->|slice| DL[Delivery: build and repair]
  DL -->|candidate| AS[Assurance: independent verdict]
  AS -->|verdict| OP[Operations: release, health, recovery]
  OP -->|confirmed release facts| GR[Growth: docs, site, launch]
  OP -->|health and usage signals| PR
  GR -->|acquisition results| PR
  subgraph FD[Foundations shared by every domain]
    EX[Execution]
    EV[Evidence store]
    AG[Action gateway]
  end
  end
  RC[Independent Operations recovery] -->|restores healthy release and compatible state| FA
  RC -->|availability and recovery without factory| PA[Customer-facing products]

3. Durable runtime

The proposed stack is one modular TypeScript application with PostgreSQL, Temporal and an artefact store. PostgreSQL owns business facts and public run state. One transaction records command results, owned state and events, projections and outbox messages. Temporal owns the execution cursor and deduplicates delivered messages. Terminal runs stay terminal; incomplete runs reconcile against durable step results.

Durable facts, repeated messages and retry-safe Commands.

Open diagram 3 at full size.

View diagram source (Mermaid)
flowchart LR
  C[Command with stable ID] --> D[Owner validates current version]
  D --> TX[Atomic database commit]
  TX --> F[Facts, run state, result and projections]
  TX --> O[Outbox]
  O --> W[Temporal: cursor and timers]
  W -->|Retry-safe next command| D
  F -.->|Views only, no actions| R[Projection rebuild]

Small interfaces, deep implementations

FoundationInterface, hidden detail and first proof
ExecutionStart, inspect or cancel a pinned recipe; hides durable cursor, isolation and worker ownership. Prove crash recovery and stale-worker rejection.
Evidence storeCollect and retrieve attributable evidence; hides storage, integrity and retention. Prove tampering is rejected and deletion survives restore.
Action gatewayRequest or reconcile an authorised effect; hides provider protocols and effect uncertainty. Prove a lost acknowledgement cannot cause a blind repeat.

One application does not mean one privilege identity. Isolated builders cannot write authoritative assurance records or obtain release credentials. Enforce these boundaries through execution identities and protected storage, not import rules alone.

4. Protected release

Independent verdicts gate each exposure, and customer health decides promotion. A manifest links source revision, build inputs and artefact digest, each checked against its own identity.

Protected release, repair routes and observed customer availability.

Open diagram 4 at full size.

View diagram source (Mermaid)
flowchart LR
  CA[Prospective merge-queue candidate] --> AS{Protected scenarios, security, privacy, UI}
  AS -->|failed| RP[Repair]
  RP --> CA
  AS -->|verified| IQ[Integrate exact verified revision]
  IQ --> AV{Risk and product policy}
  AV -->|potentially unsafe| AL[Alpha]
  AV -->|permitted direct release| ST[Stable]
  AL --> HG{Customer health}
  HG -->|harm| RB[Rollback, disable or forward repair]
  RB --> RP
  HG -->|healthy| ST[Stable]
  ST -->|post-release harm| RB
  ST --> AP[Channel receipt and customer-path probe]
  AP --> MS[Assessment]
  AP --> DC[Docs and launch from confirmed availability]
  MS -->|signals| PR[Planning]

5. Capability disposition and health

Retirement and health are independent. Healing restores safe required behaviour, or its approved replacement, and leaves any retirement decision intact.

Capability disposition and health are separate decisions.

Open diagram 5 at full size.

View diagram source (Mermaid)
flowchart LR
  R[Required] -->|Planning decision within authority and policy| T[Retiring]
  T -->|Migration verified, data handled| X[Retired]
  T -->|Retirement reconsidered| R
  H[Healthy] -->|Observed regression| D[Degraded]
  D -->|Safe behaviour re-proved| H
  U[Unknown] -->|Independent observation| H
  U -->|Regression confirmed| D

6. Uncertain external effect

A lost acknowledgement leads to reconciliation, never to a blind second write.

Unknown external effects require reconciliation before another dispatch.

Open diagram 6 at full size.

View diagram source (Mermaid)
sequenceDiagram
  participant D as Owning domain
  participant G as Action gateway
  participant X as External system
  D->>G: Request action with domain occurrence key
  G->>G: Record requested, check current authority, policy, epoch and verdict
  G->>X: Dispatch
  X--xG: Acknowledgement lost
  G->>G: Mark unknown, no blind retry
  G->>X: Reconcile by key
  alt Confirmed
    G->>D: Receipt
  else Proven not applied
    G->>G: Back to requested, recheck guards
  else Still unknown
    G->>G: Durable wait, other work continues
  end

Source: docs/architecture.md