Enhanced Mermaid Diagrams

These enhanced diagrams use simpler syntax with improved readability. They replace the more complex diagrams from the original documentation that may not render correctly in MkDocs.

Monorepo Development Workflow

This diagram shows the standard development workflow for the v4-monorepo.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e6f7ff', 'primaryTextColor': '#003366', 'primaryBorderColor': '#0066cc', 'lineColor': '#0066cc', 'secondaryColor': '#ffd700', 'tertiaryColor': '#f9f9f9' }}}%%
graph TD
    Start([Start Development]) --> Clone[Clone Repository]
    Clone --> Install[Install Dependencies<br>yarn install]

    subgraph Phase1[Setup Phase]
        Install --> SetupLocal[Setup Local Environment<br>cp .env.example .env.local]
        SetupLocal --> SetupDB[Setup Databases<br>docker-compose up -d]
    end

    subgraph Phase2[Development Phase]
        SetupDB --> Implement[Implement Feature/Fix]

        Implement --> BuildLib[Build Libraries<br>nx build lib-name]
        Implement --> Lint[Lint Code<br>nx lint app-name]
        Implement --> UnitTest[Run Unit Tests<br>nx test app-name]

        BuildLib --> DevFlow{Development<br>Complete?}
        Lint --> DevFlow
        UnitTest --> DevFlow

        DevFlow -->|No| Implement
    end

    subgraph Phase3[Validation Phase]
        DevFlow -->|Yes| Validate[Validate All Changes<br>nx affected -t build lint test]
        Validate --> Integration[Run Integration Tests]
    end

    subgraph Phase4[Submission Phase]
        Integration --> Branch[Create Branch]
        Branch --> Commit[Commit Changes]
        Commit --> Push[Push Changes]
        Push --> PR[Create Pull Request]
        PR --> Review[Code Review Process]

        Review -->|Approved| Merge[Merge PR]
        Review -->|Changes Requested| Implement
    end

    Merge --> End([End Development])

    %% Styling
    classDef start fill:#6cc24a,stroke:#0e7111,color:#fff,stroke-width:2px,font-weight:bold
    classDef end fill:#ff9a9a,stroke:#b30000,color:#fff,stroke-width:2px,font-weight:bold
    classDef phase fill:#f4f4f4,stroke:#999,stroke-width:1px
    classDef flow fill:#cfe2f3,stroke:#0b5394,stroke-width:1px
    classDef decision fill:#ffd966,stroke:#bf9000,stroke-width:1px

    class Start,End start
    class Phase1,Phase2,Phase3,Phase4 phase
    class Clone,Install,SetupLocal,SetupDB,Implement,BuildLib,Lint,UnitTest,Validate,Integration,Branch,Commit,Push,PR,Review,Merge flow
    class DevFlow decision

Command Selection Decision Tree

This diagram helps you select the right NX command for your task.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#f0f8ff', 'primaryTextColor': '#333333', 'primaryBorderColor': '#4682b4', 'lineColor': '#4682b4', 'secondaryColor': '#fffacd', 'tertiaryColor': '#f9f9f9' }}}%%
graph TD
    Start([Command Needed]) --> TaskType{What task are you doing?}

    TaskType -->|Building| Build{What to build?}
    TaskType -->|Testing| Test{What to test?}
    TaskType -->|Developing| Dev{Development task?}

    Build -->|One project| BuildOne[nx build project-name]
    Build -->|Affected projects| BuildAffected[nx affected -t build]
    Build -->|All projects| BuildAll[nx run-many -t build]

    Test -->|Unit tests| TestUnit[nx test project-name]
    Test -->|Integration tests| TestInteg[nx test --config=jest.integration.config.ts]
    Test -->|Affected tests| TestAffected[nx affected -t test]

    Dev -->|Lint| Lint[nx lint project-name]
    Dev -->|Type check| TypeCheck[nx run project-name:typecheck]
    Dev -->|Start service| Serve[nx serve project-name]
    Dev -->|Full validation| Validate[nx run project-name:validate]

    BuildOne --> Done([Command Selected])
    BuildAffected --> Done
    BuildAll --> Done
    TestUnit --> Done
    TestInteg --> Done
    TestAffected --> Done
    Lint --> Done
    TypeCheck --> Done
    Serve --> Done
    Validate --> Done

    %% Styling
    classDef start fill:#6cc24a,stroke:#0e7111,color:#fff,stroke-width:2px,font-weight:bold
    classDef end fill:#ff9a9a,stroke:#b30000,color:#fff,stroke-width:2px,font-weight:bold
    classDef decision fill:#ffd966,stroke:#bf9000,stroke-width:1px
    classDef command fill:#d0e0e3,stroke:#0e7111,stroke-width:1px

    class Start,Done start
    class TaskType,Build,Test,Dev decision
    class BuildOne,BuildAffected,BuildAll,TestUnit,TestInteg,TestAffected,Lint,TypeCheck,Serve,Validate command

Troubleshooting Decision Tree

