Skip to content

Architecture Diagrams

PlantUML diagrams documenting the Pydantic AI Trading Agent architecture.

Diagrams

1. System Architecture

File: 01-system-architecture.puml

Complete system overview showing all layers: - User Interface Layer (CLI, Interactive, API) - AI Agent Layer (Claude Sonnet 4.5) - Tools Layer (8 trading tools) - Data & State Layer (Pydantic models) - Integration Layer (Uniswap V3, Blockchain)

Use this to: Understand the overall system structure and component relationships.

2. Trade Execution Flow

File: 02-trade-execution-flow.puml

Sequence diagram showing the complete trade execution workflow: - User requests trade - Agent analyzes market data - Agent calculates position size - Validation and execution - Position creation

Use this to: Understand how a trade flows from user request to execution.

3. Position Monitoring Flow

File: 03-position-monitoring-flow.puml

Sequence diagram showing automatic position monitoring: - Regular position status checks - Take-profit detection and execution - Stop-loss detection and execution - P&L tracking

Use this to: Understand how risk management is enforced automatically.

4. Risk Management Layers

File: 04-risk-management-layers.puml

Architecture diagram showing the 4 layers of risk enforcement: 1. System Prompt - AI-level rules 2. Pydantic Validation - Input validation 3. Tool-Level Checks - Business logic 4. Position Monitoring - Runtime management

Use this to: Understand the defense-in-depth risk management strategy.

5. Data Models

File: 05-data-models.puml

Class diagram showing all Pydantic models: - PortfolioState - Portfolio container - Position - Open position tracking - ExitPlan - TP/SL configuration - ClosedPosition - Historical positions - PoolMetrics - Uniswap V3 pool data - PriceHistory - Historical price data - TechnicalIndicators - Analysis indicators

Use this to: Understand the data structures and their relationships.

6. Component Interactions

File: 06-component-interactions.puml

Component diagram showing how system parts interact: - CLI → Agent → Tools → State - Tool categorization (Market/Execution/Risk) - Type safety flow through Pydantic

Use this to: Understand component dependencies and data flow.

7. Kelly Criterion Flow

File: 07-kelly-criterion-flow.puml

Sequence diagram showing position sizing calculation: - Kelly Criterion formula application - Fractional Kelly (0.25x safety factor) - Risk caps and portfolio constraints - Final position size calculation

Use this to: Understand how position sizes are mathematically calculated.

Viewing Diagrams

Online Viewers

  1. PlantUML Online Editor
  2. Visit: http://www.plantuml.com/plantuml/uml/
  3. Paste diagram code

  4. View rendered diagram

  5. PlantText

  6. Visit: https://www.planttext.com/
  7. Paste diagram code
  8. Generate and download

Local Rendering

Using PlantUML CLI: 

# Install PlantUML
brew install plantuml  # macOS
apt-get install plantuml  # Linux

# Render all diagrams
plantuml docs/diagrams/*.puml

# Render to PNG
plantuml -tpng docs/diagrams/*.puml

# Render to SVG
plantuml -tsvg docs/diagrams/*.puml

Using VS Code: 1. Install "PlantUML" extension 2. Open any .puml file 3. Press Alt+D to preview 4. Right-click → "Export Current Diagram"

Using IntelliJ/PyCharm: 1. Install "PlantUML Integration" plugin 2. Open any .puml file 3. Preview appears automatically 4. Right-click → "Copy Diagram to Clipboard"

Docker Method

# Run PlantUML server
docker run -d -p 8080:8080 plantuml/plantuml-server

# Open browser to http://localhost:8080
# Upload .puml files to render

Generating Images

To generate PNG images from all diagrams:

# From project root
cd docs/diagrams

# Generate PNGs
for file in *.puml; do
    plantuml -tpng "$file"
done

# Generate SVGs (better for documentation)
for file in *.puml; do
    plantuml -tsvg "$file"
done

This will create .png or .svg files alongside each .puml file.

Embedding in Documentation

Markdown: 

![System Architecture](docs/diagrams/01-system-architecture.png)

HTML: 

<img src="docs/diagrams/01-system-architecture.svg" alt="System Architecture">

GitHub: GitHub automatically renders PlantUML in README files if you use the PlantUML server:

![](http://www.plantuml.com/plantuml/proxy?src=https://raw.githubusercontent.com/user/repo/main/docs/diagrams/01-system-architecture.puml)

Diagram Conventions

  • Colors:
  • Light Blue: User Interface / Input
  • Light Green: AI / Logic Layer
  • Light Yellow: Tools / Processing
  • Light Coral: State / Storage

  • Wheat: External / Integration

  • Arrow Types:

  • Solid --> : Direct call/dependency
  • Dashed -.-> : Indirect/future integration

  • Dotted ..> : Data flow

  • Box Types:

  • component : Software component
  • package : Logical grouping
  • database : Persistent state
  • class : Data model

Contributing

When adding new diagrams:

  1. Use sequential numbering: 08-your-diagram.puml
  2. Add description to this README
  3. Follow naming convention: lowercase with hyphens
  4. Include title and notes in diagram
  5. Keep diagrams focused on single concept
  6. Test rendering before committing

Resources