# daffidwilde/matching architecture

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

- Interactive diagram: https://gitdiagram.com/daffidwilde/matching
- Repository: https://github.com/daffidwilde/matching

## Overview

`matching` is a Python library for constructing and solving four preference-based allocation games: stable marriage, hospital-resident, student allocation, and stable roommates. A user creates a game from player instances or preference dictionaries, calls its solver, and receives a dictionary-like matching; game classes also expose validity and stability checks. The graph separates game APIs, algorithm implementations, player models, and shared framework code. Edges follow the shown calls or documented workflow; some unsampled game internals are represented only where the README or source index supports the connection.

Main entry points: [`src/matching/players/hospital.py`](https://github.com/daffidwilde/matching/blob/main/src/matching/players/hospital.py) (Hospital), [`src/matching/algorithms/util.py`](https://github.com/daffidwilde/matching/blob/main/src/matching/algorithms/util.py) (Pair operations), [`src/matching/games/stable_marriage.py`](https://github.com/daffidwilde/matching/blob/main/src/matching/games/stable_marriage.py) (Stable marriage), [`src/matching/games/hospital_resident.py`](https://github.com/daffidwilde/matching/blob/main/src/matching/games/hospital_resident.py) (Hospital resident)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_games["Game APIs"]
  node_sm_game["Stable marriage<br/>[stable_marriage.py]"]
  node_hr_game["Hospital resident"]
  node_sa_game["Student allocation"]
  node_sr_game["Stable roommates"]
end

subgraph group_algorithms["Solving algorithms"]
  node_sm_algo["Marriage solver<br/>[stable_marriage.py]"]
  node_hr_algo["Hospital solver"]
  node_sa_algo["Allocation solver"]
  node_sr_algo["Roommates solver"]
  node_algorithm_util["Pair operations<br/>[util.py]"]
end

subgraph group_models["Player models"]
  node_player["Player<br/>[player.py]"]
  node_hospital["Hospital<br/>[hospital.py]"]
  node_project["Project<br/>[project.py]"]
  node_supervisor["Supervisor<br/>[supervisor.py]"]
end

subgraph group_framework["Shared framework"]
  node_base_player["Base player<br/>[base.py]"]
  node_game_base["Game validation<br/>[base.py]"]
  node_exceptions["Solver warnings<br/>[exceptions.py]"]
  node_matching_result["Matching results<br/>[matchings.py]"]
end

node_user(("Library user"))

node_user -->|"creates and solves"| node_sm_game
node_user -->|"creates and solves"| node_hr_game
node_user -->|"creates and solves"| node_sa_game
node_user -->|"creates and solves"| node_sr_game
node_sm_game -->|"calls solver"| node_sm_algo
node_hr_game -->|"calls solver"| node_hr_algo
node_sa_game -->|"calls solver"| node_sa_algo
node_sr_game -->|"calls solver"| node_sr_algo
node_sm_algo -->|"imports helpers"| node_algorithm_util
node_hr_algo -->|"uses pair helpers"| node_algorithm_util
node_sa_algo -->|"uses pair helpers"| node_algorithm_util
node_sr_algo -->|"uses pair helper"| node_algorithm_util
node_hr_algo -->|"queries capacities"| node_hospital
node_sa_algo -->|"queries capacity"| node_hospital
node_sr_algo -->|"proposes to players"| node_player
node_hospital -->|"inherits behavior"| node_base_player
node_project -->|"inherits capacity model"| node_hospital
node_supervisor -->|"inherits capacity model"| node_hospital
node_sm_game -->|"returns matching"| node_matching_result
node_hr_game -->|"wraps result"| node_matching_result
node_sa_game -->|"wraps result"| node_matching_result
node_game_base -->|"raises warnings"| node_exceptions

click node_sm_game "https://github.com/daffidwilde/matching/blob/main/src/matching/games/stable_marriage.py"
click node_hr_game "https://github.com/daffidwilde/matching/blob/main/src/matching/games/hospital_resident.py"
click node_sa_game "https://github.com/daffidwilde/matching/blob/main/src/matching/games/student_allocation.py"
click node_sr_game "https://github.com/daffidwilde/matching/blob/main/src/matching/games/stable_roommates.py"
click node_sm_algo "https://github.com/daffidwilde/matching/blob/main/src/matching/algorithms/stable_marriage.py"
click node_hr_algo "https://github.com/daffidwilde/matching/blob/main/src/matching/algorithms/hospital_resident.py"
click node_sa_algo "https://github.com/daffidwilde/matching/blob/main/src/matching/algorithms/student_allocation.py"
click node_sr_algo "https://github.com/daffidwilde/matching/blob/main/src/matching/algorithms/stable_roommates.py"
click node_algorithm_util "https://github.com/daffidwilde/matching/blob/main/src/matching/algorithms/util.py"
click node_base_player "https://github.com/daffidwilde/matching/blob/main/src/matching/base.py"
click node_game_base "https://github.com/daffidwilde/matching/blob/main/src/matching/base.py"
click node_exceptions "https://github.com/daffidwilde/matching/blob/main/src/matching/exceptions.py"
click node_matching_result "https://github.com/daffidwilde/matching/blob/main/src/matching/matchings.py"
click node_player "https://github.com/daffidwilde/matching/blob/main/src/matching/players/player.py"
click node_hospital "https://github.com/daffidwilde/matching/blob/main/src/matching/players/hospital.py"
click node_project "https://github.com/daffidwilde/matching/blob/main/src/matching/players/project.py"
click node_supervisor "https://github.com/daffidwilde/matching/blob/main/src/matching/players/supervisor.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_sm_game,node_hr_game,node_sa_game,node_sr_game,node_user toneBlue
class node_sm_algo,node_hr_algo,node_sa_algo,node_sr_algo,node_algorithm_util toneAmber
class node_player,node_hospital,node_project,node_supervisor toneMint
class node_base_player,node_game_base,node_exceptions,node_matching_result toneRose
```

## Components

### Game APIs

- [Stable marriage](https://github.com/daffidwilde/matching/blob/main/src/matching/games/stable_marriage.py): `src/matching/games/stable_marriage.py`
- [Hospital resident](https://github.com/daffidwilde/matching/blob/main/src/matching/games/hospital_resident.py): `src/matching/games/hospital_resident.py`
- [Student allocation](https://github.com/daffidwilde/matching/blob/main/src/matching/games/student_allocation.py): `src/matching/games/student_allocation.py`
- [Stable roommates](https://github.com/daffidwilde/matching/blob/main/src/matching/games/stable_roommates.py): `src/matching/games/stable_roommates.py`

### Solving algorithms

- [Marriage solver](https://github.com/daffidwilde/matching/blob/main/src/matching/algorithms/stable_marriage.py): `src/matching/algorithms/stable_marriage.py`
- [Hospital solver](https://github.com/daffidwilde/matching/blob/main/src/matching/algorithms/hospital_resident.py): `src/matching/algorithms/hospital_resident.py`
- [Allocation solver](https://github.com/daffidwilde/matching/blob/main/src/matching/algorithms/student_allocation.py): `src/matching/algorithms/student_allocation.py`
- [Roommates solver](https://github.com/daffidwilde/matching/blob/main/src/matching/algorithms/stable_roommates.py): `src/matching/algorithms/stable_roommates.py`
- [Pair operations](https://github.com/daffidwilde/matching/blob/main/src/matching/algorithms/util.py): `src/matching/algorithms/util.py`

### Player models

- [Player](https://github.com/daffidwilde/matching/blob/main/src/matching/players/player.py): `src/matching/players/player.py`
- [Hospital](https://github.com/daffidwilde/matching/blob/main/src/matching/players/hospital.py): `src/matching/players/hospital.py`
- [Project](https://github.com/daffidwilde/matching/blob/main/src/matching/players/project.py): `src/matching/players/project.py`
- [Supervisor](https://github.com/daffidwilde/matching/blob/main/src/matching/players/supervisor.py): `src/matching/players/supervisor.py`

### Shared framework

- [Base player](https://github.com/daffidwilde/matching/blob/main/src/matching/base.py): `src/matching/base.py`
- [Game validation](https://github.com/daffidwilde/matching/blob/main/src/matching/base.py): `src/matching/base.py`
- [Solver warnings](https://github.com/daffidwilde/matching/blob/main/src/matching/exceptions.py): `src/matching/exceptions.py`
- [Matching results](https://github.com/daffidwilde/matching/blob/main/src/matching/matchings.py): `src/matching/matchings.py`

### Other components

- **Library user**

## Connections

- Library user → Stable marriage: creates and solves (evidence: `README.md`)
- Library user → Hospital resident: creates and solves (evidence: `README.md`)
- Library user → Student allocation: creates and solves (evidence: `README.md`)
- Library user → Stable roommates: creates and solves (evidence: `README.md`)
- Stable marriage → Marriage solver: calls solver (evidence: `src/matching/games/stable_marriage.py`)
- Hospital resident → Hospital solver: calls solver (evidence: `src/matching/games/hospital_resident.py`)
- Student allocation → Allocation solver: calls solver (evidence: `src/matching/games/student_allocation.py`)
- Stable roommates → Roommates solver: calls solver (evidence: `src/matching/games/stable_roommates.py`)
- Marriage solver → Pair operations: imports helpers (evidence: `src/matching/algorithms/stable_marriage.py`)
- Hospital solver → Pair operations: uses pair helpers (evidence: `src/matching/algorithms/hospital_resident.py`)
- Allocation solver → Pair operations: uses pair helpers (evidence: `src/matching/algorithms/student_allocation.py`)
- Roommates solver → Pair operations: uses pair helper (evidence: `src/matching/algorithms/stable_roommates.py`)
- Hospital solver → Hospital: queries capacities (evidence: `src/matching/algorithms/hospital_resident.py`)
- Allocation solver → Hospital: queries capacity (evidence: `src/matching/algorithms/student_allocation.py`)
- Roommates solver → Player: proposes to players (evidence: `src/matching/algorithms/stable_roommates.py`)
- Hospital → Base player: inherits behavior (evidence: `src/matching/players/hospital.py`)
- Project → Hospital: inherits capacity model (evidence: `src/matching/players/hospital.py`)
- Supervisor → Hospital: inherits capacity model (evidence: `src/matching/players/hospital.py`)
- Stable marriage → Matching results: returns matching (evidence: `README.md`)
- Hospital resident → Matching results: wraps result (evidence: `src/matching/games/hospital_resident.py`)
- Student allocation → Matching results: wraps result (evidence: `src/matching/games/student_allocation.py`)
- Game validation → Solver warnings: raises warnings (evidence: `src/matching/base.py`)