This diagram helps you diagnose and resolve common errors.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#f0f8ff', 'primaryTextColor': '#333333', 'primaryBorderColor': '#4682b4', 'lineColor': '#4682b4', 'secondaryColor': '#ffe6e6', 'tertiaryColor': '#f9f9f9' }}}%%
graph TD
    Start([Error Encountered]) --> ErrorType{What type of error?}

    ErrorType -->|Build Failure| BuildError{Build error type?}
    ErrorType -->|Test Failure| TestError{Test error type?}
    ErrorType -->|Runtime Error| RuntimeError{Runtime error type?}

    BuildError -->|Dependency| DependencyIssue[Check package versions<br>yarn install]
    BuildError -->|TypeScript| TSError[Check types<br>nx run project:typecheck]
    BuildError -->|Memory| MemoryError[Use retry build<br>nx run project:build:retry]

    TestError -->|Test not found| TestNotFound[Check test path<br>Check test configuration]
    TestError -->|Timeout| TestTimeout[Increase timeout<br>Fix slow tests]
    TestError -->|Environment| TestEnvError[Setup mock environment<br>Check .env.test]

    RuntimeError -->|Connection| ConnectionError[Check service connectivity<br>Verify database connection]
    RuntimeError -->|Configuration| ConfigError[Verify environment variables<br>Check config files]
    RuntimeError -->|Resource| ResourceError[Check resource limits<br>Increase allocation]

    DependencyIssue --> Solution([Solution Found])
    TSError --> Solution
    MemoryError --> Solution
    TestNotFound --> Solution
    TestTimeout --> Solution
    TestEnvError --> Solution
    ConnectionError --> Solution
    ConfigError --> Solution
    ResourceError --> Solution

    %% Styling
    classDef start fill:#6cc24a,stroke:#0e7111,color:#fff,stroke-width:2px,font-weight:bold
    classDef end fill:#ff9a9a,stroke:#b30000,color:#fff,stroke-width:2px,font-weight:bold
    classDef decision fill:#ffd966,stroke:#bf9000,stroke-width:1px
    classDef action fill:#d0e0e3,stroke:#0c343d,stroke-width:1px

    class Start start
    class Solution end
    class ErrorType,BuildError,TestError,RuntimeError decision
    class DependencyIssue,TSError,MemoryError,TestNotFound,TestTimeout,TestEnvError,ConnectionError,ConfigError,ResourceError action

Component Architecture Diagram

This diagram shows the component architecture of the v4-monorepo system.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e6f7ff', 'primaryTextColor': '#003366', 'primaryBorderColor': '#0066cc', 'lineColor': '#0066cc', 'secondaryColor': '#fff2cc', 'tertiaryColor': '#f9f9f9' }}}%%
graph TB
    subgraph "Service Layer"
        Orderbook["Orderbook Service<br>(Trading Engine)"]
        Sequencer["Sequencer<br>(Risk & Accounts)"]
        Datastream["Datastream<br>(Market Data)"]
        Relayer["Relayer<br>(Web3 Transaction)"]
        Websockets["Websockets<br>(Real-time Events)"]
    end

    subgraph "Libraries Layer"
        CommonsTS["commons-ts<br>(TS Utilities)"]
        Commons["commons<br>(Python Utilities)"]
        ConnectionsTS["connections-ts<br>(DB Connectors)"]
        Chainpyon["chainpyon<br>(Web3 Python)"]
    end

    subgraph "External Integrations"
        Blockchain["Blockchain<br>(Smart Contracts)"]
        PriceFeeds["Price Feeds<br>(Index & IV)"]
    end

    subgraph "Storage Layer"
        Redis["Redis<br>(Cache)"]
        CloudSQL["Cloud SQL<br>(State)"]
        BigQuery["BigQuery<br>(Analytics)"]
    end

    %% Service dependencies
    Orderbook -->|uses| CommonsTS
    Orderbook -->|uses| ConnectionsTS
    Sequencer -->|uses| CommonsTS
    Sequencer -->|uses| ConnectionsTS
    Datastream -->|uses| CommonsTS
    Datastream -->|uses| ConnectionsTS

    %% Service interactions
    Orderbook <-->|events| Sequencer
    Orderbook -->|publishes to| Websockets
    Sequencer -->|executes via| Relayer
    Datastream -->|provides data to| Orderbook

    %% External integrations
    Relayer <-->|transactions| Blockchain
    Datastream <-->|market data| PriceFeeds

    %% Storage connections
    Orderbook <-->|cache| Redis
    Orderbook <-->|storage| CloudSQL
    Sequencer <-->|cache| Redis
    Sequencer <-->|storage| CloudSQL

    %% Styling
    classDef service fill:#cfe2f3,stroke:#0b5394,stroke-width:2px
    classDef library fill:#fff2cc,stroke:#bf9000,stroke-width:2px
    classDef external fill:#d9ead3,stroke:#38761d,stroke-width:2px
    classDef storage fill:#f4cccc,stroke:#990000,stroke-width:2px

    class Orderbook,Sequencer,Datastream,Relayer,Websockets service
    class CommonsTS,Commons,ConnectionsTS,Chainpyon library
    class Blockchain,PriceFeeds external
    class Redis,CloudSQL,BigQuery storage