From e940c2e1ef523747746224ee12be3190a20d2496 Mon Sep 17 00:00:00 2001 From: andwati Date: Tue, 30 Sep 2025 15:25:08 +0300 Subject: [PATCH] adde architectural diagrams --- data/~$Data_Dictionary.xlsx | Bin 165 -> 0 bytes diagrams/create_architecture_diagram.py | 133 ++++++++++++++++++++ diagrams/create_mermaid_diagram.py | 114 +++++++++++++++++ diagrams/student_retention_architecture | 5 + diagrams/student_retention_architecture.mmd | 84 +++++++++++++ diagrams/users | 8 ++ pyproject.toml | 1 + uv.lock | 2 + 8 files changed, 347 insertions(+) delete mode 100644 data/~$Data_Dictionary.xlsx create mode 100644 diagrams/create_architecture_diagram.py create mode 100644 diagrams/create_mermaid_diagram.py create mode 100644 diagrams/student_retention_architecture create mode 100644 diagrams/student_retention_architecture.mmd create mode 100644 diagrams/users diff --git a/data/~$Data_Dictionary.xlsx b/data/~$Data_Dictionary.xlsx deleted file mode 100644 index e719064469604578fcf82bd4d8e91d38e2feb1ef..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 165 ZcmZS1Ow3at9WXOwG9)tOF(}Xl0s#7Q4>te+ diff --git a/diagrams/create_architecture_diagram.py b/diagrams/create_architecture_diagram.py new file mode 100644 index 0000000..e76c7d9 --- /dev/null +++ b/diagrams/create_architecture_diagram.py @@ -0,0 +1,133 @@ +#!/usr/bin/env python3 +""" +Student Retention Predictor - Architecture Diagram Generator + +This script creates a beautiful system architecture diagram using the diagrams library. +The diagram illustrates the complete flow from user interaction to prediction results. +""" + +from diagrams import Diagram +from diagrams.generic.blank import Blank +from diagrams.onprem.client import User +from diagrams.onprem.compute import Server +from diagrams.onprem.database import Postgresql +from diagrams.programming.framework import Fastapi +from diagrams.programming.language import Python +from diagrams.aws.ml import SagemakerModel +from diagrams.onprem.analytics import Spark +from diagrams.generic.storage import Storage +from diagrams.generic.device import Mobile +from diagrams.onprem.security import Vault +from diagrams.programming.flowchart import Decision + +# Set diagram attributes for better appearance +graph_attr = { + "fontsize": "45", + "bgcolor": "transparent", + "dpi": "300", + "margin": "0.5", + "rankdir": "TB", +} + +node_attr = { + "fontsize": "14", + "fontcolor": "#2d3748", + "style": "rounded,filled", + "fillcolor": "#f7fafc", + "color": "#4a5568", +} + +edge_attr = {"fontsize": "12", "fontcolor": "#4a5568", "color": "#4a5568"} + +with Diagram( + "Student Retention Predictor Architecture", + filename="student_retention_architecture", + show=False, + direction="TB", + graph_attr=graph_attr, + node_attr=node_attr, + edge_attr=edge_attr, +): + # User Layer + with Diagram( + "Users", show=False, graph_attr={"label": "User Layer", "style": "dotted"} + ): + admin = User("Admin") + educator = User("Educator") + student = User("Student/User") + + # Frontend Layer + with Diagram( + "Frontend", + show=False, + graph_attr={"label": "Presentation Layer", "style": "dotted"}, + ): + streamlit_app = Server("Streamlit Web App\n(app.py)") + ui_components = Mobile("UI Components\n(form_components.py)") + theme = Blank("Rose Pine Theme\n(theme.py)") + + # Authentication & Security + auth_layer = Vault("Authentication\n& Session Management\n(auth.py)") + + # Business Logic Layer + with Diagram( + "Business Logic", + show=False, + graph_attr={"label": "Business Logic Layer", "style": "dotted"}, + ): + validation = Decision("Input Validation\n& Recommendations") + presets = Storage("Preset Configurations\n(mappings.py)") + data_mappings = Storage("Data Dictionary\nMappings") + + # ML Layer + with Diagram( + "ML Pipeline", + show=False, + graph_attr={"label": "Machine Learning Layer", "style": "dotted"}, + ): + ml_model = SagemakerModel("Random Forest\nModel (36 features)") + preprocessing = Spark("Data Preprocessing\n& One-hot Encoding") + model_utils = Python("Model Utils\n(models_utils.py)") + + # Data Layer + with Diagram( + "Data", show=False, graph_attr={"label": "Data Layer", "style": "dotted"} + ): + dataset = Postgresql("Student Dataset\n(data.csv)") + data_dict = Storage("Data Dictionary\n(Excel)") + model_files = Storage("Serialized Models\n(.pkl files)") + + # Training Pipeline + training = Fastapi("Model Training\n(train_and_save_model.py)") + + # Define connections with labels + [admin, educator, student] >> streamlit_app + + streamlit_app >> auth_layer + auth_layer >> ui_components + ui_components >> [presets, data_mappings] + + streamlit_app >> validation + validation >> preprocessing + preprocessing >> ml_model + + ml_model >> model_utils + model_utils >> streamlit_app + + # Data flow + dataset >> training + data_dict >> data_mappings + training >> model_files + model_files >> ml_model + + # Theme styling + streamlit_app - theme + +print("🎨 Architecture diagram generated successfully!") +print("📁 Check 'student_retention_architecture.png' in the diagrams folder") +print("🔍 The diagram shows the complete system architecture with:") +print(" • User roles and authentication flow") +print(" • Streamlit frontend with modular components") +print(" • ML pipeline with Random Forest model") +print(" • Data layer with preprocessing and mappings") +print(" • Training pipeline and model serialization") diff --git a/diagrams/create_mermaid_diagram.py b/diagrams/create_mermaid_diagram.py new file mode 100644 index 0000000..cd7eb5c --- /dev/null +++ b/diagrams/create_mermaid_diagram.py @@ -0,0 +1,114 @@ +""" +Student Retention Predictor - Mermaid Architecture Diagram + +This generates a beautiful Mermaid diagram that can be rendered as an image +using online tools or VS Code extensions. +""" + +mermaid_diagram = """ +graph TB + %% Styling + classDef userClass fill:#e8f4fd,stroke:#1e40af,stroke-width:2px,color:#1e40af + classDef frontendClass fill:#fef3c7,stroke:#d97706,stroke-width:2px,color:#d97706 + classDef authClass fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px,color:#7c3aed + classDef businessClass fill:#ecfdf5,stroke:#059669,stroke-width:2px,color:#059669 + classDef mlClass fill:#fee2e2,stroke:#dc2626,stroke-width:2px,color:#dc2626 + classDef dataClass fill:#f1f5f9,stroke:#475569,stroke-width:2px,color:#475569 + + %% User Layer + subgraph Users ["👥 User Layer"] + Admin[👨‍💼 Admin
Full Access] + Educator[👨‍🏫 Educator
Export Features] + Student[👨‍🎓 Student/User
View Only] + end + + %% Frontend Layer + subgraph Frontend ["🎨 Presentation Layer"] + StreamlitApp[🌐 Streamlit Web App
app.py] + UIComponents[📱 UI Components
form_components.py
prediction_components.py] + Theme[🎨 Rose Pine Theme
theme.py] + end + + %% Authentication + AuthLayer[🔐 Authentication
& Session Management
auth.py] + + %% Business Logic Layer + subgraph BusinessLogic ["⚙️ Business Logic Layer"] + Validation[✅ Input Validation
& Recommendations] + Presets[📋 Preset Configurations
mappings.py] + DataMappings[🗂️ Data Dictionary
Mappings] + end + + %% ML Layer + subgraph MLPipeline ["🤖 Machine Learning Layer"] + MLModel[🧠 Random Forest Model
36 Features] + Preprocessing[🔄 Data Preprocessing
& One-hot Encoding] + ModelUtils[🔧 Model Utils
models_utils.py] + end + + %% Data Layer + subgraph DataLayer ["💾 Data Layer"] + Dataset[(📊 Student Dataset
data.csv)] + DataDict[(📚 Data Dictionary
Excel)] + ModelFiles[(💽 Serialized Models
.pkl files)] + end + + %% Training Pipeline + Training[🏋️ Model Training
train_and_save_model.py] + + %% Connections + Admin --> StreamlitApp + Educator --> StreamlitApp + Student --> StreamlitApp + + StreamlitApp --> AuthLayer + AuthLayer --> UIComponents + UIComponents --> Presets + UIComponents --> DataMappings + + StreamlitApp --> Validation + Validation --> Preprocessing + Preprocessing --> MLModel + + MLModel --> ModelUtils + ModelUtils --> StreamlitApp + + %% Data Flow + Dataset --> Training + DataDict --> DataMappings + Training --> ModelFiles + ModelFiles --> MLModel + + %% Styling connections + StreamlitApp -.-> Theme + + %% Apply styles + class Admin,Educator,Student userClass + class StreamlitApp,UIComponents,Theme frontendClass + class AuthLayer authClass + class Validation,Presets,DataMappings businessClass + class MLModel,Preprocessing,ModelUtils,Training mlClass + class Dataset,DataDict,ModelFiles dataClass +""" + +# Save the Mermaid diagram +with open("student_retention_architecture.mmd", "w", encoding="utf-8") as f: + f.write(mermaid_diagram) + +print("🎨 Mermaid architecture diagram created successfully!") +print("📁 File saved as: student_retention_architecture.mmd") +print() +print("🌐 To generate a beautiful image:") +print(" 1. Copy the diagram content from the .mmd file") +print(" 2. Paste it into https://mermaid.live/") +print(" 3. Download as PNG/SVG") +print() +print("💡 Or use VS Code with Mermaid Preview extension") +print("📋 The diagram shows:") +print(" • 👥 User roles with different access levels") +print(" • 🎨 Streamlit frontend with modular components") +print(" • 🔐 Authentication and session management") +print(" • ⚙️ Business logic with validation and presets") +print(" • 🤖 ML pipeline with Random Forest model") +print(" • 💾 Data layer with preprocessing and storage") +print(" • 🏋️ Training pipeline for model updates") diff --git a/diagrams/student_retention_architecture b/diagrams/student_retention_architecture new file mode 100644 index 0000000..6865877 --- /dev/null +++ b/diagrams/student_retention_architecture @@ -0,0 +1,5 @@ +digraph "Student Retention Predictor Architecture" { + graph [bgcolor=transparent dpi=300 fontcolor="#2D3436" fontname="Sans-Serif" fontsize=45 label="Student Retention Predictor Architecture" margin=0.5 nodesep=0.60 pad=2.0 rankdir=TB ranksep=0.75 splines=ortho] + node [color="#4a5568" fillcolor="#f7fafc" fixedsize=true fontcolor="#2d3748" fontname="Sans-Serif" fontsize=14 height=1.4 imagescale=true labelloc=b shape=box style="rounded,filled" width=1.4] + edge [color="#4a5568" fontcolor="#4a5568" fontsize=12] +} diff --git a/diagrams/student_retention_architecture.mmd b/diagrams/student_retention_architecture.mmd new file mode 100644 index 0000000..73b440e --- /dev/null +++ b/diagrams/student_retention_architecture.mmd @@ -0,0 +1,84 @@ + +graph TB + %% Styling + classDef userClass fill:#e8f4fd,stroke:#1e40af,stroke-width:2px,color:#1e40af + classDef frontendClass fill:#fef3c7,stroke:#d97706,stroke-width:2px,color:#d97706 + classDef authClass fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px,color:#7c3aed + classDef businessClass fill:#ecfdf5,stroke:#059669,stroke-width:2px,color:#059669 + classDef mlClass fill:#fee2e2,stroke:#dc2626,stroke-width:2px,color:#dc2626 + classDef dataClass fill:#f1f5f9,stroke:#475569,stroke-width:2px,color:#475569 + + %% User Layer + subgraph Users ["👥 User Layer"] + Admin[👨‍💼 Admin
Full Access] + Educator[👨‍🏫 Educator
Export Features] + Student[👨‍🎓 Student/User
View Only] + end + + %% Frontend Layer + subgraph Frontend ["🎨 Presentation Layer"] + StreamlitApp[🌐 Streamlit Web App
app.py] + UIComponents[📱 UI Components
form_components.py
prediction_components.py] + Theme[🎨 Rose Pine Theme
theme.py] + end + + %% Authentication + AuthLayer[🔐 Authentication
& Session Management
auth.py] + + %% Business Logic Layer + subgraph BusinessLogic ["⚙️ Business Logic Layer"] + Validation[✅ Input Validation
& Recommendations] + Presets[📋 Preset Configurations
mappings.py] + DataMappings[🗂️ Data Dictionary
Mappings] + end + + %% ML Layer + subgraph MLPipeline ["🤖 Machine Learning Layer"] + MLModel[🧠 Random Forest Model
36 Features] + Preprocessing[🔄 Data Preprocessing
& One-hot Encoding] + ModelUtils[🔧 Model Utils
models_utils.py] + end + + %% Data Layer + subgraph DataLayer ["💾 Data Layer"] + Dataset[(📊 Student Dataset
data.csv)] + DataDict[(📚 Data Dictionary
Excel)] + ModelFiles[(💽 Serialized Models
.pkl files)] + end + + %% Training Pipeline + Training[🏋️ Model Training
train_and_save_model.py] + + %% Connections + Admin --> StreamlitApp + Educator --> StreamlitApp + Student --> StreamlitApp + + StreamlitApp --> AuthLayer + AuthLayer --> UIComponents + UIComponents --> Presets + UIComponents --> DataMappings + + StreamlitApp --> Validation + Validation --> Preprocessing + Preprocessing --> MLModel + + MLModel --> ModelUtils + ModelUtils --> StreamlitApp + + %% Data Flow + Dataset --> Training + DataDict --> DataMappings + Training --> ModelFiles + ModelFiles --> MLModel + + %% Styling connections + StreamlitApp -.-> Theme + + %% Apply styles + class Admin,Educator,Student userClass + class StreamlitApp,UIComponents,Theme frontendClass + class AuthLayer authClass + class Validation,Presets,DataMappings businessClass + class MLModel,Preprocessing,ModelUtils,Training mlClass + class Dataset,DataDict,ModelFiles dataClass diff --git a/diagrams/users b/diagrams/users new file mode 100644 index 0000000..f7c473f --- /dev/null +++ b/diagrams/users @@ -0,0 +1,8 @@ +digraph Users { + graph [fontcolor="#2D3436" fontname="Sans-Serif" fontsize=15 label="User Layer" nodesep=0.60 pad=2.0 rankdir=LR ranksep=0.75 splines=ortho style=dotted] + node [fixedsize=true fontcolor="#2D3436" fontname="Sans-Serif" fontsize=13 height=1.4 imagescale=true labelloc=b shape=box style=rounded width=1.4] + edge [color="#7B8894"] + e79ce4bc44eb491994406be045426c22 [label=Admin height=1.9 image="C:\Users\ian\dev\student-retention\.venv\Lib\site-packages\resources/onprem/client\user.png" shape=none] + "00031a42a8bb4703ba1210f4a164f2c2" [label=Educator height=1.9 image="C:\Users\ian\dev\student-retention\.venv\Lib\site-packages\resources/onprem/client\user.png" shape=none] + f1824916c09f467e872a27833d9b90a6 [label="Student/User" height=1.9 image="C:\Users\ian\dev\student-retention\.venv\Lib\site-packages\resources/onprem/client\user.png" shape=none] +} diff --git a/pyproject.toml b/pyproject.toml index 3a067b4..1129cdf 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,6 +6,7 @@ readme = "README.md" requires-python = ">=3.13" dependencies = [ "diagrams>=0.24.4", + "graphviz>=0.20.3", "matplotlib>=3.10.6", "numpy>=2.3.3", "pandas>=2.3.2", diff --git a/uv.lock b/uv.lock index ab75165..abf4d58 100644 --- a/uv.lock +++ b/uv.lock @@ -1068,6 +1068,7 @@ version = "0.1.0" source = { virtual = "." } dependencies = [ { name = "diagrams" }, + { name = "graphviz" }, { name = "matplotlib" }, { name = "numpy" }, { name = "pandas" }, @@ -1080,6 +1081,7 @@ dependencies = [ [package.metadata] requires-dist = [ { name = "diagrams", specifier = ">=0.24.4" }, + { name = "graphviz", specifier = ">=0.20.3" }, { name = "matplotlib", specifier = ">=3.10.6" }, { name = "numpy", specifier = ">=2.3.3" }, { name = "pandas", specifier = ">=2.3.2" },