Platform Architecture¶

Purpose¶

bf-dev is an integration harness for downstream BetterFleet repositories.

It owns:

• Bootstrap automation (./init, template injection, clone workflow)
• Runtime orchestration (./up, profile.ini, mode selection)
• Local dependency graph (compose.yaml)
• Optional interactive control plane (./menu)

It does not own business logic of downstream services.

Architecture Summary¶

flowchart TD
  subgraph Host[Developer host]
    Scripts[Root scripts]
    Profile[Profile file]
    Templates[Environment templates]
  end

  Scripts --> Compose[Docker Compose]
  Templates --> Init[Secret injection]
  Init --> ServiceEnv[Service env files]
  ServiceEnv --> Compose
  Profile --> Up[Mode filtered startup]
  Up --> Compose

  Compose --> PlanStack[Plan services]
  Compose --> ManageStack[Manage services]
  Compose --> VendorStack[Vendor services]

Key Design Rules¶

• Single orchestration repo for multi-repo local development
• Environment templates are committed; generated .env files are not
• Service startup order is healthcheck-gated where possible
• Mode scoping in ./up prevents mixed-stack startup by default

See Also¶

• Script Runtime Model
• Compose Profiles and Modes
• Repo Topology