Architecture

optiflow converts immutable filesystem observations into evidence-backed reports and review-only plans. Detection never implies deletion authority.

The generated architecture portal provides the interactive system boundary, structural layer, and canonical document graph. This page focuses on the runtime flow and verification model.

Runtime flow

CLI / environment / TOML
          |
          v
  effective policy
          |
          v
      discovery
          |
          v
 content + media inventory
          |
          v
 persistent observations
          +----> media-profile evidence
          |
          +----> exact relationship evidence
          |
          v
 immutable report + plan
          |
          v
 typed command outcome

The v0.1.x authority boundary ends at plan generation. Mutation, transactional replacement, validation, quarantine, and recovery require a separate specification and execution architecture.

Ownership boundaries

optiflow owns discovery policy, observations, content evidence, exact relationship derivation, immutable artifacts, local state, and its versioned CLI contracts.

Current scan outputs are published as a sealed directory set; plan outputs use a recoverable plan-and-marker handshake. The artifact-set protocol defines the visibility, durability, inspection, and recovery boundaries.

Specialized tools remain behind typed adapters. The current media probe invokes one canonical, digest-bound ffprobe executable without a shell and accepts only bounded, semantically valid output. The built-in lossless-PNG profile then derives review evidence from current observations without producing an output or estimating savings. Future encoders, optimizers, quality metrics, and fingerprinters must follow the same explicit capability boundary.

The safe extension SDK adds a second, explicit boundary for provider contributions. A manifest declares; an operator lock pins and grants; the host resolves and revalidates. Embedded roles are registered by type, while process providers use bounded JSON stdio with an absolute byte-pinned executable. Neither path can execute plans, publish artifacts, or receive source-media mutation authority.

Verification loop

specification
  -> schemas and examples
  -> executable tests
  -> implementation
  -> observed evidence
  -> specification refinement

The development model defines the required traceability between behavior, safety invariants, machine contracts, tests, and emitted evidence. The performance budget exercises the same public CLI while keeping its synthetic measurement artifact outside the product contract.

The repository-level architecture reference contains the complete component and data-model inventory.

The root meta-architecture inventory connects the complete purpose, principles, knowledge, domain, system, design, decision, and roadmap document set. Cloud-native placement explains how OptiFlow remains a portable product workload while Realm, Relay, Flow, and infrastructure provide replaceable platform capabilities.