# carlos-estupinan/villaia architecture

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

- Interactive diagram: https://gitdiagram.com/carlos-estupinan/villaia
- Repository: https://github.com/carlos-estupinan/villaia

## Overview

Villa de Leyva Recommender is a tourism recommendation web application. A visitor enters travel preferences in the React interface; the FastAPI service uses the catalog and a loaded model to produce ranked, diversified recommendations with brief reasons, which the interface presents as place cards. The backend has distinct profile normalization, candidate scoring, business-rule reranking, and explanation stages. The frontend’s request call is not visible in the excerpt, so that connection is marked unverified; other links reflect shown calls or documented module references.

Main entry points: [`aplicacion/Backend/app/main.py`](https://github.com/carlos-estupinan/villaia/blob/main/aplicacion/Backend/app/main.py) (FastAPI service), [`aplicacion/Backend/app/core/topn_recommender.py`](https://github.com/carlos-estupinan/villaia/blob/main/aplicacion/Backend/app/core/topn_recommender.py) (Top-N recommender), [`aplicacion/Backend/app/core/model_loader.py`](https://github.com/carlos-estupinan/villaia/blob/main/aplicacion/Backend/app/core/model_loader.py) (Model loading and scoring), [`aplicacion/Backend/app/core/recommender.py`](https://github.com/carlos-estupinan/villaia/blob/main/aplicacion/Backend/app/core/recommender.py) (Pair recommender)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Visitor experience"]
  node_app_entry["React entry<br/>[main.jsx]"]
  node_app_shell["App shell<br/>[App.jsx]"]
  node_survey_results["Survey and results<br/>[VillaLeyvaApp.jsx]"]
end

subgraph group_service["Recommendation API"]
  node_api["FastAPI service<br/>[main.py]"]
  node_survey_schema["Survey schemas<br/>[schemas.py]"]
end

subgraph group_ranking["Recommendation engine"]
  node_topn["Top-N recommender"]
  node_feature_map["Feature mapping<br/>[feature_map.py]"]
  node_model_loader["Model loading and scoring<br/>[model_loader.py]"]
  node_business_controls["Business reranking"]
  node_legacy_recommender["Pair recommender<br/>[recommender.py]"]
end

subgraph group_inputs["Recommendation inputs"]
  node_catalog[("Place catalog")]
  node_model_artifacts["Model files"]
end

node_visitor(("Traveler"))

node_visitor -->|"uses"| node_app_entry
node_app_entry -->|"renders"| node_app_shell
node_app_shell -->|"renders"| node_survey_results
node_survey_results -.->|"requests recommendations"| node_api
node_api -->|"reads"| node_catalog
node_api -->|"loads model"| node_model_artifacts
node_api -->|"constructs"| node_model_loader
node_api -->|"constructs and calls"| node_topn
node_topn -->|"uses features"| node_feature_map
node_topn -->|"uses model"| node_model_loader
node_topn -->|"applies penalties"| node_business_controls
node_legacy_recommender -->|"builds features"| node_feature_map
node_legacy_recommender -.->|"predicts scores"| node_model_loader

click node_app_entry "https://github.com/carlos-estupinan/villaia/blob/main/aplicacion/Frontend/vdl-reco/src/main.jsx"
click node_app_shell "https://github.com/carlos-estupinan/villaia/blob/main/aplicacion/Frontend/vdl-reco/src/App.jsx"
click node_survey_results "https://github.com/carlos-estupinan/villaia/blob/main/aplicacion/Frontend/vdl-reco/src/VillaLeyvaApp.jsx"
click node_api "https://github.com/carlos-estupinan/villaia/blob/main/aplicacion/Backend/app/main.py"
click node_catalog "https://github.com/carlos-estupinan/villaia/blob/main/aplicacion/Backend/app/data/catalogo_vdl_lugares_reformulado_v2.csv"
click node_model_artifacts "https://github.com/carlos-estupinan/villaia/tree/main/aplicacion/Backend/models"
click node_topn "https://github.com/carlos-estupinan/villaia/blob/main/aplicacion/Backend/app/core/topn_recommender.py"
click node_feature_map "https://github.com/carlos-estupinan/villaia/blob/main/aplicacion/Backend/app/core/feature_map.py"
click node_model_loader "https://github.com/carlos-estupinan/villaia/blob/main/aplicacion/Backend/app/core/model_loader.py"
click node_business_controls "https://github.com/carlos-estupinan/villaia/blob/main/aplicacion/Backend/app/core/business_controls.py"
click node_legacy_recommender "https://github.com/carlos-estupinan/villaia/blob/main/aplicacion/Backend/app/core/recommender.py"
click node_survey_schema "https://github.com/carlos-estupinan/villaia/blob/main/aplicacion/Backend/app/schemas.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_app_entry,node_app_shell,node_survey_results toneBlue
class node_api,node_survey_schema toneAmber
class node_topn,node_feature_map,node_model_loader,node_business_controls,node_legacy_recommender toneMint
class node_catalog,node_model_artifacts toneRose
class node_visitor toneIndigo
```

## Components

### Visitor experience

- [React entry](https://github.com/carlos-estupinan/villaia/blob/main/aplicacion/Frontend/vdl-reco/src/main.jsx): `aplicacion/Frontend/vdl-reco/src/main.jsx`
- [App shell](https://github.com/carlos-estupinan/villaia/blob/main/aplicacion/Frontend/vdl-reco/src/App.jsx): `aplicacion/Frontend/vdl-reco/src/App.jsx`
- [Survey and results](https://github.com/carlos-estupinan/villaia/blob/main/aplicacion/Frontend/vdl-reco/src/VillaLeyvaApp.jsx): `aplicacion/Frontend/vdl-reco/src/VillaLeyvaApp.jsx`

### Recommendation API

- [FastAPI service](https://github.com/carlos-estupinan/villaia/blob/main/aplicacion/Backend/app/main.py): `aplicacion/Backend/app/main.py`
- [Survey schemas](https://github.com/carlos-estupinan/villaia/blob/main/aplicacion/Backend/app/schemas.py): `aplicacion/Backend/app/schemas.py`

### Recommendation engine

- [Top-N recommender](https://github.com/carlos-estupinan/villaia/blob/main/aplicacion/Backend/app/core/topn_recommender.py): `aplicacion/Backend/app/core/topn_recommender.py`
- [Feature mapping](https://github.com/carlos-estupinan/villaia/blob/main/aplicacion/Backend/app/core/feature_map.py): `aplicacion/Backend/app/core/feature_map.py`
- [Model loading and scoring](https://github.com/carlos-estupinan/villaia/blob/main/aplicacion/Backend/app/core/model_loader.py): `aplicacion/Backend/app/core/model_loader.py`
- [Business reranking](https://github.com/carlos-estupinan/villaia/blob/main/aplicacion/Backend/app/core/business_controls.py): `aplicacion/Backend/app/core/business_controls.py`
- [Pair recommender](https://github.com/carlos-estupinan/villaia/blob/main/aplicacion/Backend/app/core/recommender.py): `aplicacion/Backend/app/core/recommender.py`

### Recommendation inputs

- [Place catalog](https://github.com/carlos-estupinan/villaia/blob/main/aplicacion/Backend/app/data/catalogo_vdl_lugares_reformulado_v2.csv): `aplicacion/Backend/app/data/catalogo_vdl_lugares_reformulado_v2.csv`
- [Model files](https://github.com/carlos-estupinan/villaia/tree/main/aplicacion/Backend/models): `aplicacion/Backend/models`

### Other components

- **Traveler**

## Connections

- Traveler → React entry: uses (evidence: `aplicacion/Frontend/vdl-reco/src/main.jsx`)
- React entry → App shell: renders (evidence: `aplicacion/Frontend/vdl-reco/src/main.jsx`)
- App shell → Survey and results: renders (evidence: `aplicacion/Frontend/vdl-reco/src/App.jsx`)
- Survey and results → FastAPI service: requests recommendations
- FastAPI service → Place catalog: reads (evidence: `aplicacion/Backend/app/main.py`)
- FastAPI service → Model files: loads model (evidence: `aplicacion/Backend/app/main.py`)
- FastAPI service → Model loading and scoring: constructs (evidence: `aplicacion/Backend/app/main.py`)
- FastAPI service → Top-N recommender: constructs and calls (evidence: `aplicacion/Backend/app/main.py`)
- Top-N recommender → Feature mapping: uses features (evidence: `aplicacion/Backend/app/core/topn_recommender.py`)
- Top-N recommender → Model loading and scoring: uses model (evidence: `aplicacion/Backend/app/core/topn_recommender.py`)
- Top-N recommender → Business reranking: applies penalties (evidence: `aplicacion/Backend/app/core/topn_recommender.py`)
- Pair recommender → Feature mapping: builds features (evidence: `aplicacion/Backend/app/core/recommender.py`)
- Pair recommender → Model loading and scoring: predicts scores
