Modelora — Interactive Machine Learning Studio

Modelora is a Flask-based web application that helps users explore datasets, prepare data, run machine-learning workflows, visualize results, and export outputs. It also includes user authentication and administrative features.

Table of Contents

• Features
• Technology Stack
• Project Structure
• Prerequisites
• Installation
• Environment Configuration
• Running the Application
• Deployment
• Troubleshooting
• Security
• Contributing
• License

Features

Dataset Management

• Upload and process supported tabular datasets.
• Explore built-in sample datasets.
• Inspect dataset quality and prepare data for analysis.
• Export processed datasets into supported formats.

Machine Learning

• Run supported machine-learning algorithms.
• Configure algorithm-specific parameters.
• Train models and evaluate results.
• Generate predictions and access experiment results.

The available algorithms are defined by the implementation in models/ml_pipeline.py. Refer to that file and the algorithm API for the exact supported algorithms.

Results and Export

• Export predictions as CSV files.
• Download processed datasets.
• Export available ARFF data.
• Download experiment summaries.
• Review recorded experiment history.

Authentication and Administration

• Email-based registration and login.
• Session management and authentication tokens.
• Login rate limiting and failed-login protection.
• Password-reset functionality.
• Administrative user management and system monitoring.

Web Interface

• Browser-based user interface.
• Interactive pages built with HTML, CSS, and JavaScript.
• Dedicated administration interface.
• API endpoints for dataset processing and machine-learning workflows.

Technology Stack

Component	Technologies
Backend	Python, Flask, Flask-CORS
Data processing	NumPy, Pandas, SciPy
Machine learning	scikit-learn, mlxtend
File processing	openpyxl, xlrd, pyarrow, lxml
Database	MongoDB through PyMongo
Frontend	HTML, CSS, JavaScript
Production server	Gunicorn
System monitoring	psutil

Project Structure

The repository contains a root-level application and an additional nested Modelora/ project directory. The following tree summarizes the root application and its main modules. Confirm individual filenames against the current repository when navigating files.

Modelora/
├── README.md
├── LICENSE
├── .gitignore
├── app.py
├── wsgi.py
├── config.py
├── gunicorn.conf.py
├── requirements.txt
│
├── api/
│   ├── __init__.py
│   ├── auth.py
│   ├── dataset.py
│   ├── ml_api.py
│   ├── export.py
│   ├── admin.py
│   └── utils.py
│
├── core/
│   ├── __init__.py
│   ├── analyzer.py
│   ├── arff_converter.py
│   └── preprocessor.py
│
├── models/
│   ├── __init__.py
│   └── ml_pipeline.py
│
├── db/
│   ├── __init__.py
│   ├── admin_store.py
│   ├── mongo_store.py
│   └── user_store.py
│
├── middleware/
│   ├── __init__.py
│   └── security.py
│
├── storage/
│   ├── __init__.py
│   └── file_store.py
│
├── templates/
│   ├── landing.html
│   ├── login.html
│   ├── dashboard.html
│   ├── splash.html
│   ├── admin.html
│   ├── admin_splash.html
│   └── maintenance.html
│
├── static/
│   ├── css/
│   │   ├── landing.css
│   │   ├── main.css
│   │   └── admin.css
│   ├── js/
│   │   ├── landing.js
│   │   ├── app.js
│   │   ├── admin.js
│   │   ├── algo_viz.js
│   │   ├── icons.js
│   │   ├── logo.js
│   │   └── telemetry.js
│   ├── img/
│   ├── favicon.svg
│   ├── robots.txt
│   └── sitemap.xml
│
├── arff/
├── processed/
├── exports/
├── cache/
├── logs/
├── uploads/
├── instance/
│
└── Modelora/
    ├── app.py
    ├── config.py
    ├── requirements.txt
    ├── api/
    ├── core/
    ├── db/
    ├── middleware/
    ├── models/
    ├── storage/
    ├── templates/
    ├── static/
    ├── arff/
    └── processed/

Module Responsibilities

Module	Responsibility
app.py	Flask application and route registration
api/	Authentication, dataset, ML, export, and admin endpoints
core/	Dataset analysis, preprocessing, and ARFF conversion
models/	Machine-learning pipeline and algorithm registry
db/	User, experiment, and administrative data access
middleware/	Security helpers, rate limiting, and access controls
storage/	Uploaded files, cached data, and generated exports
templates/	HTML templates
static/	CSS, JavaScript, and image assets
arff/	ARFF data files
processed/	Processed dataset files
exports/	Generated result files
cache/	Runtime cache data
logs/	Application logs

Important: Run commands from the repository root containing app.py and requirements.txt. The nested Modelora/ directory is an additional project copy; avoid mixing its files with the root application.

Runtime directories may be created automatically, and their contents can differ between local development and deployment.

Prerequisites

Install the following before setting up Modelora:

• Python 3.11 or newer recommended.
• Git.
• MongoDB for persistent MongoDB-backed features.
• SMTP credentials if password-reset email delivery is required.

Verify your Python installation:

python --version
python -m pip --version

On some Linux distributions and macOS systems, use python3 instead of python.

Installation

1. Clone the Repository

git clone https://github.com/vasan06/Modelora.git
cd Modelora

