# ykato27/careernavigator architecture

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

- Interactive diagram: https://gitdiagram.com/ykato27/careernavigator
- Repository: https://github.com/ykato27/careernavigator

## Overview

##### Main components
a. Data Stores
- Input CSV directories under `data/` (members, acquired, skills, education, license, categories)
- Output CSV directory `output/`
b. Core Library (skillnote_recommendation package)
1. Data Ingestion & Transformation
- config_loader.py / core/config.py
- core/data_loader.py
- core/data_transformer.py
2. Rule‐Based Recommendation
- core/similarity_calculator.py
- core/recommendation_engine.py
- core/recommendation_system.py
- core/evaluator.py
3. Machine‐Learning Recommendation
- ml/matrix_factorization.py
- ml/ml_recommender.py
- ml/diversity.py
4. Knowledge‐Graph & Visualization
- graph/knowledge_graph.py
- graph/hybrid_recommender.py
- graph/random_walk.py
- graph/career_path.py + career_path_visualizer.py
- graph/path_visualizer.py + visualization_utils.py
5. Utility Modules
- utils/streamlit_helpers.py
- utils/visualization.py
c. Execution Interfaces
- Streamlit Web UI (`streamlit_app.py` + `pages/1_Model_Training.py`, `pages/2_Inference.py`)
- CLI Scripts (`scripts/convert_data.py`, `scripts/run_recommendation.py`)
d. Tests & Documentation
- tests/…
- docs/…

##### Relationships & data flows
- Input CSVs → DataLoader → DataTransformer → “Clean” DataFrames →
- Rule‐Based Engine → RecommendationSystem
- MLRecommender → (optional) Diversity module → RecommendationSystem
- RecommendationSystem → Evaluator (for offline metrics)
- RecommendationSystem & Graph modules → Web UI / CLI
- Web UI & CLI → Output CSVs / On‐screen visualizations

##### Architectural patterns & design principles
- Layered architecture:
- Data layer (CSV files)
- Processing layer (ingestion, transformation)
- Business logic layer (rule‐based + ML engines)
- Presentation layer (Streamlit UI + CLI)
- Modular design: clear separation of core modules (rule‐based) vs. ML modules vs. graph/visualization.
- Extensibility: configuration via YAML, pluggable RecommendationEngine subclassing, ML‐diversity strategies.

##### Technologies & frameworks
- Python 3.11+
- pandas / numpy (data handling)
- scikit‐learn & NMF (ML recommender)
- Streamlit (web frontend)
- networkx or custom graph code (knowledge graph)
- uv (environment + CLI)

