# PointPitStop 🏎️💨
> An Enterprise-Grade B2B2C Multi-Tenant Fleet Safety & Incentive Management Platform.
> currently live on : https://pitpointstop.onrender.com

[![Python Version](https://img.shields.io/badge/Python-3.10%2B-blue?style=flat-square&logo=python)](https://www.python.org/)
[![Framework](https://img.shields.io/badge/Framework-Flask%20%7C%20SQLAlchemy-red?style=flat-square&logo=flask)](https://flask.palletsprojects.com/)
[![Deployment Stack](https://img.shields.io/badge/Deployment-Render%20%7C%20PostgreSQL-002d5a?style=flat-square&logo=render)](https://render.com)

---

## 📋 Project Overview

**PointPitStop** is a multi-tenant corporate driver incentive software solution designed to gamify safe driving habits, improve fleet retention, and streamline safety operations for logistics, distribution, and freight transit firms.

The application allows independent commercial logistics companies (**Sponsors**) to define customized performance rules, ingest safety telematics data, and manage custom distribution catalogs. Commercial **Drivers** apply to sponsors, track their safe-driving milestones, and redeem their accumulated points directly for physical merchandise. The entire lifecycle is monitored via rigid system-level metrics by **Admins**.

---

## 🛠️ Key Architectural Features

* **Rigid Multi-Tenant Access Control (RBAC):** Restricts data workspaces dynamically across three distinct application profiles using customized Flask session middleware structures:
  * 👤 **Drivers:** Apply for multi-corporate sponsorships, track points history ledgers, and check out catalog rewards.
  * 🏢 **Sponsors:** Configure points-to-dollar conversion matrices, approve or reject driver requests, and run bulk data seeds.
  * ⚙️ **Administrators:** Oversee global entity linking, manage system audit logs, and override cross-tenant operational data.
* **Transactional Ledger Safety:** Utilizes structured intermediate mapping layers (`DriverCompanyLink`) and transaction isolation parameters (`db.session.flush()`) to calculate points history changes dynamically without transaction collision risk.
* **Granular Audit Compliance Tracking:** Implements an un-alterable backend logging pipeline (`log_audit_event`) that captures critical system actions—such as account generation, security failures, and administrative point modifications—supporting enterprise accountability standards.
* **Recruiter Staging Sandbox (Demo Mode):** Features an isolated database routine that safely clears out existing runtime states, builds pristine mock schema tables from scratch, and auto-populates relational link history arrays for instantaneous evaluation.

---

## 💻 Tech Stack & Dependencies

* **Backend Engine:** Python 3.10+, Flask (Micro-framework layout design)
* **Object Relational Mapping (ORM):** Flask-SQLAlchemy (PostgreSQL / SQLite backends)
* **Database Migrations:** Flask-Migrate (Alembic engine)
* **Session & Identity Management:** Flask-Login
* **Frontend Implementation:** Modular HTML5 templates styled with scoped CSS injection elements to safeguard global component layouts.

---

## 📂 Repository Architecture Snippet

```text
├── env/                      # Virtual environment isolation trees
├── routes/                   # Role-Based Access Control routing blueprints
│   ├── admin.py              # System administrator business logic
│   ├── driver.py             # Driver profile, application & catalog engines
│   └── sponsor.py            # Corporate fleet setup, conversions & reporting
├── static/                   # Global style vectors and asset resources
├── templates/                # Modular HTML view templates
│   ├── auth/                 # Core security, signup & password recovery screens
│   ├── demo/                 # Sandbox selector terminal UI panels
│   └── base.html             # The master structural layout controller
├── app.py                    # Global application intercept, configuration & initialization
├── audit.py                  # Immutable compliance log engine
├── authentication.py         # Sign-in security and session validation workflows
├── demo.py                   # Isolated testing seed automation routines
├── models.py                 # Core database entity schemas and relational maps
└── requirements.txt          # Target production dependency manifests

---

## 🚀 Future Roadmap Milestones

* **Reformatting & Cleaning:** Reformatting to React and deleting all files that are obselete
* **Global UI/UX Cohesion:** Consolidating legacy front-end view fragments into an integrated, unified design layout matching crisp client criteria.
* **Custom Third-Party API Catalogs:** Upgrading the procurement module to empower Sponsors to directly hook their inventory screens to live e-commerce vendor API feeds.
* **Asynchronous Application Management:** Rolling out interactive cancellation triggers to allow driving accounts to seamlessly rescind pending company applications.
* **Multi-Factor Authentication (2FA):** Enhancing root security protocols by enforcing TOTP two-factor setups for admin profiles.

---

## 🛠️ Known Deployment Notes

* **Render Cloud Migration Catalog Faulty:** Catalog is not presistent across session. 

---

## 👥 Meet Team #12 (Clemson CPSC 4910)

This platform was developed as part of a collaborative capstone project at Clemson University. Below is our team structure:

* **Karina** - *Lead Full-Stack / Backend & Database Engineer*
  * Engineered the global application runtime configuration hooks, database schema relational matrices, point tracking history transactional logic, and built the framework.
* **John** - *Catalog & Support*
  * Handled support system, frontend and backend catalog, and coordinated reporting templates.
* **Ian** - *Reporting*
  * Developed reporting framework, coordinated reporting templates, and invoice rendering setups.