{"id":47610638,"url":"https://github.com/giuliorossetti/superviseme","last_synced_at":"2026-04-01T20:02:33.417Z","repository":{"id":339412906,"uuid":"1022620801","full_name":"GiulioRossetti/SuperviseMe","owner":"GiulioRossetti","description":"SuperviseMe is a thesis supervision tool","archived":false,"fork":false,"pushed_at":"2026-02-19T15:00:54.000Z","size":7848,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-19T18:46:29.442Z","etag":null,"topics":["student-management-system","student-supervision","thesis-support","webapp"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GiulioRossetti.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-19T13:19:27.000Z","updated_at":"2026-02-19T15:01:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/GiulioRossetti/SuperviseMe","commit_stats":null,"previous_names":["giuliorossetti/superviseme"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/GiulioRossetti/SuperviseMe","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GiulioRossetti%2FSuperviseMe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GiulioRossetti%2FSuperviseMe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GiulioRossetti%2FSuperviseMe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GiulioRossetti%2FSuperviseMe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GiulioRossetti","download_url":"https://codeload.github.com/GiulioRossetti/SuperviseMe/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GiulioRossetti%2FSuperviseMe/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291344,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["student-management-system","student-supervision","thesis-support","webapp"],"created_at":"2026-04-01T20:02:29.883Z","updated_at":"2026-04-01T20:02:33.372Z","avatar_url":"https://github.com/GiulioRossetti.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SuperviseMe\n\nA comprehensive web application for thesis supervision and research project management in academic environments. SuperviseMe streamlines the process of thesis supervision by providing dedicated dashboards for administrators, supervisors, researchers, and students, along with robust user management and project tracking capabilities.\n\n📘 **[Read the Full Documentation](https://giuliorossetti.github.io/SuperviseMe/)**\n\n## 🎯 Project Overview\n\nSuperviseMe is a Flask-based web application designed to facilitate thesis supervision and research collaboration in universities and academic institutions. The platform provides role-based access control with distinct interfaces for administrators, supervisors, researchers, and students, each tailored to their specific needs and responsibilities.\n\n## ✨ Key Features\n\n### 🔐 Authentication \u0026 Authorization\n- **Secure Login System**: Email-based authentication with password hashing using PBKDF2-SHA256\n- **Role-Based Access Control**: Separate dashboards and permissions for admins, supervisors, researchers, and students\n- **Session Management**: Secure session handling with remember-me functionality\n- **Logout Protection**: Proper session cleanup and redirect handling\n\n### 👨‍💼 Administrator Features\n- **User Management**: Complete CRUD operations for all user types (admins, supervisors, researchers, students)\n- **System Dashboard**: Real-time statistics showing user counts and thesis distribution\n- **Thesis Overview**: Comprehensive view of all assigned and available theses\n- **Research Project Monitoring**: Overview of research projects and collaborations\n- **Supervisor Role Management**: Grant and revoke supervisor privileges to researchers\n- **Email Notification Management**: Configure and manage weekly supervisor email reports\n- **Activity Monitoring**: Track user activity across the platform\n- **Scheduler Management**: Monitor and control background task scheduling\n- **Email Testing**: Preview and test weekly notification emails before sending\n- **Data Export**: JSON and CSV export capabilities for system data\n- **System Health Monitoring**: Built-in health checks and system diagnostics\n\n### 🔬 Researcher Features (NEW!)\n- **Research Project Management**: Create, update, and delete research projects\n- **Collaboration System**: Invite other researchers as collaborators with different roles\n- **Project Dashboard**: Overview of personal research projects and statistics\n- **Dual Role Support**: Access supervisor functions when granted supervisor privileges\n- **Collaborative Workspace**: Share projects with team members and manage permissions\n- **Progress Tracking**: Monitor research project milestones and activities\n\n### 👨‍🏫 Supervisor Features\n- **Student Management**: View and manage supervised students with activity tracking\n- **Thesis Supervision**: Track thesis progress and provide feedback\n- **Resource Sharing**: Upload and manage thesis-related resources\n- **Progress Monitoring**: Track student updates and milestones\n- **Weekly Email Reports**: Automatic Monday morning activity summaries for all supervised students\n- **Activity Status Indicators**: Visual indicators for active/inactive students with last activity locations\n- **Inactive Student Alerts**: Clear highlighting of students inactive for more than 2 weeks\n- **Profile Management**: Update personal information and preferences\n\n### 👨‍🎓 Student Features\n- **Personal Dashboard**: Overview of thesis status and recent activities\n- **Thesis Details**: View thesis description, requirements, and supervisor information\n- **Progress Tracking**: Submit updates and track thesis milestones\n- **Resource Access**: Download supervisor-provided resources and materials\n- **Profile Management**: Update personal information and account settings\n\n## 📧 Notification System\n\nSuperviseMe includes comprehensive notification systems to keep users informed about thesis activities and important updates.\n\n### 🔔 Telegram Notifications (NEW!)\n\nReal-time notifications delivered directly to your Telegram account:\n\n- **Instant Delivery**: Immediate notifications for urgent activities\n- **Customizable Types**: Choose which notifications to receive via Telegram\n- **Rich Formatting**: Formatted messages with emojis and action links\n- **Secure Setup**: Verified user identification prevents impersonation\n- **Multi-Channel**: Works alongside email notifications\n\n**Available Notification Types:**\n- 📝 New thesis updates from students\n- 💬 Supervisor feedback and comments\n- ✅ Task assignments and completions\n- 📊 Thesis status changes\n- ⏰ Deadline reminders\n- 📈 Weekly activity summaries\n\nSee [docs/telegram_setup_detailed.md](docs/telegram_setup_detailed.md) for detailed setup instructions.\n\n### 📧 Weekly Email System\n\nAutomated weekly email reports for supervisors:\n\n- **Automated Schedule**: Weekly reports are automatically sent every Monday morning at 9:00 AM\n- **Activity Summary**: Each supervisor receives a detailed summary of all supervised students' weekly activities\n- **Inactive Student Alerts**: Students who have been inactive for more than 2 weeks are clearly highlighted\n- **Last Activity Tracking**: Shows where students were last active on the platform (e.g., \"student_dashboard\", \"posting_thesis_update\")\n- **Update Statistics**: Number of thesis updates posted by each student during the past week\n- **Professional Templates**: Clean, easy-to-read email format with structured information\n\n### 📊 Activity Monitoring\n\nThe system continuously tracks student engagement:\n- **Login Activity**: Records when students access their dashboards\n- **Update Posts**: Tracks when students post thesis progress updates\n- **Platform Interaction**: Monitors various forms of student engagement\n- **Location Tracking**: Records which part of the platform students were using\n\n### ⚙️ Administrative Control\n\nAdministrators have full control over the email notification system:\n- **Scheduler Status**: Monitor the background task scheduler status\n- **Email Testing**: Preview weekly reports for any supervisor before sending\n- **Manual Triggers**: Send weekly reports immediately for testing purposes\n- **Schedule Management**: Monitor next run times and job configurations\n\n### 🎯 Benefits\n\n- **Proactive Supervision**: Supervisors are automatically notified of inactive students\n- **Improved Communication**: Regular updates keep everyone informed\n- **Early Intervention**: Identify struggling students before issues become critical\n- **Professional Workflow**: Automated system reduces manual oversight burden\n\n### 🗄️ Data Management\n- **SQLite Database**: Lightweight, file-based database for development and small deployments\n- **PostgreSQL Support**: Enterprise-grade database support for production environments\n- **Sample Data**: Pre-configured sample users and theses for testing and demonstration\n- **Data Integrity**: Proper foreign key relationships and cascade operations\n\n## 🚀 Installation \u0026 Setup\n\n### Quick Start (Local Development)\n\n#### Prerequisites\n- Python 3.8+\n- pip (Python package installer)\n- (Optional) PostgreSQL for production deployment\n\n#### Local Installation\n\n1. **Clone the repository**\n```bash\ngit clone https://github.com/GiulioRossetti/SuperviseMe.git\ncd SuperviseMe\n```\n\n2. **Install dependencies**\n```bash\npip install -r requirements.txt\n```\n\n3. **(Optional) Configure seed passwords**\n```bash\nexport ADMIN_BOOTSTRAP_PASSWORD=change-me-admin\nexport SEED_DEFAULT_PASSWORD=change-me-seed\n# Or set role-specific values:\n# export SEED_SUPERVISOR_PASSWORD=...\n# export SEED_STUDENT_PASSWORD=...\n# export SEED_RESEARCHER_PASSWORD=...\n```\n\n4. **Initialize the database with sample data**\n```bash\npython scripts/seed_database.py\n```\n\n5. **Run database migrations (for existing installations)**\n```bash\n# If upgrading from a previous version, run migrations to add new features\npython scripts/migrate_database.py      # For activity tracking\npython scripts/migrate_telegram.py      # For Telegram notifications (NEW!)\npython scripts/migrate_researcher.py    # For researcher role and research projects (NEW!)\n```\n\n6. **Configure Telegram notifications (optional)**\n   - See [docs/telegram_setup_detailed.md](docs/telegram_setup_detailed.md) for detailed setup instructions\n   - Create a Telegram bot via @BotFather\n   - Configure bot settings in the admin panel\n\n7. **Start the application**\n```bash\npython superviseme.py\n```\n\n8. **Access the application**\nOpen your web browser and navigate to `http://localhost:8080`\n\n### 🐳 Docker Setup (Recommended)\n\nFor a complete production-ready setup with database persistence, SSL, and mail server:\n\n#### Prerequisites\n- Docker and Docker Compose installed on your system\n\n#### Quick Start with Docker\n\n1. **Clone and navigate to the repository**:\n   ```bash\n   git clone https://github.com/GiulioRossetti/SuperviseMe.git\n   cd SuperviseMe\n   ```\n\n2. **Create environment configuration**:\n   ```bash\n   cp .env.example .env\n   ```\n   Edit `.env` and customize the values, especially:\n   - `SECRET_KEY`: Use a strong, unique secret key\n   - `ADMIN_BOOTSTRAP_PASSWORD`: Set a strong admin bootstrap password\n   - `PG_PASSWORD`: Set a secure database password\n\n3. **Provide TLS files for Nginx**:\n   - Place certificate and key files in `nginx/ssl/`:\n     - `superviseme.crt`\n     - `superviseme.key`\n\n4. **Start the application**:\n   ```bash\n   docker-compose up -d\n   ```\n\n5. **Access the application**:\n   - Main application: https://localhost\n   - Mail server UI: http://localhost:8025\n\n#### Docker Architecture\n\nThe Docker setup includes:\n- **superviseme_app**: Flask application running with Gunicorn\n- **postgres**: PostgreSQL database with persistent storage\n- **nginx**: Reverse proxy with SSL termination and static file serving\n- **mailhog**: Development mail server for testing email functionality\n\n#### Development Mode with Docker\n\nFor development with hot reloading:\n\n```bash\ndocker-compose -f docker-compose.yml -f docker-compose.dev.yml up\n```\n\nDevelopment features:\n- Flask development server with auto-reload\n- Source code volume mounting\n- Debug mode enabled\n- Direct access to application on port 8080\n\n#### Data Persistence\n\n**Database Data**\n- Volume: `postgres_data`\n- Backup: `docker-compose exec postgres pg_dump -U superviseme_user superviseme \u003e backup.sql`\n\n**Application Data**\n- Volume: `app_data`\n- Purpose: Persistent storage for SQLite fallback and file uploads\n\nFor detailed Docker setup instructions, see [docs/docker_readme.md](docs/docker_readme.md).\n\n### Advanced Configuration\n\n#### Database Configuration\n\n**SQLite (Default - Development)**\n```bash\npython superviseme.py --db sqlite\n```\n\n**PostgreSQL (Production)**\n```bash\n# Set environment variables\nexport PG_USER=your_username\nexport PG_PASSWORD=your_password  \nexport PG_HOST=localhost\nexport PG_PORT=5432\nexport PG_DBNAME=superviseme\n\n# Run with PostgreSQL\npython superviseme.py --db postgresql\n```\n\n#### Command Line Options\n```bash\npython superviseme.py --help\n\nOptions:\n  -x, --host TEXT        Host address to run the app on (default: localhost)\n  -y, --port TEXT        Port to run the app on (default: 8080)\n  -d, --debug           Enable debug mode\n  -D, --db [sqlite|postgresql]  Database type (default: sqlite)\n```\n\n## 👥 Sample Data \u0026 Test Credentials\n\nThe application comes pre-configured with sample data for immediate testing and demonstration:\n\n### 🔑 Test Login Credentials\n\nPassword values depend on your environment configuration:\n- `ADMIN_BOOTSTRAP_PASSWORD` for admin bootstrap user\n- `SEED_SUPERVISOR_PASSWORD` / `SEED_STUDENT_PASSWORD` / `SEED_RESEARCHER_PASSWORD`\n- If role-specific seed password is not set, `SEED_DEFAULT_PASSWORD` is used\n- If none are set, seed script falls back to `test` (development fallback only)\n\n#### Administrator Account\n- **Email**: `admin@supervise.me`\n- **Password**: value from `ADMIN_BOOTSTRAP_PASSWORD`\n- **Role**: System Administrator\n- **Access**: Full system access, user management, system statistics\n\n#### Supervisor Accounts\n- **Email**: `j.smith@university.edu`\n- **Email**: `e.johnson@university.edu`  \n- **Email**: `m.garcia@university.edu`\n- **Password**: `SEED_SUPERVISOR_PASSWORD` (or `SEED_DEFAULT_PASSWORD`)\n- **Role**: Thesis Supervisors\n- **Access**: Student supervision, thesis management, resource sharing\n\n#### Researcher Accounts (NEW!)\n- **Email**: `alice.johnson@university.edu`\n  - **Special Role**: Also has supervisor privileges\n  - **Access**: Research project management + thesis supervision\n- **Email**: `bob.williams@university.edu`\n  - **Role**: Researcher only\n  - **Access**: Research project management and collaboration\n- **Email**: `maria.rodriguez@university.edu`\n  - **Special Role**: Also has supervisor privileges\n  - **Access**: Research project management + thesis supervision\n- **Password**: `SEED_RESEARCHER_PASSWORD` (or `SEED_DEFAULT_PASSWORD`)\n\n#### Student Accounts\n- **Email**: `alice.doe@student.university.edu`\n- **Email**: `bob.wilson@student.university.edu`\n- **Email**: `carol.brown@student.university.edu`\n- **Email**: `david.miller@student.university.edu`\n- **Email**: `eva.clark@student.university.edu`\n- **Password**: `SEED_STUDENT_PASSWORD` (or `SEED_DEFAULT_PASSWORD`)\n- **Role**: Students\n- **Access**: Personal dashboard, thesis tracking, progress updates\n\n### 📊 Sample Theses Data\n\nThe system includes 7 sample theses across different academic levels:\n\n#### Assigned Theses (5)\n1. **Machine Learning for Predictive Analytics in Healthcare** (Alice Doe - Master's)\n2. **Deep Learning Approaches for Natural Language Processing** (Bob Wilson - Bachelor's)\n3. **Computer Vision for Autonomous Vehicle Navigation** (David Miller - Master's)\n4. **Quantum Computing Applications in Cryptography** (Eva Clark - Bachelor's)\n5. **Blockchain Technology in Supply Chain Management** (Carol Brown - Master's)\n\n#### Available Theses (2)\n1. **IoT Security Framework for Smart Cities** (Other level)\n2. **AI-Driven Personalized Learning Systems** (Bachelor's level)\n\n### 🔬 Sample Research Projects Data (NEW!)\n\nThe system includes 4 sample research projects with collaborations:\n\n#### Research Projects\n1. **Machine Learning for Climate Prediction** (Dr. Alice Johnson - Research level)\n   - **Collaborator**: Dr. Bob Williams (Co-investigator)\n2. **Social Network Analysis in Online Communities** (Dr. Bob Williams - Full-scale)\n   - **Collaborator**: Dr. Maria Rodriguez (Collaborator)\n3. **Ethics in Artificial Intelligence Systems** (Dr. Maria Rodriguez - Longitudinal)\n   - **Collaborator**: Dr. Alice Johnson (Advisor)\n4. **Quantum Computing Applications in Healthcare** (Dr. Alice Johnson - Pilot)\n\n#### Collaboration Features\n- **Role-Based Collaboration**: Different collaboration roles (collaborator, co-investigator, advisor)\n- **Cross-Project Collaboration**: Researchers can collaborate on multiple projects\n- **Access Control**: Project owners can add/remove collaborators\n\n## 📱 User Interface Screenshots\n\n### 🔐 Login Interface\n![Login Page](https://github.com/user-attachments/assets/14d6b4b7-6a67-4c0c-91fa-0020c9927aff)\n\nThe login page features a clean, modern design with:\n- Email and password authentication\n- Remember me functionality\n- Responsive layout that adapts to different screen sizes\n- Clear error messaging for failed login attempts\n\n### 👨‍💼 Administrator Dashboard\n![Admin Dashboard with Researchers](docs/assets/images/admin-dashboard-with-researchers.png)\n\nThe administrator dashboard provides:\n- **System Statistics**: Real-time counts of admins, supervisors, researchers, students, and theses\n- **Assigned Theses Table**: Complete overview of all active thesis assignments\n- **Available Theses Table**: List of theses available for assignment\n- **Navigation Menu**: Quick access to user management, thesis management, and system tools\n\n### 👨‍💼 Administrator User Management\n![Admin Users with Researchers](docs/assets/images/admin-users-with-researchers.png)\n\nThe user management interface shows:\n- **Complete User List**: All users across different roles including researchers\n- **Role-Based Filtering**: Easy identification of different user types\n- **Create User Form**: Includes researcher role option in the dropdown\n- **User Actions**: Direct access to user details and deletion functions\n\n### 🔬 Researcher Dashboard (With Supervisor Access)\n*Screenshot showing researcher dashboard with both research projects and supervisor access panel*\n\nThe researcher dashboard features:\n- **Research Project Statistics**: Overview of personal research projects\n- **Supervised Theses Count**: Shows supervised theses when user has supervisor privileges\n- **Recent Projects Table**: Quick access to research projects with status and collaboration info\n- **Dual Navigation**: Both research and supervision menu sections when applicable\n- **Supervisor Functions**: Quick access panel to supervisor tools when privileges are granted\n\n### 🔬 Researcher Project Management\n*Screenshot showing research project management interface with collaborations*\n\nThe research project management interface provides:\n- **Project Overview Table**: Complete list of research projects with descriptions, levels, and collaborators\n- **Collaboration Status**: Visual indicators showing project collaborators and their roles\n- **Project Actions**: Edit, delete, and view options for each project\n- **Create Project Modal**: Easy project creation with title, description, and level selection\n- **Collaborator Management**: Add/remove collaborators with different role assignments\n\n### 🔬 Researcher Dashboard (Researcher Only)\n*Screenshot showing researcher dashboard without supervisor privileges*\n\nFor researchers without supervisor privileges:\n- **Research-Focused Interface**: Clean dashboard focusing on research activities\n- **Project Statistics**: Personal research project metrics and collaboration counts\n- **Simplified Navigation**: Research-only menu without supervisor functions\n- **Collaboration Overview**: Shows projects where user is a collaborator\n\n### 👨‍🎓 Student Dashboard\n![Student Dashboard](https://github.com/user-attachments/assets/2fa0923e-7984-4251-8449-023be3643757)\n\nThe student dashboard features:\n- **Personal Statistics**: Overview of updates, feedback, resources, and thesis status\n- **My Thesis Section**: Detailed view of assigned thesis with description and metadata\n- **Recent Updates Section**: Timeline of thesis progress and activities\n- **Navigation Menu**: Access to thesis details, progress tracking, and profile management\n\n### 🔓 Logout Functionality\n![Logout Redirect](https://github.com/user-attachments/assets/42e154f8-f4a1-471f-b6fd-20ba5fa2fead)\n\nSecure logout implementation:\n- Proper session cleanup and termination\n- Automatic redirect to login page\n- Clean interface return for new login attempts\n\n## 🏗️ Technical Architecture\n\n### Backend Framework\n- **Flask**: Lightweight and flexible Python web framework\n- **Flask-SQLAlchemy**: ORM for database operations\n- **Flask-Login**: User session management and authentication\n- **Flask-Mail**: Email functionality for weekly notifications\n- **APScheduler**: Background task scheduling for automated emails\n- **Werkzeug**: Password hashing and security utilities\n\n### Database Schema\n- **Users**: Administrators, supervisors, researchers, and students with role-based permissions and activity tracking\n- **Theses**: Thesis information, descriptions, and metadata  \n- **Thesis-Supervisor Relationships**: Many-to-many relationships between theses and supervisors\n- **Thesis Status**: Current status tracking (Active, Completed, etc.)\n- **Thesis Tags**: Categorization and organization system\n- **Research Projects**: Research project information, descriptions, and researcher ownership\n- **Research Collaborations**: Many-to-many relationships between research projects and collaborating researchers\n- **Supervisor Roles**: Role grants allowing researchers to access supervisor functions\n- **Activity Tracking**: User activity monitoring with timestamps and location tracking\n\n### Frontend Technologies\n- **HTML5/CSS3**: Modern, semantic markup and responsive styling\n- **Bootstrap**: Responsive grid system and UI components\n- **JavaScript**: Interactive features and AJAX functionality\n- **Font Awesome**: Icon system for intuitive navigation\n\n### Security Features\n- **Password Hashing**: PBKDF2-SHA256 encryption for user passwords\n- **Session Management**: Secure Flask sessions with CSRF protection\n- **Input Validation**: Server-side validation for all user inputs\n- **Role-Based Authorization**: Route-level access control based on user roles\n\n## 🔧 Development Features\n\n### Database Management\n```bash\n# Initialize fresh database with all sample data (including researchers)\npython scripts/seed_database.py\n\n# The seed script will:\n# - Clear existing data\n# - Create admin, supervisor, researcher, and student accounts\n# - Generate sample theses and relationships\n# - Create sample research projects and collaborations\n# - Grant supervisor roles to selected researchers\n# - Set up proper foreign key constraints\n```\n\n### Local Quality Gates\n```bash\n# Run lint + compile + schema alignment + tests\nmake ci\n\n# Run smoke checks against a local server process\nmake smoke\n```\n\n### Migration Scripts\nFor existing installations, run these migration scripts in order:\n```bash\n# Core system migrations\npython scripts/migrate_database.py      # For activity tracking\npython scripts/migrate_telegram.py      # For Telegram notifications\npython scripts/migrate_researcher.py    # For researcher role and research projects (NEW!)\n\n# The researcher migration will:\n# - Add researcher user accounts\n# - Create research project and collaboration tables\n# - Set up supervisor role management\n# - Add sample research data for testing\n```\n\n### API Endpoints\nThe application includes several API endpoints for data access:\n- `/admin/api/system_stats` - System statistics and metrics\n- `/admin/api/export_data` - JSON export of system data\n- `/admin/api/export_data/csv` - CSV export with ZIP delivery\n\n### Debugging and Development\n- **Debug Mode**: Detailed error messages and auto-reload functionality\n- **Logging**: Comprehensive logging for troubleshooting\n- **Sample Data**: Pre-configured test environment for development\n\n## 🚀 Production Deployment\n\n### Environment Variables\n```bash\nexport FLASK_ENV=production\nexport SECRET_KEY=your-secret-key-here\nexport ADMIN_BOOTSTRAP_PASSWORD=your-bootstrap-password\nexport ENABLE_SCHEDULER=false\nexport SKIP_DB_SEED=true\n\n# Database Configuration\nexport PG_USER=your_db_user\nexport PG_PASSWORD=your_db_password\nexport PG_HOST=your_db_host\nexport PG_PORT=5432\nexport PG_DBNAME=superviseme_production\n\n# Email Configuration (required for weekly notifications)\nexport MAIL_SERVER=smtp.gmail.com\nexport MAIL_PORT=587\nexport MAIL_USE_TLS=true\nexport MAIL_USE_SSL=false\nexport MAIL_USERNAME=your-email@gmail.com\nexport MAIL_PASSWORD=your-app-password\nexport MAIL_DEFAULT_SENDER=your-email@gmail.com\n```\n\n### Deployment Operations\n- Use `ENABLE_SCHEDULER=true` in exactly one scheduler worker/service only.\n- Keep all web replicas on `ENABLE_SCHEDULER=false`.\n- Follow the full operational checklist in `docs/deployment_runbook_detailed.md`.\n\n### CI Quality Gates\nCI runs on push and pull request with:\n- `ruff` runtime-safety lint rules\n- Python compile checks\n- Schema alignment verification (`scripts/check_schema_alignment.py`)\n- Automated tests (`pytest`)\n\n### WSGI Configuration\nFor production deployment with gunicorn or similar WSGI servers:\n```bash\npip install gunicorn\ngunicorn -w 4 -b 0.0.0.0:8000 superviseme:app\n```\n\n## 📁 Project Structure\n\n```\nSuperviseMe/\n├── superviseme/                 # Main application package\n│   ├── __init__.py             # Application factory and configuration\n│   ├── models.py               # Database models and relationships\n│   ├── routes/                 # Route handlers organized by functionality\n│   │   ├── auth.py             # Authentication routes (login/logout)\n│   │   ├── admin.py            # Administrator dashboard and management\n│   │   ├── supervisor.py       # Supervisor dashboard and tools  \n│   │   ├── researcher.py       # Researcher dashboard and project management (NEW!)\n│   │   ├── student.py          # Student dashboard and features\n│   │   └── profile.py          # User profile management\n│   ├── templates/              # Jinja2 HTML templates\n│   │   ├── login.html          # Authentication interface\n│   │   ├── admin/              # Administrator interface templates\n│   │   ├── supervisor/         # Supervisor interface templates\n│   │   ├── researcher/         # Researcher interface templates (NEW!)\n│   │   └── student/            # Student interface templates\n│   ├── static/                 # Static assets (CSS, JS, images)\n│   │   └── assets/             # Bootstrap and custom assets\n│   └── utils/                  # Utility functions and helpers\n├── data_schema/                # Database schema and initialization\n├── scripts/\n│   ├── seed_database.py        # Sample data generation script (enhanced with researchers)\n│   ├── check_schema_alignment.py # Schema vs models consistency check\n│   └── migrate_researcher.py   # Migration script for researcher functionality (NEW!)\n├── docs/                       # Documentation and Reference Materials\n│   └── deployment_runbook_detailed.md # Production rollout/rollback/smoke procedures\n├── Makefile                    # Local CI/smoke command shortcuts\n├── superviseme.py              # Application entry point\n├── requirements.txt            # Python dependencies\n└── README.md                   # This documentation\n```\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.\n\n## 🙋‍♂️ Support\n\nFor questions, issues, or contributions, please:\n- Open an issue on GitHub\n- Contact the development team\n- Review the documentation and sample configurations\n\n---\n\n**SuperviseMe** - Streamlining thesis supervision and research collaboration for the modern academic environment.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiuliorossetti%2Fsuperviseme","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgiuliorossetti%2Fsuperviseme","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiuliorossetti%2Fsuperviseme/lists"}