Skip to content

ADR-001.md

Latest commit

 

History

History
160 lines (113 loc) · 4.93 KB

ADR-001.md

File metadata and controls

160 lines (113 loc) · 4.93 KB
Raw

ADR-001: Replace Prototype BuildCompiler Structure with Clean Architecture

Status

Accepted.

Context

The current BuildCompiler prototype proves important pieces of the desired workflow, especially level-1 assembly and SBOL digestion/ligation behavior. However, the current structure mixes too many responsibilities in a small number of files:

  • collection indexing
  • SynBioHub pulling
  • plasmid/backbone/reagent tracking
  • domestication
  • level-1 assembly
  • placeholder level-2 assembly
  • transformation
  • plating
  • PUDU JSON conversion
  • manual protocol helpers
  • Opentrons simulation helpers

The new full_build vision requires a dependency-resolving compiler pipeline, partial success semantics, route optimization, structured blockers, approvals, graph/reporting, and optional protocol generation. Preserving old APIs and module boundaries would slow implementation and make Codex work harder to verify.

Decision

Rewrite the internals around a clean architecture while keeping only the root package name buildcompiler.

Do not preserve legacy APIs, compatibility wrappers, or old module boundaries.

The target architecture separates:

api
  public compiler object and options

domain
  stable contracts and normalized domain records

planning
  design classification, validation, combinatorial expansion

execution
  worklist and bounded full-build loop

stages
  biological build operations

sbol
  SBOL resolver and SBOL construction services

inventory
  indexed material lookup and compatibility selection

adapters
  PUDU and Opentrons handoff boundaries

reporting
  graph, summary, report, serialization

Options considered

Option 1: Incrementally patch the existing BuildCompiler class

Pros:

  • Smaller initial diff.
  • May preserve existing notebooks temporarily.
  • Easier to start quickly.

Cons:

  • Reinforces the current god-class structure.
  • Makes partial success and structured blockers awkward.
  • Makes Codex tasks harder to scope.
  • Encourages hidden compatibility behavior.
  • Risks coupling PUDU/Opentrons side effects to compiler-only mode.

Option 2: Preserve public wrappers but move internals

Pros:

  • Gives users a transition path.
  • Reduces immediate breakage.

Cons:

  • Adds compatibility traces the project does not need.
  • Doubles API surface during a major refactor.
  • Forces new contracts to fit old return shapes.
  • Makes partial success harder to expose cleanly.

Option 3: Clean architecture rewrite with no compatibility traces

Pros:

  • Best long-term module boundaries.
  • Makes Codex tasks smaller and safer.
  • Enables testable contracts before complex stages.
  • Separates compiler-only mode from automation side effects.
  • Treats expected build blockers as structured data.
  • Supports route optimization, reporting, and approvals naturally.

Cons:

  • Larger initial migration.
  • Existing notebooks/imports will break.
  • Requires disciplined milestone sequencing.
  • Requires new documentation and tests early.

Rationale

Option 3 is best now because the user explicitly prefers clean architecture over compatibility and wants the current repository treated as inspiration, not an API to preserve.

The new full_build behavior is not a small extension. It is a compiler pipeline with:

  • planning
  • inventory lookup
  • route optimization
  • staged execution
  • retry loops
  • structured missing inputs
  • approval gates
  • SBOL artifacts
  • PUDU JSON adapters
  • reporting

Those concerns need explicit boundaries.

Consequences

  • The root package remains buildcompiler.
  • Existing method signatures such as compiler.assembly_lvl1(raw_component_definition) do not need to survive.
  • BuildCompiler.__init__ becomes dependency-injected and lightweight.
  • BuildCompiler.from_synbiohub(...) owns convenience loading/indexing.
  • Stages use a uniform run(request, context) -> StageResult contract.
  • Inventory records replace the old Plasmid class.
  • PUDU/Opentrons are optional adapters, not core dependencies.
  • Codex should implement in milestone order and keep tests passing at each step.

Risks and mitigations

Risk Mitigation
Rewrite grows too large Implement milestone-by-milestone with tests.
Working level-1 assembly regresses Port current Assembly behavior mostly intact before deeper cleanup.
Users lose old APIs Accepted tradeoff; update docs and examples for new API.
SBOL identity bugs Use identity-based domain contracts and central SbolResolver.
Route optimizer is hard to debug Use explicit score dataclasses and detailed report alternatives.
Automation dependencies destabilize core CI Keep PUDU/Opentrons optional and out of default CI.

Revisit triggers

Revisit this decision if:

  • A downstream user requires stable old APIs for publication or production workflows.
  • SynBioSuite integration depends on old imports.
  • The clean rewrite cannot pass level-1 fixture tests after the assembly service port.
  • A future release needs a compatibility bridge for migration.