# sectechsociety/smart-study-plan-generator architecture

> Architecture diagram of the GitHub repository sectechsociety/smart-study-plan-generator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sectechsociety/smart-study-plan-generator
- Repository: https://github.com/sectechsociety/smart-study-plan-generator

## Overview

#### Purpose and Entry Points
This is a local Streamlit application that creates personalized weekly study plans. It combines ANN-based total-hour prediction, difficulty-weighted allocation, availability-constrained timetable generation, SQLite persistence, and per-user authentication.

Primary runtime entry point: `smart-study-plan-generator-complete/app.py`.  
Model training/export entry point: `smart-study-plan-generator-complete/train_and_export_model.py`.

#### Streamlit Application Orchestration
`app.py` is the application boundary between user input and planning services. It collects CGPA targets, dynamically defined subjects and difficulty levels, and weekly available time slots; it also presents generated plans and persisted plan history.

Relevant paths:
- `smart-study-plan-generator-complete/app.py`
- `smart-study-plan-generator-complete/auth.py`
- `smart-study-plan-generator-complete/database.py`

#### Authentication and User Isolation
Authentication is implemented separately and backed by SQLite. Signup/login establishes the user identity used to scope saved and retrieved study plans, preventing one user’s historical plans from appearing in another’s view.

Relevant paths:
- `smart-study-plan-generator-complete/auth.py`
- `smart-study-plan-generator-complete/database.py`
- `smart-study-plan-generator-complete/study_planner.db`

#### ML Prediction Boundary
The planner predicts a single total weekly study-hours value from current and target CGPA. At runtime, the application consumes a pre-exported TensorFlow/Keras H5 artifact. If the artifact or ML runtime is unavailable, the system has rule-based fallback behavior rather than blocking plan creation.

Relevant paths:
- `smart-study-plan-generator-complete/model/total_hours_model.h5`
- `smart-study-plan-generator-complete/app.py`
- `smart-study-plan-generator-complete/train_and_export_model.py`

#### Training and Data Pipeline
Offline training reads synthetic academic data, trains the total-hours neural network, and exports the inference artifact consumed by the Streamlit application. Training is operationally distinct from the interactive request path.

Relevant paths:
- `smart-study-plan-generator-complete/train_and_export_model.py`
- `smart-study-plan-generator-complete/data/synthetic_full.csv`
- `smart-study-plan-generator-complete/model/total_hours_model.h5`

#### Planning and Scheduling Flow
The central flow is: authenticated user input → total-hours prediction/fallback → subject-hour distribution weighted by subject difficulty → slot-level weekly timetable. The scheduler has a two-stage constraint policy: first allocate at least one slot to every subject, then use remaining availability proportionally by difficulty. Scheduling is bounded by user-selected time slots, so allocated study intent must be reconciled with finite calendar capacity.

Relevant paths:
- `smart-study-plan-generator-complete/app.py`
- `smart-study-plan-generator-complete/model/total_hours_model.h5`

#### Persistence and Runtime Dependencies
SQLite is the persistent system of record for credentials and generated-plan history, including retrieval of the latest timetable after later login. The application is intended for local Python 3.9–3.11 execution through Streamlit; TensorFlow/Keras supports training and model inference. Dependency declarations are in `smart-study-plan-generator-complete/requirements.txt`.

Relevant paths:
- `smart-study-plan-generator-complete/database.py`
- `smart-study-plan-generator-complete/study_planner.db`
- `smart-study-plan-generator-complete/requirements.txt`

