# mmadrb/volume-profile-order-flow-analysis-vpofa architecture

> Architecture diagram of the GitHub repository mmadrb/volume-profile-order-flow-analysis-vpofa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mmadrb/volume-profile-order-flow-analysis-vpofa
- Repository: https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa
- Video tour (about a minute): https://gitdiagram.com/mmadrb/volume-profile-order-flow-analysis-vpofa/video

## Overview

VPOFA V8 is a modular ML trading system for crypto perpetual futures, with research/backtesting, paper and live execution, and model lifecycle capabilities. The principal trading flow is an order command handled by the application layer, then passed through execution routing to a venue adapter; risk analysis and model-driven signal generation are distinct supporting stages. The graph also shows documented feature-store, governance, drift/retraining, and explainability branches. Wiring for unsampled subsystems is based on README capabilities and module names; uncertain call relationships are omitted.

Main entry points: [`vpofa6_v8/application/handlers.py`](https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/blob/master/vpofa6_v8/application/handlers.py) (Command handlers), [`vpofa6_v8/mlops/retrain/pipeline.py`](https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/blob/master/vpofa6_v8/mlops/retrain/pipeline.py) (Retraining pipeline), [`vpofa6_v8/agents/orchestrator/orchestrator.py`](https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/blob/master/vpofa6_v8/agents/orchestrator/orchestrator.py) (Agent orchestrator), [`vpofa6_v8/execution/engine/execution_engine.py`](https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/blob/master/vpofa6_v8/execution/engine/execution_engine.py) (Execution engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application and domain"]
  node_handlers["Command handlers<br/>[handlers.py]"]
  node_domain["Trading domain<br/>[entities.py]"]
  node_domain_services["Domain services<br/>[services.py]"]
  node_persistence[("Application repositories")]
end

subgraph group_intelligence["Data and intelligence"]
  node_agent_orchestrator["Agent orchestrator<br/>[orchestrator.py]"]
  node_feature_agent["Feature agent"]
  node_features["Order-flow features"]
  node_feature_store[("Feature store")]
  node_ensemble["Model ensembles"]
  node_rl["Reinforcement learning"]
  node_xai["Decision explanations"]
end

subgraph group_trading["Trading runtime"]
  node_execution_engine["Execution engine"]
  node_router["Smart order router"]
  node_adapters["Broker adapters"]
end

subgraph group_governance["Model governance"]
  node_drift["Drift detection<br/>[drift_engine.py]"]
  node_retrainer["Retraining pipeline<br/>[pipeline.py]"]
  node_registry[("Model registry")]
end

subgraph group_operations["Risk and operations"]
  node_risk_engine["Risk engine<br/>[engine.py]"]
  node_risk_models["Risk calculations"]
  node_s3[("Artifact storage<br/>[s3_storage.py]")]
  node_monitoring["Monitoring and alerts"]
end

node_user(("Trader or operator"))
node_venue(("Exchange or broker"))

node_user -->|"submits command"| node_handlers
node_handlers -->|"creates or updates"| node_domain
node_handlers -->|"reads and writes"| node_persistence
node_handlers -->|"dispatches order callback"| node_execution_engine
node_execution_engine -->|"selects venue"| node_router
node_execution_engine -->|"submits and cancels"| node_adapters
node_adapters -->|"sends orders"| node_venue
node_agent_orchestrator -->|"runs cycle step"| node_feature_agent
node_feature_agent -->|"returns proposal"| node_agent_orchestrator
node_agent_orchestrator -->|"processes market data"| node_features
node_risk_engine -->|"computes risk metrics"| node_risk_models
node_drift -.->|"signals retraining"| node_retrainer
node_retrainer -->|"compares and promotes"| node_registry
node_retrainer -->|"generates explanations"| node_xai
node_retrainer -.->|"stores artifacts"| node_s3

click node_handlers "https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/blob/master/vpofa6_v8/application/handlers.py"
click node_domain "https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/blob/master/vpofa6_v8/domain/entities.py"
click node_domain_services "https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/blob/master/vpofa6_v8/domain/services.py"
click node_agent_orchestrator "https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/blob/master/vpofa6_v8/agents/orchestrator/orchestrator.py"
click node_feature_agent "https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/blob/master/vpofa6_v8/agents/specialized/feature_engineering_agent.py"
click node_features "https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/tree/master/vpofa6_v8/orderflow"
click node_feature_store "https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/tree/master/vpofa6_v8/feature_store"
click node_ensemble "https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/tree/master/vpofa6_v8/ensemble"
click node_rl "https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/tree/master/vpofa6_v8/rl"
click node_xai "https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/tree/master/vpofa6_v8/xai"
click node_execution_engine "https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/blob/master/vpofa6_v8/execution/engine/execution_engine.py"
click node_router "https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/blob/master/vpofa6_v8/execution/routing/smart_order_router.py"
click node_adapters "https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/tree/master/vpofa6_v8/execution/adapters"
click node_risk_engine "https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/blob/master/vpofa6_v8/risk/engine.py"
click node_risk_models "https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/tree/master/vpofa6_v8/risk"
click node_drift "https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/blob/master/vpofa6_v8/drift/drift_engine.py"
click node_retrainer "https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/blob/master/vpofa6_v8/mlops/retrain/pipeline.py"
click node_registry "https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/tree/master/vpofa6_v8/model_registry"
click node_persistence "https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/tree/master/vpofa6_v8/infrastructure/persistence"
click node_s3 "https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/blob/master/vpofa6_v8/infrastructure/storage/s3_storage.py"
click node_monitoring "https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/tree/master/vpofa6_v8/mlops/monitoring"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_handlers,node_domain,node_domain_services,node_persistence toneBlue
class node_agent_orchestrator,node_feature_agent,node_features,node_feature_store,node_ensemble,node_rl,node_xai toneAmber
class node_execution_engine,node_router,node_adapters toneMint
class node_drift,node_retrainer,node_registry toneRose
class node_risk_engine,node_risk_models,node_s3,node_monitoring,node_user,node_venue toneIndigo
```

## Components

### Application and domain

- [Command handlers](https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/blob/master/vpofa6_v8/application/handlers.py): `vpofa6_v8/application/handlers.py`
- [Trading domain](https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/blob/master/vpofa6_v8/domain/entities.py): `vpofa6_v8/domain/entities.py`
- [Domain services](https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/blob/master/vpofa6_v8/domain/services.py): `vpofa6_v8/domain/services.py`
- [Application repositories](https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/tree/master/vpofa6_v8/infrastructure/persistence): `vpofa6_v8/infrastructure/persistence`

### Data and intelligence

- [Agent orchestrator](https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/blob/master/vpofa6_v8/agents/orchestrator/orchestrator.py): `vpofa6_v8/agents/orchestrator/orchestrator.py`
- [Feature agent](https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/blob/master/vpofa6_v8/agents/specialized/feature_engineering_agent.py): `vpofa6_v8/agents/specialized/feature_engineering_agent.py`
- [Order-flow features](https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/tree/master/vpofa6_v8/orderflow): `vpofa6_v8/orderflow`
- [Feature store](https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/tree/master/vpofa6_v8/feature_store): `vpofa6_v8/feature_store`
- [Model ensembles](https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/tree/master/vpofa6_v8/ensemble): `vpofa6_v8/ensemble`
- [Reinforcement learning](https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/tree/master/vpofa6_v8/rl): `vpofa6_v8/rl`
- [Decision explanations](https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/tree/master/vpofa6_v8/xai): `vpofa6_v8/xai`

### Trading runtime

- [Execution engine](https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/blob/master/vpofa6_v8/execution/engine/execution_engine.py): `vpofa6_v8/execution/engine/execution_engine.py`
- [Smart order router](https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/blob/master/vpofa6_v8/execution/routing/smart_order_router.py): `vpofa6_v8/execution/routing/smart_order_router.py`
- [Broker adapters](https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/tree/master/vpofa6_v8/execution/adapters): `vpofa6_v8/execution/adapters`

### Model governance

- [Drift detection](https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/blob/master/vpofa6_v8/drift/drift_engine.py): `vpofa6_v8/drift/drift_engine.py`
- [Retraining pipeline](https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/blob/master/vpofa6_v8/mlops/retrain/pipeline.py): `vpofa6_v8/mlops/retrain/pipeline.py`
- [Model registry](https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/tree/master/vpofa6_v8/model_registry): `vpofa6_v8/model_registry`

### Risk and operations

- [Risk engine](https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/blob/master/vpofa6_v8/risk/engine.py): `vpofa6_v8/risk/engine.py`
- [Risk calculations](https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/tree/master/vpofa6_v8/risk): `vpofa6_v8/risk`
- [Artifact storage](https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/blob/master/vpofa6_v8/infrastructure/storage/s3_storage.py): `vpofa6_v8/infrastructure/storage/s3_storage.py`
- [Monitoring and alerts](https://github.com/mmadrb/volume-profile-order-flow-analysis-vpofa/tree/master/vpofa6_v8/mlops/monitoring): `vpofa6_v8/mlops/monitoring`

### Other components

- **Trader or operator**
- **Exchange or broker**

## Connections

- Trader or operator → Command handlers: submits command
- Command handlers → Trading domain: creates or updates
- Command handlers → Application repositories: reads and writes
- Command handlers → Execution engine: dispatches order callback
- Execution engine → Smart order router: selects venue
- Execution engine → Broker adapters: submits and cancels
- Broker adapters → Exchange or broker: sends orders
- Agent orchestrator → Feature agent: runs cycle step
- Feature agent → Agent orchestrator: returns proposal
- Agent orchestrator → Order-flow features: processes market data
- Risk engine → Risk calculations: computes risk metrics
- Drift detection → Retraining pipeline: signals retraining
- Retraining pipeline → Model registry: compares and promotes
- Retraining pipeline → Decision explanations: generates explanations
- Retraining pipeline → Artifact storage: stores artifacts