# arthurcornelio88/how-happy-is-europe architecture

> Architecture diagram of the GitHub repository arthurcornelio88/how-happy-is-europe, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arthurcornelio88/how-happy-is-europe
- Repository: https://github.com/arthurcornelio88/how-happy-is-europe

## Overview

##### Project Type and Purpose
- This project is a data science / machine learning application focused on predicting happiness levels in Europe by leveraging the European Social Survey 10 dataset.
- Its purpose is to explore factors affecting happiness and build a predictive model. The codebase supports data preprocessing, exploratory data analysis (EDA), model building, and serving predictions through various interfaces.

##### Main Components
a. Data Sources and Data Layer:
- The “data” directory contains the raw CSV files, descriptions, and feature tables.
- This as the input data source feeding into the system.

b. ML Logic Layer:
- Located in the "howhappyineurope/ml_logic" directory.
- This includes modules for data preprocessing (preprocessor.py, data.py), model training and evaluation (model.py), and a registry for tracking components (registry.py).
- Machine learning artifacts (joblib files for scalers, model, and encoder) stored in the “ml_obj” subdirectory.
- That this layer handles feature engineering, model building, evaluation, and model interpretation.

c. API Layer:
- Found in "howhappyineurope/api/fast.py".
- This component is likely responsible for exposing prediction endpoints (possibly via FastAPI or similar) so that external consumers can request predictions.
- Directional interactions from the API to the ML logic (e.g., receiving inputs, returning predictions).

d. User Interface / Frontend Layer:
- The “howhappyineurope/interface” folder contains “main.py” and “main_local.py”.
- This indicates a clear separation between the service interface (whether for local testing or deployment) and the backend API.

e. Notebooks and Exploratory Analysis:
- There is a “howhappyineurope/notebook” folder containing Jupyter notebooks for exploratory data analysis and experimentation.
- Although not a core production component, it’s useful to show this separate research and prototyping layer that influences development.

f. Configuration and DevOps Elements:
- Files like Dockerfile, Makefile, environment configuration files (.env, etc.), and requirements (requirements.txt, requirements_prod.txt) suggest containerization and deployment scripting.
- Tools as part of the deployment/infrastructure layer, which ensures that the entire system can be reproducibly deployed.

##### Relationships and Data Flow
- The ML logic performs preprocessing, training, and prediction. Its outputs (trained models and artifacts) are stored and later used for inference.
- Optionally, highlight a development/infrastructure bubble where Docker, Makefile, and environment files manage system configuration and deployment.

##### Architectural Patterns and Design Principles
- A modular design pattern: Each responsibility (data handling, processing, serving) is separated into different directories/ components.
- The separation of concerns is evident: Data processing and ML logic are isolated from the API and front end interfaces.
- Use of pre-built machine learning objects (using joblib) and configuration management (via parameters and environment files).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        D["Raw Data (CSV, codebook, features_table, web_crawled_discription)"]:::data
    end

    %% ML Logic Layer
    subgraph "ML Logic Layer"
        ML["ML Logic (data.py, preprocessor.py, model.py, registry.py, joblib artifacts)"]:::ml
    end

    %% API Layer
    subgraph "API Layer"
        API["API (fast.py)"]:::api
    end

    %% User Interface Layer
    subgraph "Interface Layer"
        UI["User Interface (main.py, main_local.py)"]:::ui
    end

    %% Notebooks and Exploratory Analysis
    subgraph "Notebooks/EDA Layer"
        NB["Exploratory Notebooks (Jupyter)"]:::notebooks
    end

    %% Deployment/DevOps Layer
    subgraph "Deployment/DevOps Layer"
        DEV["Deployment & Config (Dockerfile, Makefile, .env, requirements, setup.py)"]:::devops
    end

    %% Data Flow Connections
    D -->|"feeds"| ML
    ML -->|"serves predictions"| API
    UI -->|"requests predictions"| API
    NB -->|"informs development"| ML
    DEV -->|"deploys/configures"| API
    DEV -->|"deploys/configures"| ML
    DEV -->|"deploys/configures"| UI

    %% Click Events
    click D "https://github.com/arthurcornelio88/how-happy-is-europe/tree/master/data/"
    click ML "https://github.com/arthurcornelio88/how-happy-is-europe/tree/master/howhappyineurope/ml_logic/"
    click API "https://github.com/arthurcornelio88/how-happy-is-europe/blob/master/howhappyineurope/api/fast.py"
    click UI "https://github.com/arthurcornelio88/how-happy-is-europe/tree/master/howhappyineurope/interface/"
    click NB "https://github.com/arthurcornelio88/how-happy-is-europe/tree/master/howhappyineurope/notebook/"
    click DEV "https://github.com/arthurcornelio88/how-happy-is-europe/tree/master/Dockerfile"

    %% Styles
    classDef data fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef ml fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef api fill:#e2e3e5,stroke:#383d41,stroke-width:2px;
    classDef ui fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef notebooks fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef devops fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
```
