id: f9726477e2bb458fa2bf19090ad3eea6
parent_id: 
item_type: 1
item_id: 659da65d964344fc89e6b4eafac0098c
item_updated_time: 1781251946519
title_diff: "[{\"diffs\":[[1,\"Bot Framework Architecture\"]],\"start1\":0,\"start2\":0,\"length1\":0,\"length2\":26}]"
body_diff: "[{\"diffs\":[[1,\"Module architecture for the bot framework in the Rust `rusty-marvin` project. Uses a **strategy framework** with hand analysis, modular strategy composition, and advanced cash-game bots — while keeping proprietary bot logic in a separate private crate.\\\n\\\n---\\\n\\\n## Goals\\\n\\\n1. **Public/Private separation** — Advanced bots live in a private crate excludable from public mirrors\\\n2. **Framework in `holdem_core`** — Traits, helpers, analysis tools remain public and reusable\\\n3. **Idiomatic Rust** — Traits instead of interfaces, enums instead of inheritance, `Option` instead of null\\\n4. **Minimal disruption** — Existing bots and engine code continue to work unchanged\\\n\\\n---\\\n\\\n## Workspace Structure\\\n\\\n```\\\nrusty-marvin/\\\n├── Cargo.toml                    # workspace root\\\n├── holdem_core/                  # PUBLIC crate — framework + simple bots\\\n│   └── src/\\\n│       ├── card.rs, deck.rs, board.rs, hand.rs, hole_cards.rs\\\n│       ├── evaluator/            # 3-tier: Supersonic → Cactus Kev → Algorithmic\\\n│       └── game/\\\n│           ├── player.rs         # HoldemPlayer trait + Seat\\\n│           ├── bot_factory.rs    # Plugin-style registration\\\n│           ├── bots/             # CallBot, FoldBot, RaiseBot, RandomBot, FlockBot, ChumpBot, StrategyBot\\\n│           └── strategy/         # Strategy trait, ModularStrategy, Context, Analyzer, Helper, Recorder\\\n├── holdem_bots/                  # PRIVATE crate — advanced bots\\\n│   └── src/\\\n│       ├── lib.rs                # register_bots()\\\n│       └── cash/                 # BigStackBot, ShortStackBot, PostFlopStrategy\\\n├── holdem_sim/                   # simulation runner\\\n└── docs/\\\n```\\\n\\\n---\\\n\\\n## Key Traits and Relationships\\\n\\\n### Strategy Trait\\\n```rust\\\npub trait Strategy: Send + Sync {\\\n    fn is_applicable(&self, context: &StrategyContext) -> bool;\\\n    fn act(&self, context: &StrategyContext) -> Action;\\\n}\\\n```\\\n\\\n### VotingMode Enum\\\n```rust\\\npub enum VotingMode {\\\n    FirstApplicable,  // First applicable wins\\\n    Democratic,       // Majority vote\\\n    Random,           // Weighted random\\\n}\\\n```\\\n\\\n### ModularStrategy (Composite Pattern)\\\nContains `Vec<Box<dyn Strategy>>` + `VotingMode`. Implements `Strategy` trait.\\\n\\\n### StrategyBot (Adapter)\\\nBridges `Strategy` trait → `HoldemPlayer` trait. Manages per-hand state (hole cards, action recorder).\\\n\\\n### StrategyContext\\\nAggregated decision state: `GameInfo`, `HoleCards`, `ActionRecorder`, `aggressor_id`, `num_raises`, `num_callers`.\\\n\\\n---\\\n\\\n## Java → Rust Idiom Mapping\\\n\\\n| Java | Rust | Notes |\\\n|---|---|---|\\\n| `interface Strategy` | `trait Strategy` | `Send + Sync` bounds |\\\n| `ModularStrategy extends Strategy` | Struct implementing trait | Composition over inheritance |\\\n| `BigStackStrategy extends ModularStrategy` | `BigStackBot` implementing `Strategy` directly | Flat delegation |\\\n| `ModularStrategy implements HoldemPlayer` | `StrategyBot` wraps `Strategy` | Adapter pattern |\\\n| `HandAnalyzer` singleton | `HandAnalyzer` with `Arc<Evaluator>` | `OnceLock` singleton |\\\n| `null` | `Option<T>` | Idiomatic |\\\n\\\n---\\\n\\\n## Bot Factory: Plugin Registration Pattern\\\n\\\n1. `holdem_core` handles built-in bots directly in `create_bot()` — zero overhead\\\n2. `holdem_bots` exports `register_bots()` calling `register_bot_type()` for custom bots\\\n3. `holdem_sim` calls `holdem_bots::register_bots()` behind `#[cfg(feature = \\\"advanced-bots\\\")]`\\\n\\\nDependency flows correctly: `holdem_sim` → `holdem_bots` → `holdem_core`\\\n\\\n---\\\n\\\n## Public vs Private Separation\\\n\\\n**Public (holdem_core):** All traits, analysis tools, ModularStrategy, ActionRecorder, StrategyContext, StrategyBot, simple test bots, evaluator\\\n\\\n**Private (holdem_bots):** BigStackBot, ShortStackBot, preflop strategy tables, PostFlopStrategy, future proprietary bots\\\n\\\nConditional compilation via `#[cfg(feature = \\\"advanced-bots\\\")]` in holdem_sim.\\\n\\\n---\\\n\\\n## Design Decisions\\\n\\\n- **Strategy separate from HoldemPlayer:** Strategy is a decision interface; HoldemPlayer is a lifecycle interface. Allows composition and isolated testing.\\\n- **StrategyBot adapter over ModularStrategy implementing HoldemPlayer:** Keeps strategy framework pure, manages per-hand state in one place.\\\n- **Plugin registry over hardcoded match:** Allows holdem_bots to register without holdem_core knowing about it.\\\n- **OnceLock over Lazy:** Already in std::sync, no extra dependency needed.\"]],\"start1\":0,\"start2\":0,\"length1\":0,\"length2\":4295}]"
metadata_diff: {"new":{"id":"659da65d964344fc89e6b4eafac0098c","parent_id":"2c8da247905946c3aa19eb4936e16323","latitude":"0.00000000","longitude":"0.00000000","altitude":"0.0000","author":"","source_url":"","is_todo":0,"todo_due":0,"todo_completed":0,"source":"joplin-desktop","source_application":"net.cozic.joplin-desktop","application_data":"","order":1780223822827,"markup_language":1,"is_shared":0,"share_id":"","conflict_original_id":"","master_key_id":"","user_data":"","deleted_time":0},"deleted":[]}
encryption_cipher_text: 
encryption_applied: 0
updated_time: 2026-06-12T08:16:35.051Z
created_time: 2026-06-12T08:16:35.051Z
type_: 13