adde architectural diagrams

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")

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<br/>Full Access]
+        Educator[👨‍🏫 Educator<br/>Export Features]  
+        Student[👨‍🎓 Student/User<br/>View Only]
+    end
+    
+    %% Frontend Layer
+    subgraph Frontend ["🎨 Presentation Layer"]
+        StreamlitApp[🌐 Streamlit Web App<br/>app.py]
+        UIComponents[📱 UI Components<br/>form_components.py<br/>prediction_components.py]
+        Theme[🎨 Rose Pine Theme<br/>theme.py]
+    end
+    
+    %% Authentication
+    AuthLayer[🔐 Authentication<br/>& Session Management<br/>auth.py]
+    
+    %% Business Logic Layer  
+    subgraph BusinessLogic ["⚙️ Business Logic Layer"]
+        Validation[✅ Input Validation<br/>& Recommendations]
+        Presets[📋 Preset Configurations<br/>mappings.py]
+        DataMappings[🗂️ Data Dictionary<br/>Mappings]
+    end
+    
+    %% ML Layer
+    subgraph MLPipeline ["🤖 Machine Learning Layer"]
+        MLModel[🧠 Random Forest Model<br/>36 Features]
+        Preprocessing[🔄 Data Preprocessing<br/>& One-hot Encoding]
+        ModelUtils[🔧 Model Utils<br/>models_utils.py]
+    end
+    
+    %% Data Layer
+    subgraph DataLayer ["💾 Data Layer"]
+        Dataset[(📊 Student Dataset<br/>data.csv)]
+        DataDict[(📚 Data Dictionary<br/>Excel)]
+        ModelFiles[(💽 Serialized Models<br/>.pkl files)]
+    end
+    
+    %% Training Pipeline
+    Training[🏋️ Model Training<br/>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")

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]
+}

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<br/>Full Access]
+        Educator[👨‍🏫 Educator<br/>Export Features]  
+        Student[👨‍🎓 Student/User<br/>View Only]
+    end
+    
+    %% Frontend Layer
+    subgraph Frontend ["🎨 Presentation Layer"]
+        StreamlitApp[🌐 Streamlit Web App<br/>app.py]
+        UIComponents[📱 UI Components<br/>form_components.py<br/>prediction_components.py]
+        Theme[🎨 Rose Pine Theme<br/>theme.py]
+    end
+    
+    %% Authentication
+    AuthLayer[🔐 Authentication<br/>& Session Management<br/>auth.py]
+    
+    %% Business Logic Layer  
+    subgraph BusinessLogic ["⚙️ Business Logic Layer"]
+        Validation[✅ Input Validation<br/>& Recommendations]
+        Presets[📋 Preset Configurations<br/>mappings.py]
+        DataMappings[🗂️ Data Dictionary<br/>Mappings]
+    end
+    
+    %% ML Layer
+    subgraph MLPipeline ["🤖 Machine Learning Layer"]
+        MLModel[🧠 Random Forest Model<br/>36 Features]
+        Preprocessing[🔄 Data Preprocessing<br/>& One-hot Encoding]
+        ModelUtils[🔧 Model Utils<br/>models_utils.py]
+    end
+    
+    %% Data Layer
+    subgraph DataLayer ["💾 Data Layer"]
+        Dataset[(📊 Student Dataset<br/>data.csv)]
+        DataDict[(📚 Data Dictionary<br/>Excel)]
+        ModelFiles[(💽 Serialized Models<br/>.pkl files)]
+    end
+    
+    %% Training Pipeline
+    Training[🏋️ Model Training<br/>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

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]
+}

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",

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" },