# maillzz/ddt_poker architecture

> Architecture diagram of the GitHub repository maillzz/ddt_poker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maillzz/ddt_poker
- Repository: https://github.com/maillzz/ddt_poker

## Overview

Poker Monte Carlo is a Texas Hold’em decision-support service. Users submit hole cards, board cards, opponents, and betting parameters through the authenticated web form or API; the app validates them, creates an owner-scoped task, runs a Monte Carlo calculation asynchronously, and exposes task status and results. The solver deals unknown cards, evaluates hands, aggregates win/tie/loss and equity, then recommends an action. The README also describes batch, hand-tracking, and hand-rank API capabilities, but those routes are not shown in the sampled API implementation; they are marked as documented-only. Evidence for edges is limited to the README and indexed or excerpted files.

Main entry points: [`web/services.py`](https://github.com/maillzz/ddt_poker/blob/main/web/services.py) (Task service), [`web/views.py`](https://github.com/maillzz/ddt_poker/blob/main/web/views.py) (Web interface), [`core/solver.py`](https://github.com/maillzz/ddt_poker/blob/main/core/solver.py) (Monte Carlo solver), [`api/api.py`](https://github.com/maillzz/ddt_poker/blob/main/api/api.py) (Task API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_web["Web interface<br/>[views.py]"]
  node_form["Poker form<br/>[forms.py]"]
  node_api["Task API<br/>[api.py]"]
  node_task_page["Task results page<br/>[detail.html]"]
  node_documented_api["Additional API capabilities"]
end

subgraph group_validation["Input validation"]
  node_schema["Parameter schema<br/>[schemas.py]"]
end

subgraph group_compute["Calculation"]
  node_solver["Monte Carlo solver<br/>[solver.py]"]
  node_dealing["Card simulation<br/>[solver.py]"]
  node_evaluation["Hand evaluation<br/>[solver.py]"]
  node_recommendation["Action recommendation<br/>[solver.py]"]
end

subgraph group_tasks["Task execution"]
  node_service["Task service<br/>[services.py]"]
  node_store[("Task records<br/>[models.py]")]
  node_thread["Background thread<br/>[services.py]"]
  node_queue["RQ queue<br/>[jobs.py]"]
end

node_player(("Poker player"))

node_player -->|"submits hand"| node_web
node_player -->|"submits task"| node_api
node_web -->|"renders"| node_form
node_web -->|"validates with"| node_schema
node_api -->|"validates with"| node_schema
node_web -->|"creates task"| node_service
node_api -->|"creates task"| node_service
node_service -->|"creates and queries"| node_store
node_service -->|"starts"| node_thread
node_service -.->|"enqueues optionally"| node_queue
node_thread -->|"executes task"| node_service
node_service -->|"runs calculation"| node_solver
node_solver -->|"simulates deals"| node_dealing
node_solver -->|"evaluates hands"| node_evaluation
node_solver -->|"derives action"| node_recommendation
node_web -->|"renders results"| node_task_page
node_documented_api -.->|"extends task API"| node_api

click node_web "https://github.com/maillzz/ddt_poker/blob/main/web/views.py"
click node_form "https://github.com/maillzz/ddt_poker/blob/main/web/forms.py"
click node_api "https://github.com/maillzz/ddt_poker/blob/main/api/api.py"
click node_schema "https://github.com/maillzz/ddt_poker/blob/main/core/schemas.py"
click node_service "https://github.com/maillzz/ddt_poker/blob/main/web/services.py"
click node_store "https://github.com/maillzz/ddt_poker/blob/main/web/models.py"
click node_thread "https://github.com/maillzz/ddt_poker/blob/main/web/services.py"
click node_queue "https://github.com/maillzz/ddt_poker/blob/main/web/jobs.py"
click node_solver "https://github.com/maillzz/ddt_poker/blob/main/core/solver.py"
click node_dealing "https://github.com/maillzz/ddt_poker/blob/main/core/solver.py"
click node_evaluation "https://github.com/maillzz/ddt_poker/blob/main/core/solver.py"
click node_recommendation "https://github.com/maillzz/ddt_poker/blob/main/core/solver.py"
click node_task_page "https://github.com/maillzz/ddt_poker/blob/main/templates/web/detail.html"
click node_documented_api "https://github.com/maillzz/ddt_poker/tree/main/api"

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_web,node_form,node_api,node_task_page,node_documented_api toneBlue
class node_schema toneAmber
class node_solver,node_dealing,node_evaluation,node_recommendation toneMint
class node_service,node_store,node_thread,node_queue toneRose
class node_player toneIndigo
```

## Components

### User interfaces

- [Web interface](https://github.com/maillzz/ddt_poker/blob/main/web/views.py): `web/views.py`
- [Poker form](https://github.com/maillzz/ddt_poker/blob/main/web/forms.py): `web/forms.py`
- [Task API](https://github.com/maillzz/ddt_poker/blob/main/api/api.py): `api/api.py`
- [Task results page](https://github.com/maillzz/ddt_poker/blob/main/templates/web/detail.html): `templates/web/detail.html`
- [Additional API capabilities](https://github.com/maillzz/ddt_poker/tree/main/api): `api`

### Input validation

- [Parameter schema](https://github.com/maillzz/ddt_poker/blob/main/core/schemas.py): `core/schemas.py`

### Calculation

- [Monte Carlo solver](https://github.com/maillzz/ddt_poker/blob/main/core/solver.py): `core/solver.py`
- [Card simulation](https://github.com/maillzz/ddt_poker/blob/main/core/solver.py): `core/solver.py`
- [Hand evaluation](https://github.com/maillzz/ddt_poker/blob/main/core/solver.py): `core/solver.py`
- [Action recommendation](https://github.com/maillzz/ddt_poker/blob/main/core/solver.py): `core/solver.py`

### Task execution

- [Task service](https://github.com/maillzz/ddt_poker/blob/main/web/services.py): `web/services.py`
- [Task records](https://github.com/maillzz/ddt_poker/blob/main/web/models.py): `web/models.py`
- [Background thread](https://github.com/maillzz/ddt_poker/blob/main/web/services.py): `web/services.py`
- [RQ queue](https://github.com/maillzz/ddt_poker/blob/main/web/jobs.py): `web/jobs.py`

### Other components

- **Poker player**

## Connections

- Poker player → Web interface: submits hand
- Poker player → Task API: submits task
- Web interface → Poker form: renders (evidence: `web/views.py`)
- Web interface → Parameter schema: validates with (evidence: `web/views.py`)
- Task API → Parameter schema: validates with (evidence: `api/api.py`)
- Web interface → Task service: creates task (evidence: `web/views.py`)
- Task API → Task service: creates task (evidence: `api/api.py`)
- Task service → Task records: creates and queries (evidence: `web/services.py`)
- Task service → Background thread: starts (evidence: `web/services.py`)
- Task service → RQ queue: enqueues optionally (evidence: `web/services.py`)
- Background thread → Task service: executes task (evidence: `web/services.py`)
- Task service → Monte Carlo solver: runs calculation (evidence: `web/services.py`)
- Monte Carlo solver → Card simulation: simulates deals (evidence: `core/solver.py`)
- Monte Carlo solver → Hand evaluation: evaluates hands (evidence: `core/solver.py`)
- Monte Carlo solver → Action recommendation: derives action (evidence: `core/solver.py`)
- Web interface → Task results page: renders results (evidence: `web/views.py`)
- Additional API capabilities → Task API: extends task API