Confirm that app.py and requirements.txt exist in the current directory.

2. Create a Virtual Environment

Windows — PowerShell

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt

If PowerShell blocks activation, use Command Prompt:

.venv\Scripts\activate.bat
python -m pip install --upgrade pip
pip install -r requirements.txt

Linux / macOS

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

3. Verify Dependencies

python -m pip check

If dependencies fail to install, confirm the Python version and review the installation error before changing package versions.

Environment Configuration

The application's configuration is defined in config.py. Do not assume that a .env file is automatically loaded; configure environment variables directly in your shell or hosting platform unless dotenv loading is explicitly added.

Variable	Purpose
SECRET_KEY	Secret used to sign application tokens
MONGO_URI	MongoDB connection string
SMTP_HOST	Outgoing email server
SMTP_PORT	Outgoing email port
SMTP_USER	SMTP account username
SMTP_PASS	SMTP password or provider-approved app password
SMTP_FROM	Sender email address
DEBUG	Enables or disables debug mode
PORT	Development server port
WEB_CONCURRENCY	Gunicorn worker count
REQUEST_THREADS	Gunicorn threads per worker

The actual defaults are defined in config.py and gunicorn.conf.py. Configure production secrets explicitly rather than relying on development defaults.

Windows — PowerShell

$env:SECRET_KEY = python -c "import secrets; print(secrets.token_hex(32))"
$env:MONGO_URI = "mongodb://localhost:27017"
$env:DEBUG = "0"

Linux / macOS

export SECRET_KEY="$(python -c 'import secrets; print(secrets.token_hex(32))')"
export MONGO_URI="mongodb://localhost:27017"
export DEBUG=0

Replace the MongoDB URI with your own connection string when using a remote database.

For email-based password resets, configure the SMTP variables with valid credentials. Never commit real passwords, API keys, tokens, or database credentials to Git.

Running the Application

Development Server

Activate the virtual environment and configure the required environment variables, then run:

python app.py

If the application's configured port is 5000, open:

http://127.0.0.1:5000

The exact port and available page routes depend on the current configuration and registered routes.

Production-Style Server

The repository includes wsgi.py and gunicorn.conf.py for WSGI deployment on compatible environments.

gunicorn -c gunicorn.conf.py wsgi:app

Gunicorn's default bind address is configured in gunicorn.conf.py. Set the host and port appropriately for your environment.

Do not expose Flask's development server or enable debug mode on a public production deployment.

Deployment

Modelora can be deployed to a compatible Python hosting platform that supports Flask applications, Gunicorn, environment variables, and the application's storage requirements.

Deployment Checklist

1. Connect your GitHub repository to the selected hosting platform.

2. Set the application root to the directory containing the intended app.py and requirements.txt.

3. Install dependencies:

   pip install -r requirements.txt

4. Configure the start command:

   gunicorn -c gunicorn.conf.py wsgi:app

5. Set SECRET_KEY, MONGO_URI, and any required SMTP settings in the platform's environment configuration.

6. Set DEBUG=0.

7. Configure MongoDB credentials and network access securely.

8. Verify that required runtime directories are writable and persistent where necessary.

9. Test registration, login, dataset upload, model execution, and file exports after deployment.

10. Review application and hosting logs for startup errors.

The exact deployment configuration depends on the selected provider. Successful deployment should be confirmed by testing the live application rather than relying on a successful build alone.

Troubleshooting

Problem	Possible Solution
ModuleNotFoundError	Activate the correct virtual environment and install dependencies using python -m pip install -r requirements.txt.
Dependency installation fails	Check the Python version and the package installation error.
MongoDB connection warnings	Verify that MongoDB is running, the URI is correct, and credentials and network access are valid.
Login or session failures	Check the configured SECRET_KEY, token validity, and application logs.
Password-reset emails are not received	Verify SMTP credentials, sender address, port, and provider restrictions.
Dataset upload or processing fails	Check the file format, configured upload-size limit, available disk space, and logs.
Port is already in use	Configure a different development port or Gunicorn bind address.
Works locally but fails after deployment	Check the start command, working directory, environment variables, permissions, and Python dependencies.
Export file is missing	Run the relevant workflow first and confirm that generated files are available in the configured output directory.

Security

• Use a strong, randomly generated SECRET_KEY.
• Never commit database passwords, SMTP credentials, or other secrets.
• Keep debug mode disabled in production.
• Use HTTPS for public deployments.
• Restrict database network access and use a database account with only the required permissions.
• Review administrator-role assignment and account-management behavior before exposing the application publicly.
• Protect uploaded datasets and exported results from unauthorized access.
• Define retention and backup policies for runtime data and logs.
• Avoid including sensitive information in logs, screenshots, bug reports, and commits.

Contributing

Contributions and improvements are welcome.

1. Fork the repository.
2. Create a branch for your change.
3. Keep changes focused on a specific feature or issue.
4. Test the affected workflows locally.
5. Document relevant configuration changes.
6. Submit a pull request with a clear description and testing steps.

Do not include credentials, private datasets, generated exports containing sensitive information, or other secrets in pull requests.

License

This project is distributed under the MIT License. Refer to the repository's LICENSE file for the complete license terms.

---

Modelora — Learn, Experiment, and Visualize Machine Learning.