- Clear component labels (e.g., “DataTransformer”, “MLRecommender”)
- Arrowheads for data flow direction

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Zone
    subgraph "Data Zone"
        direction TB
        DataCSV["Input CSV Directories"]:::data
        DataOut["Output CSV Directory"]:::data
    end

    %% Configuration
    ConfigYAML["config.yaml"]:::config
    ConfigLoader["Config Loader"]:::config
    CoreConfig["Core Config Module"]:::config

    %% Data Ingestion & Transformation
    DataLoader["Data Loader"]:::processing
    DataTransformer["Data Transformer"]:::processing

    %% Rule-Based Recommendation
    SimilarityCalc["Similarity Calculator"]:::processing
    RecEngine["Recommendation Engine"]:::processing
    RecSys["Recommendation System"]:::processing
    Evaluator["Evaluator"]:::processing

    %% Core Models
    Models["Models"]:::processing
    RefPersons["Reference Persons"]:::processing
    RoleModel["Role Model"]:::processing

    %% Machine-Learning Recommendation
    MatrixFact["Matrix Factorization"]:::processing
    MLRec["ML Recommender"]:::processing
    Diversity["Diversity Module"]:::processing

    %% Knowledge-Graph & Visualization
    KG["Knowledge Graph"]:::processing
    HybridRec["Hybrid Recommender"]:::processing
    RandomWalk["Random Walk"]:::processing
    CareerPath["Career Path Logic"]:::processing
    CareerViz["Career Path Visualizer"]:::processing
    PathViz["Path Visualizer"]:::processing
    VisUtils["Visualization Utils"]:::processing

    %% Utility Modules
    StreamlitHelpers["Streamlit Helpers"]:::util
    GenVis["Visualization Utils"]:::util

    %% Frontend Zone
    subgraph "Presentation Layer"
        direction TB
        StreamlitApp["Streamlit App"]:::frontend
        Page1["1_Model_Training Page"]:::frontend
        Page2["2_Inference Page"]:::frontend
        CLIConvert["convert_data Script"]:::frontend
        CLIRun["run_recommendation Script"]:::frontend
    end

    %% Data Flow
    DataCSV -->|"Raw CSV → DataFrame"| DataLoader
    DataLoader -->|"Clean DataFrame"| DataTransformer
    DataTransformer -->|"Features"| SimilarityCalc
    DataTransformer -->|"Features"| MatrixFact
    DataTransformer -->|"Graph Data"| KG

    %% Config Flow
    ConfigYAML -->|"load"| ConfigLoader -->|"apply"| CoreConfig
    CoreConfig --> DataLoader
    CoreConfig --> SimilarityCalc
    CoreConfig --> MatrixFact
    CoreConfig --> KG

    %% Rule-Based Flow
    SimilarityCalc --> RecEngine --> RecSys
    Models --> RecEngine
    RefPersons --> RecEngine
    RoleModel --> RecEngine
    RecSys --> Evaluator

    %% ML Flow
    MatrixFact --> MLRec --> Diversity --> RecSys

    %% Graph Flow
    KG --> HybridRec --> RecSys
    RandomWalk --> HybridRec
    CareerPath --> CareerViz
    PathViz --> CareerViz
    VisUtils --> CareerViz

    %% Utilities
    StreamlitHelpers --> StreamlitApp
    GenVis --> CareerViz

    %% Frontend Interactions
    StreamlitApp --> Page1
    StreamlitApp --> Page2
    Page1 --> RecSys
    Page2 --> RecSys
    CLIConvert --> DataLoader
    CLIRun --> RecSys
    RecSys -->|"Recommendations"| DataOut
    RecSys -->|"Recommendations"| StreamlitApp

    %% Click Events
    click DataCSV "https://github.com/ykato27/careernavigator/tree/main/data/"
    click DataOut "https://github.com/ykato27/careernavigator/tree/main/output/"
    click ConfigYAML "https://github.com/ykato27/careernavigator/blob/main/skillnote_recommendation/config.yaml"
    click ConfigLoader "https://github.com/ykato27/careernavigator/blob/main/skillnote_recommendation/config_loader.py"
    click CoreConfig "https://github.com/ykato27/careernavigator/blob/main/skillnote_recommendation/core/config.py"
    click DataLoader "https://github.com/ykato27/careernavigator/blob/main/skillnote_recommendation/core/data_loader.py"
    click DataTransformer "https://github.com/ykato27/careernavigator/blob/main/skillnote_recommendation/core/data_transformer.py"
    click SimilarityCalc "https://github.com/ykato27/careernavigator/blob/main/skillnote_recommendation/core/similarity_calculator.py"
    click RecEngine "https://github.com/ykato27/careernavigator/blob/main/skillnote_recommendation/core/recommendation_engine.py"
    click RecSys "https://github.com/ykato27/careernavigator/blob/main/skillnote_recommendation/core/recommendation_system.py"
    click Evaluator "https://github.com/ykato27/careernavigator/blob/main/skillnote_recommendation/core/evaluator.py"
    click Models "https://github.com/ykato27/careernavigator/blob/main/skillnote_recommendation/core/models.py"
    click RefPersons "https://github.com/ykato27/careernavigator/blob/main/skillnote_recommendation/core/reference_persons.py"
    click RoleModel "https://github.com/ykato27/careernavigator/blob/main/skillnote_recommendation/core/role_model.py"
    click MatrixFact "https://github.com/ykato27/careernavigator/blob/main/skillnote_recommendation/ml/matrix_factorization.py"
    click MLRec "https://github.com/ykato27/careernavigator/blob/main/skillnote_recommendation/ml/ml_recommender.py"
    click Diversity "https://github.com/ykato27/careernavigator/blob/main/skillnote_recommendation/ml/diversity.py"
    click KG "https://github.com/ykato27/careernavigator/blob/main/skillnote_recommendation/graph/knowledge_graph.py"
    click HybridRec "https://github.com/ykato27/careernavigator/blob/main/skillnote_recommendation/graph/hybrid_recommender.py"
    click RandomWalk "https://github.com/ykato27/careernavigator/blob/main/skillnote_recommendation/graph/random_walk.py"
    click CareerPath "https://github.com/ykato27/careernavigator/blob/main/skillnote_recommendation/graph/career_path.py"
    click CareerViz "https://github.com/ykato27/careernavigator/blob/main/skillnote_recommendation/graph/career_path_visualizer.py"
    click PathViz "https://github.com/ykato27/careernavigator/blob/main/skillnote_recommendation/graph/path_visualizer.py"
    click VisUtils "https://github.com/ykato27/careernavigator/blob/main/skillnote_recommendation/graph/visualization_utils.py"
    click StreamlitHelpers "https://github.com/ykato27/careernavigator/blob/main/skillnote_recommendation/utils/streamlit_helpers.py"
    click GenVis "https://github.com/ykato27/careernavigator/blob/main/skillnote_recommendation/utils/visualization.py"
    click StreamlitApp "https://github.com/ykato27/careernavigator/blob/main/streamlit_app.py"
    click Page1 "https://github.com/ykato27/careernavigator/blob/main/pages/1_Model_Training.py"
    click Page2 "https://github.com/ykato27/careernavigator/blob/main/pages/2_Inference.py"
    click CLIConvert "https://github.com/ykato27/careernavigator/blob/main/skillnote_recommendation/scripts/convert_data.py"
    click CLIRun "https://github.com/ykato27/careernavigator/blob/main/skillnote_recommendation/scripts/run_recommendation.py"

    %% Styles
    classDef data fill:#D6EFFF,stroke:#a4c2f4;
    classDef processing fill:#E6FFE6,stroke:#8cc08c;
    classDef config fill:#FFF5CC,stroke:#E1C05A;
    classDef frontend fill:#FFE6CC,stroke:#f4a460;
    classDef util fill:#FFE6FF,stroke:#d28cc0;
```
