# kartevsumit/hostel-allocation-optimizer architecture

> Architecture diagram of the GitHub repository kartevsumit/hostel-allocation-optimizer, 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/kartevsumit/hostel-allocation-optimizer
- Repository: https://github.com/kartevsumit/hostel-allocation-optimizer

## Overview

This C++ hostel-allocation engine loads student groups, preferences, room inventory and roommate data, preprocesses constraints, then runs greedy placement, simulated annealing and MCMF before saving and reporting an allocation. A separate FCFS executable provides the documented comparison baseline. The graph reflects the explicitly shown orchestration and documented algorithm roles; internal calls in unsampled portions of some optimizer sources are not inferred.

Main entry points: [`src/main.cpp`](https://github.com/kartevsumit/hostel-allocation-optimizer/blob/main/src/main.cpp) (Optimizer entry), [`src/fcfs.cpp`](https://github.com/kartevsumit/hostel-allocation-optimizer/blob/main/src/fcfs.cpp) (FCFS baseline), [`src/db/db_loader.cpp`](https://github.com/kartevsumit/hostel-allocation-optimizer/blob/main/src/db/db_loader.cpp) (Database loader), [`src/optimizer/greedy.cpp`](https://github.com/kartevsumit/hostel-allocation-optimizer/blob/main/src/optimizer/greedy.cpp) (Greedy placement)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Run orchestration"]
  node_main["Optimizer entry<br/>[main.cpp]"]
  node_fcfs["FCFS baseline<br/>[fcfs.cpp]"]
end

subgraph group_optimization["Allocation optimization"]
  node_greedy["Greedy placement<br/>[greedy.cpp]"]
  node_annealer["Simulated annealing<br/>[annealer.cpp]"]
  node_mcmf["MCMF optimizer<br/>[mcmf.cpp]"]
end

subgraph group_domain["Allocation domain"]
  node_preprocess["Input preprocessing<br/>[preprocessor.cpp]"]
  node_cost["Cost model<br/>[cost.cpp]"]
  node_state["Allocation state<br/>[state.h]"]
  node_models["Allocation models<br/>[models.h]"]
  node_types["Allocation types<br/>[types.h]"]
  node_logger["Logger<br/>[logger.h]"]
end

subgraph group_io["Persistence and output"]
  node_dbloader["Database loader<br/>[db_loader.cpp]"]
  node_reporter["Allocation reporter<br/>[reporter.cpp]"]
end

node_operator(("Operator"))
node_postgres[("PostgreSQL")]
node_results["Allocation reports"]

node_operator -->|"runs optimizer"| node_main
node_main -->|"loads data"| node_dbloader
node_dbloader -.->|"reads and writes"| node_postgres
node_main -->|"resolves constraints"| node_preprocess
node_main -->|"starts phase one"| node_greedy
node_main -->|"starts phase two"| node_annealer
node_main -->|"starts phase three"| node_mcmf
node_main -->|"saves allocation"| node_dbloader
node_main -->|"requests reports"| node_reporter
node_reporter -->|"exports CSV"| node_results
node_fcfs -->|"loads data"| node_dbloader
node_fcfs -->|"resolves constraints"| node_preprocess
node_fcfs -->|"places groups"| node_greedy
node_fcfs -->|"requests reports"| node_reporter
node_greedy -->|"feeds allocation"| node_annealer
node_annealer -->|"refines allocation"| node_mcmf

click node_main "https://github.com/kartevsumit/hostel-allocation-optimizer/blob/main/src/main.cpp"
click node_fcfs "https://github.com/kartevsumit/hostel-allocation-optimizer/blob/main/src/fcfs.cpp"
click node_preprocess "https://github.com/kartevsumit/hostel-allocation-optimizer/blob/main/src/core/preprocessor.cpp"
click node_greedy "https://github.com/kartevsumit/hostel-allocation-optimizer/blob/main/src/optimizer/greedy.cpp"
click node_annealer "https://github.com/kartevsumit/hostel-allocation-optimizer/blob/main/src/optimizer/annealer.cpp"
click node_mcmf "https://github.com/kartevsumit/hostel-allocation-optimizer/blob/main/src/optimizer/mcmf.cpp"
click node_cost "https://github.com/kartevsumit/hostel-allocation-optimizer/blob/main/src/core/cost.cpp"
click node_state "https://github.com/kartevsumit/hostel-allocation-optimizer/blob/main/include/core/state.h"
click node_models "https://github.com/kartevsumit/hostel-allocation-optimizer/blob/main/include/core/models.h"
click node_types "https://github.com/kartevsumit/hostel-allocation-optimizer/blob/main/include/core/types.h"
click node_logger "https://github.com/kartevsumit/hostel-allocation-optimizer/blob/main/include/utils/logger.h"
click node_dbloader "https://github.com/kartevsumit/hostel-allocation-optimizer/blob/main/src/db/db_loader.cpp"
click node_reporter "https://github.com/kartevsumit/hostel-allocation-optimizer/blob/main/src/io/reporter.cpp"

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_main,node_fcfs toneBlue
class node_greedy,node_annealer,node_mcmf,node_postgres toneAmber
class node_preprocess,node_cost,node_state,node_models,node_types,node_logger toneMint
class node_dbloader,node_reporter toneRose
class node_operator,node_results toneIndigo
```

## Components

### Run orchestration

- [Optimizer entry](https://github.com/kartevsumit/hostel-allocation-optimizer/blob/main/src/main.cpp): `src/main.cpp`
- [FCFS baseline](https://github.com/kartevsumit/hostel-allocation-optimizer/blob/main/src/fcfs.cpp): `src/fcfs.cpp`

### Allocation optimization

- [Greedy placement](https://github.com/kartevsumit/hostel-allocation-optimizer/blob/main/src/optimizer/greedy.cpp): `src/optimizer/greedy.cpp`
- [Simulated annealing](https://github.com/kartevsumit/hostel-allocation-optimizer/blob/main/src/optimizer/annealer.cpp): `src/optimizer/annealer.cpp`
- [MCMF optimizer](https://github.com/kartevsumit/hostel-allocation-optimizer/blob/main/src/optimizer/mcmf.cpp): `src/optimizer/mcmf.cpp`

### Allocation domain

- [Input preprocessing](https://github.com/kartevsumit/hostel-allocation-optimizer/blob/main/src/core/preprocessor.cpp): `src/core/preprocessor.cpp`
- [Cost model](https://github.com/kartevsumit/hostel-allocation-optimizer/blob/main/src/core/cost.cpp): `src/core/cost.cpp`
- [Allocation state](https://github.com/kartevsumit/hostel-allocation-optimizer/blob/main/include/core/state.h): `include/core/state.h`
- [Allocation models](https://github.com/kartevsumit/hostel-allocation-optimizer/blob/main/include/core/models.h): `include/core/models.h`
- [Allocation types](https://github.com/kartevsumit/hostel-allocation-optimizer/blob/main/include/core/types.h): `include/core/types.h`
- [Logger](https://github.com/kartevsumit/hostel-allocation-optimizer/blob/main/include/utils/logger.h): `include/utils/logger.h`

### Persistence and output

- [Database loader](https://github.com/kartevsumit/hostel-allocation-optimizer/blob/main/src/db/db_loader.cpp): `src/db/db_loader.cpp`
- [Allocation reporter](https://github.com/kartevsumit/hostel-allocation-optimizer/blob/main/src/io/reporter.cpp): `src/io/reporter.cpp`

### Other components

- **Operator**
- **PostgreSQL**
- **Allocation reports**

## Connections

- Operator → Optimizer entry: runs optimizer (evidence: `src/main.cpp`)
- Optimizer entry → Database loader: loads data (evidence: `src/main.cpp`)
- Database loader → PostgreSQL: reads and writes (evidence: `README.md`)
- Optimizer entry → Input preprocessing: resolves constraints (evidence: `src/main.cpp`)
- Optimizer entry → Greedy placement: starts phase one (evidence: `src/main.cpp`)
- Optimizer entry → Simulated annealing: starts phase two (evidence: `src/main.cpp`)
- Optimizer entry → MCMF optimizer: starts phase three (evidence: `src/main.cpp`)
- Optimizer entry → Database loader: saves allocation (evidence: `src/main.cpp`)
- Optimizer entry → Allocation reporter: requests reports (evidence: `src/main.cpp`)
- Allocation reporter → Allocation reports: exports CSV
- FCFS baseline → Database loader: loads data (evidence: `src/fcfs.cpp`)
- FCFS baseline → Input preprocessing: resolves constraints (evidence: `src/fcfs.cpp`)
- FCFS baseline → Greedy placement: places groups (evidence: `src/fcfs.cpp`)
- FCFS baseline → Allocation reporter: requests reports (evidence: `src/fcfs.cpp`)
- Greedy placement → Simulated annealing: feeds allocation (evidence: `README.md`)
- Simulated annealing → MCMF optimizer: refines allocation (evidence: `README.md`)