# michou001/intelligent-recommendation-plataform architecture

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

- Interactive diagram: https://gitdiagram.com/michou001/intelligent-recommendation-plataform
- Repository: https://github.com/michou001/intelligent-recommendation-plataform

## Overview

The Intelligent Recommendation Platform serves personalized Top-K recommendations and records user interactions. Its main request path is user → REST API → recommendation controller → feature lookup → selected strategy → catalog enrichment → response; the controller also publishes an interaction event for asynchronous history storage. Separately, a four-stage offline pipeline prepares features for inference. The graph preserves the README’s strategy, decorator, persistence, and messaging capabilities. Some relationships are documented rather than verified from complete source excerpts; those edges cite the README, and unsampled details are not inferred.

Main entry points: [`src/application/recommendation_controller.py`](https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/application/recommendation_controller.py) (Recommendation Controller), [`src/application/api.py`](https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/application/api.py) (REST API), [`src/ai/model_factory.py`](https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/ai/model_factory.py) (Model Factory), [`src/data/feature_store_manager.py`](https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/data/feature_store_manager.py) (Feature Store Reader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_web["Web Interface<br/>[index.html]"]
  node_schemas["Request Schemas<br/>[schemas.py]"]
end

subgraph group_application["Application"]
  node_api["REST API<br/>[api.py]"]
  node_controller["Recommendation Controller"]
  node_ingestion["Interaction Ingestion"]
  node_settings["Platform Settings<br/>[settings.py]"]
end

subgraph group_recommendation["Recommendation Engine"]
  node_factory["Model Factory<br/>[model_factory.py]"]
  node_collaborative["Collaborative Filtering"]
  node_content["Content-Based Strategy"]
  node_deep["Deep Learning Strategy"]
  node_popularity["Popularity Fallback"]
  node_caching["Caching Decorator"]
  node_logging["Logging Decorator"]
  node_timing["Timing Decorator"]
end

subgraph group_data["Data Preparation"]
  node_featurestore[("Feature Store Reader")]
  node_ingest["Dataset Ingestion<br/>[ingest.py]"]
  node_clean["Data Cleaning<br/>[clean.py]"]
  node_transform["Feature Transformation<br/>[transform.py]"]
  node_materialize["Feature Materialization<br/>[materialize.py]"]
end

subgraph group_storage["Persistence and Messaging"]
  node_profiles[("User Profiles")]
  node_catalog[("Item Catalog")]
  node_queue["Interaction Event Queue"]
  node_feedback["Feedback History Worker"]
  node_history[("Interaction History")]
  node_embeddings[("Embedding Repository")]
end

node_user(("User"))

node_user -->|"uses"| node_web
node_web -->|"calls endpoints"| node_api
node_api -->|"validates with"| node_schemas
node_api -->|"routes requests"| node_controller
node_api -->|"routes interactions"| node_ingestion
node_api -->|"creates strategy"| node_factory
node_api -->|"configures"| node_settings
node_controller -->|"loads features"| node_featurestore
node_controller -->|"predicts via"| node_collaborative
node_controller -->|"predicts via"| node_content
node_controller -->|"predicts via"| node_deep
node_controller -->|"falls back to"| node_popularity
node_factory -->|"loads registered"| node_collaborative
node_factory -->|"loads registered"| node_content
node_factory -->|"loads registered"| node_deep
node_factory -->|"loads registered"| node_popularity
node_api -->|"builds decorators"| node_caching
node_api -->|"builds decorators"| node_logging
node_api -->|"builds decorators"| node_timing
node_controller -->|"reads profile"| node_profiles
node_controller -->|"enriches ranking"| node_catalog
node_controller -->|"publishes event"| node_queue
node_ingestion -->|"publishes interaction"| node_queue
node_queue -->|"delivers events"| node_feedback
node_feedback -->|"writes history"| node_history
node_ingest -->|"writes raw data"| node_clean
node_clean -->|"writes cleaned data"| node_transform
node_transform -->|"writes features"| node_materialize
node_materialize -->|"materializes for"| node_featurestore
node_featurestore -->|"returns features"| node_controller

click node_web "https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/presentation/static/index.html"
click node_schemas "https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/presentation/schemas.py"
click node_api "https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/application/api.py"
click node_controller "https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/application/recommendation_controller.py"
click node_ingestion "https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/application/interaction_ingestion_service.py"
click node_settings "https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/config/settings.py"
click node_featurestore "https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/data/feature_store_manager.py"
click node_ingest "https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/data/pipeline/ingest.py"
click node_clean "https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/data/pipeline/clean.py"
click node_transform "https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/data/pipeline/transform.py"
click node_materialize "https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/data/pipeline/materialize.py"
click node_factory "https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/ai/model_factory.py"
click node_collaborative "https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/ai/strategies/collaborative_filtering_strategy.py"
click node_content "https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/ai/strategies/content_based_strategy.py"
click node_deep "https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/ai/strategies/deep_learning_strategy.py"
click node_popularity "https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/ai/strategies/popularity_strategy.py"
click node_caching "https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/ai/decorators/caching_decorator.py"
click node_logging "https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/ai/decorators/logging_decorator.py"
click node_timing "https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/ai/decorators/timing_decorator.py"
click node_profiles "https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/persistence/sql_user_profile_repository.py"
click node_catalog "https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/persistence/sql_catalog_repository.py"
click node_queue "https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/messaging/interaction_event_queue.py"
click node_feedback "https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/messaging/feedback_history_service.py"
click node_history "https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/persistence/nosql_interaction_history_repository.py"
click node_embeddings "https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/persistence/vector_embedding_repository.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_web,node_schemas,node_user toneBlue
class node_api,node_controller,node_ingestion,node_settings toneAmber
class node_factory,node_collaborative,node_content,node_deep,node_popularity,node_caching,node_logging,node_timing toneMint
class node_featurestore,node_ingest,node_clean,node_transform,node_materialize toneRose
class node_profiles,node_catalog,node_queue,node_feedback,node_history,node_embeddings toneIndigo
```

## Components

### Presentation

- [Web Interface](https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/presentation/static/index.html): `src/presentation/static/index.html`
- [Request Schemas](https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/presentation/schemas.py): `src/presentation/schemas.py`

### Application

- [REST API](https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/application/api.py): `src/application/api.py`
- [Recommendation Controller](https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/application/recommendation_controller.py): `src/application/recommendation_controller.py`
- [Interaction Ingestion](https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/application/interaction_ingestion_service.py): `src/application/interaction_ingestion_service.py`
- [Platform Settings](https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/config/settings.py): `src/config/settings.py`

### Recommendation Engine

- [Model Factory](https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/ai/model_factory.py): `src/ai/model_factory.py`
- [Collaborative Filtering](https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/ai/strategies/collaborative_filtering_strategy.py): `src/ai/strategies/collaborative_filtering_strategy.py`
- [Content-Based Strategy](https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/ai/strategies/content_based_strategy.py): `src/ai/strategies/content_based_strategy.py`
- [Deep Learning Strategy](https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/ai/strategies/deep_learning_strategy.py): `src/ai/strategies/deep_learning_strategy.py`
- [Popularity Fallback](https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/ai/strategies/popularity_strategy.py): `src/ai/strategies/popularity_strategy.py`
- [Caching Decorator](https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/ai/decorators/caching_decorator.py): `src/ai/decorators/caching_decorator.py`
- [Logging Decorator](https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/ai/decorators/logging_decorator.py): `src/ai/decorators/logging_decorator.py`
- [Timing Decorator](https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/ai/decorators/timing_decorator.py): `src/ai/decorators/timing_decorator.py`

### Data Preparation

- [Feature Store Reader](https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/data/feature_store_manager.py): `src/data/feature_store_manager.py`
- [Dataset Ingestion](https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/data/pipeline/ingest.py): `src/data/pipeline/ingest.py`
- [Data Cleaning](https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/data/pipeline/clean.py): `src/data/pipeline/clean.py`
- [Feature Transformation](https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/data/pipeline/transform.py): `src/data/pipeline/transform.py`
- [Feature Materialization](https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/data/pipeline/materialize.py): `src/data/pipeline/materialize.py`

### Persistence and Messaging

- [User Profiles](https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/persistence/sql_user_profile_repository.py): `src/persistence/sql_user_profile_repository.py`
- [Item Catalog](https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/persistence/sql_catalog_repository.py): `src/persistence/sql_catalog_repository.py`
- [Interaction Event Queue](https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/messaging/interaction_event_queue.py): `src/messaging/interaction_event_queue.py`
- [Feedback History Worker](https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/messaging/feedback_history_service.py): `src/messaging/feedback_history_service.py`
- [Interaction History](https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/persistence/nosql_interaction_history_repository.py): `src/persistence/nosql_interaction_history_repository.py`
- [Embedding Repository](https://github.com/michou001/intelligent-recommendation-plataform/blob/main/src/persistence/vector_embedding_repository.py): `src/persistence/vector_embedding_repository.py`

### Other components

- **User**

## Connections

- User → Web Interface: uses (evidence: `README.md`)
- Web Interface → REST API: calls endpoints (evidence: `README.md`)
- REST API → Request Schemas: validates with (evidence: `README.md`)
- REST API → Recommendation Controller: routes requests (evidence: `README.md`)
- REST API → Interaction Ingestion: routes interactions (evidence: `src/application/api.py`)
- REST API → Model Factory: creates strategy (evidence: `src/application/api.py`)
- REST API → Platform Settings: configures (evidence: `src/application/api.py`)
- Recommendation Controller → Feature Store Reader: loads features (evidence: `src/application/recommendation_controller.py`)
- Recommendation Controller → Collaborative Filtering: predicts via (evidence: `README.md`)
- Recommendation Controller → Content-Based Strategy: predicts via (evidence: `README.md`)
- Recommendation Controller → Deep Learning Strategy: predicts via (evidence: `README.md`)
- Recommendation Controller → Popularity Fallback: falls back to (evidence: `src/application/recommendation_controller.py`)
- Model Factory → Collaborative Filtering: loads registered (evidence: `src/ai/model_factory.py`)
- Model Factory → Content-Based Strategy: loads registered (evidence: `src/ai/model_factory.py`)
- Model Factory → Deep Learning Strategy: loads registered (evidence: `src/ai/model_factory.py`)
- Model Factory → Popularity Fallback: loads registered (evidence: `src/ai/model_factory.py`)
- REST API → Caching Decorator: builds decorators (evidence: `README.md`)
- REST API → Logging Decorator: builds decorators (evidence: `README.md`)
- REST API → Timing Decorator: builds decorators (evidence: `README.md`)
- Recommendation Controller → User Profiles: reads profile (evidence: `README.md`)
- Recommendation Controller → Item Catalog: enriches ranking (evidence: `src/application/recommendation_controller.py`)
- Recommendation Controller → Interaction Event Queue: publishes event (evidence: `src/application/recommendation_controller.py`)
- Interaction Ingestion → Interaction Event Queue: publishes interaction (evidence: `src/application/interaction_ingestion_service.py`)
- Interaction Event Queue → Feedback History Worker: delivers events (evidence: `src/messaging/interaction_event_queue.py`)
- Feedback History Worker → Interaction History: writes history (evidence: `src/messaging/feedback_history_service.py`)
- Dataset Ingestion → Data Cleaning: writes raw data (evidence: `README.md`)
- Data Cleaning → Feature Transformation: writes cleaned data (evidence: `README.md`)
- Feature Transformation → Feature Materialization: writes features (evidence: `README.md`)
- Feature Materialization → Feature Store Reader: materializes for (evidence: `README.md`)
- Feature Store Reader → Recommendation Controller: returns features (evidence: `src/application/recommendation_controller.py`)
