# lorserker/ben architecture

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

- Interactive diagram: https://gitdiagram.com/lorserker/ben
- Repository: https://github.com/lorserker/ben
- Video tour (about a minute): https://gitdiagram.com/lorserker/ben/video

## Overview

BEN is a bridge engine for robot play, hand analysis, and AI development. The principal user workflow is to open the browser UI, start a board, bid and play against bots, then review the hand. The runtime also supports standalone game runs and a REST API, while bidding, opening-lead, and card-play models provide distinct decision stages alongside double-dummy analysis. The README documents the service boundaries and capabilities; sampled source excerpts are partial, so internal call wiring beyond those documented boundaries is kept conservative.

Main entry points: [`src/game.py`](https://github.com/lorserker/ben/blob/main/src/game.py) (Game state), [`src/carding.py`](https://github.com/lorserker/ben/blob/main/src/carding.py) (Card play), [`src/bidding/bidding.py`](https://github.com/lorserker/ben/blob/main/src/bidding/bidding.py) (Bidding engine), [`src/nn`](https://github.com/lorserker/ben/tree/main/src/nn) (Neural models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_services["Runtime services"]
  node_appserver["Web app server<br/>[appserver.py]"]
  node_gameserver["Game server<br/>[gameserver.py]"]
  node_gameapi["Game API<br/>[gameapi.py]"]
end

subgraph group_gameplay["Bridge gameplay"]
  node_game["Game runner<br/>[game.py]"]
  node_gamecore["Game state<br/>[game.py]"]
  node_bidding["Bidding engine<br/>[bidding.py]"]
  node_openinglead["Opening lead<br/>[openinglead.py]"]
  node_cardplay["Card play<br/>[carding.py]"]
  node_pbn["Deal formats<br/>[pbn.py]"]
end

subgraph group_intelligence["Decision engines"]
  node_nn["Neural models"]
  node_sampler["Deal sampler<br/>[sample.py]"]
  node_dds["Double-dummy solver<br/>[ddsolver.py]"]
  node_pimc["PIMC engine<br/>[PIMC.py]"]
  node_ace["ACE defender<br/>[ACE.py]"]
  node_bba["BBA bidder<br/>[BBA.py]"]
end

subgraph group_interfaces["User interfaces"]
  node_tableclient["Table manager client"]
  node_viz["Hand visualizer<br/>[viz.js]"]
end

node_player(("Bridge player"))
node_browser(("Browser"))
node_dds_ext["DDS extension<br/>[__init__.py]"]

node_player -->|"plays through"| node_browser
node_browser -->|"requests UI"| node_appserver
node_appserver -->|"serves UI"| node_browser
node_browser -->|"plays via WebSocket"| node_gameserver
node_gameserver -->|"serves game API"| node_gamecore
node_game -->|"reads deal formats"| node_pbn
node_game -->|"runs boards"| node_gamecore
node_gamecore -->|"requests bids"| node_bidding
node_gamecore -->|"requests lead"| node_openinglead
node_gamecore -->|"requests plays"| node_cardplay
node_bidding -->|"uses bid models"| node_nn
node_openinglead -->|"uses lead models"| node_nn
node_cardplay -->|"uses play models"| node_nn
node_gamecore -->|"requests analysis"| node_dds
node_dds -->|"calls solver"| node_dds_ext
node_gamecore -->|"samples deals"| node_sampler
node_cardplay -.->|"uses search"| node_pimc
node_cardplay -.->|"uses defender"| node_ace
node_bidding -.->|"uses BBA"| node_bba
node_player -.->|"connects to table"| node_tableclient
node_tableclient -.->|"plays boards"| node_gamecore
node_browser -->|"reviews hands"| node_viz
node_gameapi -->|"exposes operations"| node_gamecore

click node_appserver "https://github.com/lorserker/ben/blob/main/src/frontend/appserver.py"
click node_gameserver "https://github.com/lorserker/ben/blob/main/src/gameserver.py"
click node_gameapi "https://github.com/lorserker/ben/blob/main/src/gameapi.py"
click node_game "https://github.com/lorserker/ben/blob/main/src/game.py"
click node_gamecore "https://github.com/lorserker/ben/blob/main/src/game.py"
click node_bidding "https://github.com/lorserker/ben/blob/main/src/bidding/bidding.py"
click node_openinglead "https://github.com/lorserker/ben/blob/main/src/openinglead/openinglead.py"
click node_cardplay "https://github.com/lorserker/ben/blob/main/src/carding.py"
click node_pbn "https://github.com/lorserker/ben/blob/main/src/pbn.py"
click node_nn "https://github.com/lorserker/ben/tree/main/src/nn"
click node_sampler "https://github.com/lorserker/ben/blob/main/src/sample.py"
click node_dds "https://github.com/lorserker/ben/blob/main/src/ddsolver/ddsolver.py"
click node_pimc "https://github.com/lorserker/ben/blob/main/src/pimc/PIMC.py"
click node_ace "https://github.com/lorserker/ben/blob/main/src/ace/ACE.py"
click node_bba "https://github.com/lorserker/ben/blob/main/src/bba/BBA.py"
click node_tableclient "https://github.com/lorserker/ben/blob/main/src/table_manager_client.py"
click node_viz "https://github.com/lorserker/ben/blob/main/src/frontend/viz.js"
click node_dds_ext "https://github.com/lorserker/ben/blob/main/bin/dds3-linux/dds3/__init__.py"

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_appserver,node_gameserver,node_gameapi,node_browser toneBlue
class node_game,node_gamecore,node_bidding,node_openinglead,node_cardplay,node_pbn toneAmber
class node_nn,node_sampler,node_dds,node_pimc,node_ace,node_bba toneMint
class node_tableclient,node_viz toneRose
class node_player toneIndigo
class node_dds_ext toneTeal
```

## Components

### Runtime services

- [Web app server](https://github.com/lorserker/ben/blob/main/src/frontend/appserver.py): `src/frontend/appserver.py`
- [Game server](https://github.com/lorserker/ben/blob/main/src/gameserver.py): `src/gameserver.py`
- [Game API](https://github.com/lorserker/ben/blob/main/src/gameapi.py): `src/gameapi.py`

### Bridge gameplay

- [Game runner](https://github.com/lorserker/ben/blob/main/src/game.py): `src/game.py`
- [Game state](https://github.com/lorserker/ben/blob/main/src/game.py): `src/game.py`
- [Bidding engine](https://github.com/lorserker/ben/blob/main/src/bidding/bidding.py): `src/bidding/bidding.py`
- [Opening lead](https://github.com/lorserker/ben/blob/main/src/openinglead/openinglead.py): `src/openinglead/openinglead.py`
- [Card play](https://github.com/lorserker/ben/blob/main/src/carding.py): `src/carding.py`
- [Deal formats](https://github.com/lorserker/ben/blob/main/src/pbn.py): `src/pbn.py`

### Decision engines

- [Neural models](https://github.com/lorserker/ben/tree/main/src/nn): `src/nn`
- [Deal sampler](https://github.com/lorserker/ben/blob/main/src/sample.py): `src/sample.py`
- [Double-dummy solver](https://github.com/lorserker/ben/blob/main/src/ddsolver/ddsolver.py): `src/ddsolver/ddsolver.py`
- [PIMC engine](https://github.com/lorserker/ben/blob/main/src/pimc/PIMC.py): `src/pimc/PIMC.py`
- [ACE defender](https://github.com/lorserker/ben/blob/main/src/ace/ACE.py): `src/ace/ACE.py`
- [BBA bidder](https://github.com/lorserker/ben/blob/main/src/bba/BBA.py): `src/bba/BBA.py`

### User interfaces

- [Table manager client](https://github.com/lorserker/ben/blob/main/src/table_manager_client.py): `src/table_manager_client.py`
- [Hand visualizer](https://github.com/lorserker/ben/blob/main/src/frontend/viz.js): `src/frontend/viz.js`

### Other components

- **Bridge player**
- **Browser**
- [DDS extension](https://github.com/lorserker/ben/blob/main/bin/dds3-linux/dds3/__init__.py): `bin/dds3-linux/dds3/__init__.py`

## Connections

- Bridge player → Browser: plays through
- Browser → Web app server: requests UI
- Web app server → Browser: serves UI
- Browser → Game server: plays via WebSocket
- Game server → Game state: serves game API
- Game runner → Deal formats: reads deal formats
- Game runner → Game state: runs boards
- Game state → Bidding engine: requests bids
- Game state → Opening lead: requests lead
- Game state → Card play: requests plays
- Bidding engine → Neural models: uses bid models
- Opening lead → Neural models: uses lead models
- Card play → Neural models: uses play models
- Game state → Double-dummy solver: requests analysis
- Double-dummy solver → DDS extension: calls solver
- Game state → Deal sampler: samples deals
- Card play → PIMC engine: uses search
- Card play → ACE defender: uses defender
- Bidding engine → BBA bidder: uses BBA
- Bridge player → Table manager client: connects to table
- Table manager client → Game state: plays boards
- Browser → Hand visualizer: reviews hands
- Game API → Game state: exposes operations