Skip to content

chore: add onboarding doc with architecture diagrams #4288

@Sajjad-Khoshdooni

Description

@Sajjad-Khoshdooni

Background

New contributors currently have to piece together the architecture and service boundaries from multiple READMEs and code. This makes onboarding slower and increases the chance of misunderstanding the end-to-end order → auction → settlement flow.

Details

Create a new docs/ONBOARDING.md that:

  • Explains the high-level architecture of the services in this repo
  • Uses Mermaid diagrams to show:
    • System context (orderbook ↔ DB ↔ autopilot ↔ driver ↔ solvers ↔ chain)
    • The “happy path” sequence from order placement to on-chain settlement
    • Service responsibilities and key crates
  • Includes a “Where to start reading code” section with practical entrypoints
  • Links to existing docs (playground/README.md, database/README.md, docs/COW_ORDER_DEBUG_SKILL.md)

Also add a short link in README.md pointing to docs/ONBOARDING.md for discoverability.

Acceptance criteria

  • docs/ONBOARDING.md exists and renders on GitHub (Mermaid diagrams)
  • docs/ONBOARDING.md includes practical code entrypoints (orderbook/autopilot/driver/solvers/contracts/db)
  • README.md links to docs/ONBOARDING.md
  • Links to referenced docs resolve

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions