# alberthamoui/candidate_allocation architecture

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

- Interactive diagram: https://gitdiagram.com/alberthamoui/candidate_allocation
- Repository: https://github.com/alberthamoui/candidate_allocation

## Overview

Candidate Allocation is a web application for turning a three-sheet Excel workbook into interview-table assignments. Users upload and map candidate, evaluator, and restriction data, review candidates, set capacity and optional course/semester criteria, then run allocation and inspect or export the result. The documented optimizer combines simulated annealing with exact evaluator assignment and an optimality bound. Backend request wiring and several frontend API calls were not excerpted, so those relationships are shown only where README or excerpts support them.

Main entry points: [`frontend/src/pages/Parametros.tsx`](https://github.com/alberthamoui/candidate_allocation/blob/main/frontend/src/pages/Parametros.tsx) (Allocation parameters), [`handlers.go`](https://github.com/alberthamoui/candidate_allocation/blob/main/handlers.go) (API handlers), [`alocate.go`](https://github.com/alberthamoui/candidate_allocation/blob/main/alocate.go) (Assignment search), [`frontend/src/pages/Resultado.tsx`](https://github.com/alberthamoui/candidate_allocation/blob/main/frontend/src/pages/Resultado.tsx) (Result screen)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Workbook intake"]
  node_http["HTTP server<br/>[main.go]"]
  node_handlers["API handlers<br/>[handlers.go]"]
  node_excel["Workbook processing<br/>[processa.go]"]
  node_mapping["Column mapping<br/>[mapping.go]"]
  node_suggest["Mapping suggestions"]
end

subgraph group_setup["Allocation setup"]
  node_capacity["Capacity preview<br/>[capacidade.go]"]
  node_storage[("Session data<br/>[auxfunctions.go]")]
end

subgraph group_engine["Allocation engine"]
  node_criteria["Additional criteria<br/>[criterios.go]"]
  node_allocation["Assignment search<br/>[alocate.go]"]
  node_models["Allocation data model<br/>[models.go]"]
end

subgraph group_results["Results and export"]
  node_result_panel["Search and quality view"]
  node_result_service["Result and quality<br/>[resultado.go]"]
  node_export["Excel export<br/>[export.go]"]
end

subgraph group_ui["Web interface"]
  node_home["Upload settings<br/>[Home.tsx]"]
  node_upload_api["Upload API<br/>[api.ts]"]
  node_candidate_review["Candidate review<br/>[VerifyUsers.tsx]"]
  node_review_card["Editable user cards<br/>[UserCard.tsx]"]
  node_editable_cell["Editable fields<br/>[EditableCell.tsx]"]
  node_evaluator_upload["Evaluator mapping"]
  node_restriction_upload["Restriction mapping"]
  node_parameters["Allocation parameters<br/>[Parametros.tsx]"]
  node_criteria_editor["Criteria editor"]
  node_result_page["Result screen<br/>[Resultado.tsx]"]
  node_result_api["Result API client<br/>[api.ts]"]
end

node_user(("Operator"))
node_excel_user["Workbook"]

node_user -->|"uploads workbook"| node_home
node_home -->|"submits file"| node_upload_api
node_upload_api -.->|"requests upload"| node_handlers
node_handlers -.->|"processes workbook"| node_excel
node_excel -.->|"builds mappings"| node_mapping
node_mapping -.->|"suggests columns"| node_suggest
node_user -->|"reviews candidates"| node_candidate_review
node_candidate_review -->|"renders cards"| node_review_card
node_review_card -->|"renders fields"| node_editable_cell
node_user -->|"maps evaluators"| node_evaluator_upload
node_user -->|"maps restrictions"| node_restriction_upload
node_user -->|"sets parameters"| node_parameters
node_parameters -->|"edits criteria"| node_criteria_editor
node_parameters -.->|"requests preview"| node_capacity
node_parameters -->|"starts allocation"| node_allocation
node_allocation -->|"scores criteria"| node_criteria
node_allocation -.->|"uses allocation data"| node_models
node_handlers -.->|"persists session data"| node_storage
node_user -->|"views assignments"| node_result_page
node_result_page -.->|"loads result"| node_result_api
node_result_page -->|"renders results"| node_result_panel
node_result_service -.->|"provides export data"| node_export
node_user -->|"exports workbook"| node_export
node_export -->|"writes workbook"| node_excel_user
node_user -->|"searches and filters"| node_result_panel

click node_home "https://github.com/alberthamoui/candidate_allocation/blob/main/frontend/src/pages/Home.tsx"
click node_upload_api "https://github.com/alberthamoui/candidate_allocation/blob/main/frontend/src/api.ts"
click node_http "https://github.com/alberthamoui/candidate_allocation/blob/main/main.go"
click node_handlers "https://github.com/alberthamoui/candidate_allocation/blob/main/handlers.go"
click node_excel "https://github.com/alberthamoui/candidate_allocation/blob/main/processa.go"
click node_mapping "https://github.com/alberthamoui/candidate_allocation/blob/main/mapping.go"
click node_suggest "https://github.com/alberthamoui/candidate_allocation/blob/main/sugestao_mapping.go"
click node_candidate_review "https://github.com/alberthamoui/candidate_allocation/blob/main/frontend/src/pages/VerifyUsers.tsx"
click node_review_card "https://github.com/alberthamoui/candidate_allocation/blob/main/frontend/src/components/UserCard.tsx"
click node_editable_cell "https://github.com/alberthamoui/candidate_allocation/blob/main/frontend/src/components/EditableCell.tsx"
click node_evaluator_upload "https://github.com/alberthamoui/candidate_allocation/blob/main/frontend/src/pages/UploadAvaliador.tsx"
click node_restriction_upload "https://github.com/alberthamoui/candidate_allocation/blob/main/frontend/src/pages/UploadRestricao.tsx"
click node_parameters "https://github.com/alberthamoui/candidate_allocation/blob/main/frontend/src/pages/Parametros.tsx"
click node_criteria_editor "https://github.com/alberthamoui/candidate_allocation/blob/main/frontend/src/components/EditorCriterios.tsx"
click node_capacity "https://github.com/alberthamoui/candidate_allocation/blob/main/capacidade.go"
click node_criteria "https://github.com/alberthamoui/candidate_allocation/blob/main/criterios.go"
click node_allocation "https://github.com/alberthamoui/candidate_allocation/blob/main/alocate.go"
click node_models "https://github.com/alberthamoui/candidate_allocation/blob/main/models.go"
click node_storage "https://github.com/alberthamoui/candidate_allocation/blob/main/db/auxfunctions.go"
click node_result_page "https://github.com/alberthamoui/candidate_allocation/blob/main/frontend/src/pages/Resultado.tsx"
click node_result_panel "https://github.com/alberthamoui/candidate_allocation/blob/main/frontend/src/components/PainelResultado.tsx"
click node_result_api "https://github.com/alberthamoui/candidate_allocation/blob/main/frontend/src/api.ts"
click node_result_service "https://github.com/alberthamoui/candidate_allocation/blob/main/resultado.go"
click node_export "https://github.com/alberthamoui/candidate_allocation/blob/main/export.go"

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_http,node_handlers,node_excel,node_mapping,node_suggest toneBlue
class node_capacity,node_storage toneAmber
class node_criteria,node_allocation,node_models toneMint
class node_result_panel,node_result_service,node_export toneRose
class node_home,node_upload_api,node_candidate_review,node_review_card,node_editable_cell,node_evaluator_upload,node_restriction_upload,node_parameters,node_criteria_editor,node_result_page,node_result_api,node_user,node_excel_user toneIndigo
```

## Components

### Workbook intake

- [HTTP server](https://github.com/alberthamoui/candidate_allocation/blob/main/main.go): `main.go`
- [API handlers](https://github.com/alberthamoui/candidate_allocation/blob/main/handlers.go): `handlers.go`
- [Workbook processing](https://github.com/alberthamoui/candidate_allocation/blob/main/processa.go): `processa.go`
- [Column mapping](https://github.com/alberthamoui/candidate_allocation/blob/main/mapping.go): `mapping.go`
- [Mapping suggestions](https://github.com/alberthamoui/candidate_allocation/blob/main/sugestao_mapping.go): `sugestao_mapping.go`

### Allocation setup

- [Capacity preview](https://github.com/alberthamoui/candidate_allocation/blob/main/capacidade.go): `capacidade.go`
- [Session data](https://github.com/alberthamoui/candidate_allocation/blob/main/db/auxfunctions.go): `db/auxfunctions.go`

### Allocation engine

- [Additional criteria](https://github.com/alberthamoui/candidate_allocation/blob/main/criterios.go): `criterios.go`
- [Assignment search](https://github.com/alberthamoui/candidate_allocation/blob/main/alocate.go): `alocate.go`
- [Allocation data model](https://github.com/alberthamoui/candidate_allocation/blob/main/models.go): `models.go`

### Results and export

- [Search and quality view](https://github.com/alberthamoui/candidate_allocation/blob/main/frontend/src/components/PainelResultado.tsx): `frontend/src/components/PainelResultado.tsx`
- [Result and quality](https://github.com/alberthamoui/candidate_allocation/blob/main/resultado.go): `resultado.go`
- [Excel export](https://github.com/alberthamoui/candidate_allocation/blob/main/export.go): `export.go`

### Web interface

- [Upload settings](https://github.com/alberthamoui/candidate_allocation/blob/main/frontend/src/pages/Home.tsx): `frontend/src/pages/Home.tsx`
- [Upload API](https://github.com/alberthamoui/candidate_allocation/blob/main/frontend/src/api.ts): `frontend/src/api.ts`
- [Candidate review](https://github.com/alberthamoui/candidate_allocation/blob/main/frontend/src/pages/VerifyUsers.tsx): `frontend/src/pages/VerifyUsers.tsx`
- [Editable user cards](https://github.com/alberthamoui/candidate_allocation/blob/main/frontend/src/components/UserCard.tsx): `frontend/src/components/UserCard.tsx`
- [Editable fields](https://github.com/alberthamoui/candidate_allocation/blob/main/frontend/src/components/EditableCell.tsx): `frontend/src/components/EditableCell.tsx`
- [Evaluator mapping](https://github.com/alberthamoui/candidate_allocation/blob/main/frontend/src/pages/UploadAvaliador.tsx): `frontend/src/pages/UploadAvaliador.tsx`
- [Restriction mapping](https://github.com/alberthamoui/candidate_allocation/blob/main/frontend/src/pages/UploadRestricao.tsx): `frontend/src/pages/UploadRestricao.tsx`
- [Allocation parameters](https://github.com/alberthamoui/candidate_allocation/blob/main/frontend/src/pages/Parametros.tsx): `frontend/src/pages/Parametros.tsx`
- [Criteria editor](https://github.com/alberthamoui/candidate_allocation/blob/main/frontend/src/components/EditorCriterios.tsx): `frontend/src/components/EditorCriterios.tsx`
- [Result screen](https://github.com/alberthamoui/candidate_allocation/blob/main/frontend/src/pages/Resultado.tsx): `frontend/src/pages/Resultado.tsx`
- [Result API client](https://github.com/alberthamoui/candidate_allocation/blob/main/frontend/src/api.ts): `frontend/src/api.ts`

### Other components

- **Operator**
- **Workbook**

## Connections

- Operator → Upload settings: uploads workbook (evidence: `README.md`)
- Upload settings → Upload API: submits file (evidence: `frontend/src/pages/Home.tsx`)
- Upload API → API handlers: requests upload
- API handlers → Workbook processing: processes workbook
- Workbook processing → Column mapping: builds mappings
- Column mapping → Mapping suggestions: suggests columns
- Operator → Candidate review: reviews candidates (evidence: `README.md`)
- Candidate review → Editable user cards: renders cards (evidence: `frontend/src/pages/VerifyUsers.tsx`)
- Editable user cards → Editable fields: renders fields (evidence: `frontend/src/components/UserCard.tsx`)
- Operator → Evaluator mapping: maps evaluators (evidence: `README.md`)
- Operator → Restriction mapping: maps restrictions (evidence: `README.md`)
- Operator → Allocation parameters: sets parameters (evidence: `README.md`)
- Allocation parameters → Criteria editor: edits criteria (evidence: `frontend/src/pages/Parametros.tsx`)
- Allocation parameters → Capacity preview: requests preview
- Allocation parameters → Assignment search: starts allocation (evidence: `README.md`)
- Assignment search → Additional criteria: scores criteria (evidence: `README.md`)
- Assignment search → Allocation data model: uses allocation data
- API handlers → Session data: persists session data
- Operator → Result screen: views assignments (evidence: `README.md`)
- Result screen → Result API client: loads result (evidence: `frontend/src/pages/Resultado.tsx`)
- Result screen → Search and quality view: renders results (evidence: `frontend/src/pages/Resultado.tsx`)
- Result and quality → Excel export: provides export data
- Operator → Excel export: exports workbook (evidence: `README.md`)
- Excel export → Workbook: writes workbook (evidence: `README.md`)
- Operator → Search and quality view: searches and filters (evidence: `README.md`)