Main entry points: [`smart-study-plan-generator-complete/app.py`](https://github.com/sectechsociety/smart-study-plan-generator/blob/main/smart-study-plan-generator-complete/app.py) (Streamlit app), [`smart-study-plan-generator-complete/database.py`](https://github.com/sectechsociety/smart-study-plan-generator/blob/main/smart-study-plan-generator-complete/database.py) (Database access), [`smart-study-plan-generator-complete/train_and_export_model.py`](https://github.com/sectechsociety/smart-study-plan-generator/blob/main/smart-study-plan-generator-complete/train_and_export_model.py) (Model training/export), [`smart-study-plan-generator-complete/model/total_hours_model.h5`](https://github.com/sectechsociety/smart-study-plan-generator/blob/main/smart-study-plan-generator-complete/model/total_hours_model.h5) (Total-hours model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Interactive Application"]
  node_streamlit["Streamlit app<br/>[app.py]"]
  node_auth["Authentication<br/>auth module<br/>[auth.py]"]
  node_user_input["Student inputs<br/>[app.py]"]
  node_prediction["Total-hours prediction<br/>planning stage<br/>[app.py]"]
  node_allocation["Difficulty allocation<br/>planning stage<br/>[app.py]"]
  node_scheduler["Weekly scheduler<br/>planning stage<br/>[app.py]"]
  node_plan_history["Plan history view<br/>presentation<br/>[app.py]"]
end

subgraph group_ml["ML Pipeline"]
  node_trainer["Model training/export<br/>training job"]
  node_synthetic_data["Synthetic academic data<br/>training data<br/>[synthetic_full.csv]"]
  node_hours_model{{"Total-hours model<br/>Keras H5 artifact"}}
end

subgraph group_data["Persistence"]
  node_database[("SQLite database<br/>system of record<br/>[study_planner.db]")]
  node_database_module["Database access<br/>persistence module<br/>[database.py]"]
end

node_dependencies["Runtime dependencies<br/>dependency manifest<br/>[requirements.txt]"]

node_user_input -->|"submits"| node_streamlit
node_streamlit -->|"authenticates user"| node_auth
node_auth -->|"reads/writes credentials"| node_database_module
node_streamlit -->|"passes CGPAs"| node_prediction
node_prediction -->|"loads for inference"| node_hours_model
node_prediction -->|"total weekly hours"| node_allocation
node_allocation -->|"subject-hour targets"| node_scheduler
node_user_input -->|"availability constraints"| node_scheduler
node_scheduler -->|"saves timetable by user"| node_database_module
node_streamlit -->|"requests latest plans"| node_plan_history
node_plan_history -->|"loads user-scoped history"| node_database_module
node_database_module -->|"persists records"| node_database
node_synthetic_data -->|"training input"| node_trainer
node_trainer -->|"exports"| node_hours_model
node_hours_model -.->|"unavailable: fallback"| node_prediction
node_dependencies -.->|"supports runtime"| node_streamlit
node_dependencies -.->|"supports training"| node_trainer

click node_streamlit "https://github.com/sectechsociety/smart-study-plan-generator/blob/main/smart-study-plan-generator-complete/app.py"
click node_auth "https://github.com/sectechsociety/smart-study-plan-generator/blob/main/smart-study-plan-generator-complete/auth.py"
click node_user_input "https://github.com/sectechsociety/smart-study-plan-generator/blob/main/smart-study-plan-generator-complete/app.py"
click node_prediction "https://github.com/sectechsociety/smart-study-plan-generator/blob/main/smart-study-plan-generator-complete/app.py"
click node_allocation "https://github.com/sectechsociety/smart-study-plan-generator/blob/main/smart-study-plan-generator-complete/app.py"
click node_scheduler "https://github.com/sectechsociety/smart-study-plan-generator/blob/main/smart-study-plan-generator-complete/app.py"
click node_plan_history "https://github.com/sectechsociety/smart-study-plan-generator/blob/main/smart-study-plan-generator-complete/app.py"
click node_trainer "https://github.com/sectechsociety/smart-study-plan-generator/blob/main/smart-study-plan-generator-complete/train_and_export_model.py"
click node_synthetic_data "https://github.com/sectechsociety/smart-study-plan-generator/blob/main/smart-study-plan-generator-complete/data/synthetic_full.csv"
click node_hours_model "https://github.com/sectechsociety/smart-study-plan-generator/blob/main/smart-study-plan-generator-complete/model/total_hours_model.h5"
click node_database "https://github.com/sectechsociety/smart-study-plan-generator/blob/main/smart-study-plan-generator-complete/study_planner.db"
click node_database_module "https://github.com/sectechsociety/smart-study-plan-generator/blob/main/smart-study-plan-generator-complete/database.py"
click node_dependencies "https://github.com/sectechsociety/smart-study-plan-generator/blob/main/smart-study-plan-generator-complete/requirements.txt"

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_streamlit,node_auth,node_user_input,node_prediction,node_allocation,node_scheduler,node_plan_history toneBlue
class node_trainer,node_synthetic_data,node_hours_model toneAmber
class node_database,node_database_module toneMint
class node_dependencies toneNeutral
```

## Components

### Interactive Application

- [Streamlit app](https://github.com/sectechsociety/smart-study-plan-generator/blob/main/smart-study-plan-generator-complete/app.py): application · Collects inputs, creates plans, and shows history. · `smart-study-plan-generator-complete/app.py`
- [Authentication](https://github.com/sectechsociety/smart-study-plan-generator/blob/main/smart-study-plan-generator-complete/auth.py): auth module · Establishes the identity used to isolate plans. · `smart-study-plan-generator-complete/auth.py`
- [Student inputs](https://github.com/sectechsociety/smart-study-plan-generator/blob/main/smart-study-plan-generator-complete/app.py): input · CGPAs, subjects, difficulty, and weekly slots. · `smart-study-plan-generator-complete/app.py`
- [Total-hours prediction](https://github.com/sectechsociety/smart-study-plan-generator/blob/main/smart-study-plan-generator-complete/app.py): planning stage · Predicts weekly study hours with a rule-based fallback. · `smart-study-plan-generator-complete/app.py`
- [Difficulty allocation](https://github.com/sectechsociety/smart-study-plan-generator/blob/main/smart-study-plan-generator-complete/app.py): planning stage · Distributes predicted hours across subjects by difficulty. · `smart-study-plan-generator-complete/app.py`
- [Weekly scheduler](https://github.com/sectechsociety/smart-study-plan-generator/blob/main/smart-study-plan-generator-complete/app.py): planning stage · Assigns every subject first, then fills remaining slots proportionally. · `smart-study-plan-generator-complete/app.py`
- [Plan history view](https://github.com/sectechsociety/smart-study-plan-generator/blob/main/smart-study-plan-generator-complete/app.py): presentation · Displays saved plans for the logged-in user. · `smart-study-plan-generator-complete/app.py`

### ML Pipeline

- [Model training/export](https://github.com/sectechsociety/smart-study-plan-generator/blob/main/smart-study-plan-generator-complete/train_and_export_model.py): training job · Trains and exports the total-hours inference model offline. · `smart-study-plan-generator-complete/train_and_export_model.py`
- [Synthetic academic data](https://github.com/sectechsociety/smart-study-plan-generator/blob/main/smart-study-plan-generator-complete/data/synthetic_full.csv): training data · `smart-study-plan-generator-complete/data/synthetic_full.csv`
- [Total-hours model](https://github.com/sectechsociety/smart-study-plan-generator/blob/main/smart-study-plan-generator-complete/model/total_hours_model.h5): Keras H5 artifact · Runtime inference artifact for weekly total hours. · `smart-study-plan-generator-complete/model/total_hours_model.h5`

### Persistence

- [SQLite database](https://github.com/sectechsociety/smart-study-plan-generator/blob/main/smart-study-plan-generator-complete/study_planner.db): system of record · Stores credentials and user-scoped generated plans. · `smart-study-plan-generator-complete/study_planner.db`
- [Database access](https://github.com/sectechsociety/smart-study-plan-generator/blob/main/smart-study-plan-generator-complete/database.py): persistence module · `smart-study-plan-generator-complete/database.py`

### Other components

- [Runtime dependencies](https://github.com/sectechsociety/smart-study-plan-generator/blob/main/smart-study-plan-generator-complete/requirements.txt): dependency manifest · Declares Streamlit and TensorFlow/Keras runtime support. · `smart-study-plan-generator-complete/requirements.txt`

## Connections

- Student inputs → Streamlit app: submits
- Streamlit app → Authentication: authenticates user
- Authentication → Database access: reads/writes credentials
- Streamlit app → Total-hours prediction: passes CGPAs
- Total-hours prediction → Total-hours model: loads for inference
- Total-hours prediction → Difficulty allocation: total weekly hours
- Difficulty allocation → Weekly scheduler: subject-hour targets
- Student inputs → Weekly scheduler: availability constraints
- Weekly scheduler → Database access: saves timetable by user
- Streamlit app → Plan history view: requests latest plans
- Plan history view → Database access: loads user-scoped history
- Database access → SQLite database: persists records
- Synthetic academic data → Model training/export: training input
- Model training/export → Total-hours model: exports
- Total-hours model → Total-hours prediction: unavailable: fallback
- Runtime dependencies → Streamlit app: supports runtime
- Runtime dependencies → Model training/export: supports training