# frozono9/ecityclic-recommender architecture

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

- Interactive diagram: https://gitdiagram.com/frozono9/ecityclic-recommender
- Repository: https://github.com/frozono9/ecityclic-recommender

## Overview

eCityclic is a Streamlit application that recommends administrative procedures from a user’s recent procedure history. A user selects an available procedure; the frontend maintains a short history and sends its sequence IDs to the backend. The backend loads the trained Transformer, pads the history, predicts likely next procedures, filters to active procedures, and resolves suggestions to titles for display. The README also describes notebook-based preprocessing and training. The referenced CSV is absent from the supplied tree, so it is shown as an external data dependency; notebook details are based on the README, not inspected source.

Main entry points: [`streamlit/backend.py`](https://github.com/frozono9/ecityclic-recommender/blob/main/streamlit/backend.py) (Recommendation entry), [`streamlit/frontend.py`](https://github.com/frozono9/ecityclic-recommender/blob/main/streamlit/frontend.py) (Selection and display), [`model/modelo_transformer_tramites.h5`](https://github.com/frozono9/ecityclic-recommender/blob/main/model/modelo_transformer_tramites.h5) (Trained Transformer), [`model/model.ipynb`](https://github.com/frozono9/ecityclic-recommender/blob/main/model/model.ipynb) (Preprocessing and training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Streamlit interface"]
  node_frontend["Selection and display<br/>[frontend.py]"]
  node_history["Recent history<br/>[frontend.py]"]
end

subgraph group_recommendation["Recommendation runtime"]
  node_backend["Recommendation entry<br/>[backend.py]"]
  node_loader["Model loader<br/>[backend.py]"]
  node_model["Trained Transformer"]
  node_prepare["Sequence padding<br/>[backend.py]"]
  node_predict["Transformer prediction<br/>[backend.py]"]
  node_rank["Active ranking<br/>[backend.py]"]
  node_titles["Title resolution<br/>[backend.py]"]
end

subgraph group_training["Model training"]
  node_notebook["Preprocessing and training<br/>[model.ipynb]"]
end

node_user(("Procedure user"))
node_catalog["Procedure catalog CSV"]

node_user -->|"selects procedure"| node_frontend
node_frontend -->|"reads titles and IDs"| node_catalog
node_frontend -->|"updates history"| node_history
node_frontend -->|"sends sequence IDs"| node_backend
node_backend -->|"loads model"| node_loader
node_loader -->|"loads weights"| node_model
node_backend -->|"pads sequence"| node_prepare
node_backend -->|"predicts sequence"| node_predict
node_predict -->|"runs inference"| node_model
node_backend -->|"filters and ranks"| node_rank
node_rank -->|"reads active procedures"| node_catalog
node_backend -->|"resolves suggestions"| node_titles
node_titles -->|"looks up titles"| node_catalog
node_backend -->|"returns suggestions"| node_frontend
node_frontend -->|"displays suggestions"| node_user
node_notebook -.->|"trains and saves"| node_model

click node_frontend "https://github.com/frozono9/ecityclic-recommender/blob/main/streamlit/frontend.py"
click node_history "https://github.com/frozono9/ecityclic-recommender/blob/main/streamlit/frontend.py"
click node_backend "https://github.com/frozono9/ecityclic-recommender/blob/main/streamlit/backend.py"
click node_loader "https://github.com/frozono9/ecityclic-recommender/blob/main/streamlit/backend.py"
click node_model "https://github.com/frozono9/ecityclic-recommender/blob/main/model/modelo_transformer_tramites.h5"
click node_prepare "https://github.com/frozono9/ecityclic-recommender/blob/main/streamlit/backend.py"
click node_predict "https://github.com/frozono9/ecityclic-recommender/blob/main/streamlit/backend.py"
click node_rank "https://github.com/frozono9/ecityclic-recommender/blob/main/streamlit/backend.py"
click node_titles "https://github.com/frozono9/ecityclic-recommender/blob/main/streamlit/backend.py"
click node_notebook "https://github.com/frozono9/ecityclic-recommender/blob/main/model/model.ipynb"

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_frontend,node_history,node_user toneBlue
class node_backend,node_loader,node_model,node_prepare,node_predict,node_rank,node_titles toneAmber
class node_notebook toneMint
class node_catalog toneIndigo
```

## Components

### Streamlit interface

- [Selection and display](https://github.com/frozono9/ecityclic-recommender/blob/main/streamlit/frontend.py): `streamlit/frontend.py`
- [Recent history](https://github.com/frozono9/ecityclic-recommender/blob/main/streamlit/frontend.py): `streamlit/frontend.py`

### Recommendation runtime

- [Recommendation entry](https://github.com/frozono9/ecityclic-recommender/blob/main/streamlit/backend.py): `streamlit/backend.py`
- [Model loader](https://github.com/frozono9/ecityclic-recommender/blob/main/streamlit/backend.py): `streamlit/backend.py`
- [Trained Transformer](https://github.com/frozono9/ecityclic-recommender/blob/main/model/modelo_transformer_tramites.h5): `model/modelo_transformer_tramites.h5`
- [Sequence padding](https://github.com/frozono9/ecityclic-recommender/blob/main/streamlit/backend.py): `streamlit/backend.py`
- [Transformer prediction](https://github.com/frozono9/ecityclic-recommender/blob/main/streamlit/backend.py): `streamlit/backend.py`
- [Active ranking](https://github.com/frozono9/ecityclic-recommender/blob/main/streamlit/backend.py): `streamlit/backend.py`
- [Title resolution](https://github.com/frozono9/ecityclic-recommender/blob/main/streamlit/backend.py): `streamlit/backend.py`

### Model training

- [Preprocessing and training](https://github.com/frozono9/ecityclic-recommender/blob/main/model/model.ipynb): `model/model.ipynb`

### Other components

- **Procedure user**
- **Procedure catalog CSV**

## Connections

- Procedure user → Selection and display: selects procedure
- Selection and display → Procedure catalog CSV: reads titles and IDs
- Selection and display → Recent history: updates history
- Selection and display → Recommendation entry: sends sequence IDs
- Recommendation entry → Model loader: loads model
- Model loader → Trained Transformer: loads weights
- Recommendation entry → Sequence padding: pads sequence
- Recommendation entry → Transformer prediction: predicts sequence
- Transformer prediction → Trained Transformer: runs inference
- Recommendation entry → Active ranking: filters and ranks
- Active ranking → Procedure catalog CSV: reads active procedures
- Recommendation entry → Title resolution: resolves suggestions
- Title resolution → Procedure catalog CSV: looks up titles
- Recommendation entry → Selection and display: returns suggestions
- Selection and display → Procedure user: displays suggestions
- Preprocessing and training → Trained Transformer: trains and saves