MAD2-PROJECT

A fullstack web application with a Flask backend and a Vue.js frontend for Parking Management System.

NOTE:

README.md created with help of AI

Project Structure

mad2-project/ backend/ # Flask backend code frontend/ # Vue.js frontend code README.md # Project overview and instructions .gitignore

---

Prerequisites

• Python 3.8+
• Node.js 16+
• Redis Server
• SQLite (included with Python)
• Mailhog (for capturing outbound emails locally)

---

Backend (Flask)

• Location: backend/
• Main file: backend/app.py

Setup

1. Go to the backend folder:

   cd backend

2. (Recommended) Create a virtual environment:

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

4. Install and start Redis:

   • macOS (using Homebrew):

     brew install redis
     brew services start redis

   • Linux (Ubuntu/Debian):

     sudo apt-get install redis-server
     sudo systemctl start redis

   • Windows: Download and install Redis from https://redis.io/download Or use WSL (Windows Subsystem for Linux)

5. (Optional) Run Mailhog so that reminder/report/export emails are captured locally:

   mailhog

   • SMTP input: 127.0.0.1:1025
   • Web UI (where you actually read the emails): http://127.0.0.1:8025

6. Run the backend server:

   python app.py

7. (Optional) Run Celery worker in a separate terminal:

   cd backend
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   celery -A app worker --loglevel=info

8. (Optional) Run Celery beat scheduler in a separate terminal (for scheduled tasks):

   cd backend
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   celery -A app beat --loglevel=info

Backend Features

• Authentication: JWT-based authentication with role-based access control (RBAC)
• Database: SQLAlchemy with SQLite
• Caching: Redis caching with expiry for frequently accessed data
• Background Jobs: Celery for scheduled and user-triggered tasks
  • Monthly user tracking reports (scheduled)
  • User parking details reports (user-triggered)
• Email Delivery: Mailhog-powered SMTP so daily reminders, monthly HTML reports, and CSV export alerts are visible locally
• API Endpoints: RESTful API with comprehensive CRUD operations

Admin User

Default admin credentials (created automatically):

• Email: admin@example.com
• Password: admin

---

Frontend (Vue.js)

• Location: frontend/
• Main file: frontend/src/App.vue

Setup

1. Go to the frontend folder:

   cd frontend

2. Install dependencies:

   npm install

3. Run the development server:

   npm run dev

Frontend Features

• Framework: Vue.js 3 with Composition API
• Routing: Vue Router for navigation
• State Management: Pinia for authentication state
• HTTP Client: Axios for API calls
• Charts: Chart.js for data visualization
• UI: Modern, responsive design with gradient themes

---

Running the Application

Step 1: Start Redis

Make sure Redis is running on localhost:6379

Step 2: Start Backend

cd backend
source venv/bin/activate  # On Windows: venv\Scripts\activate
python app.py

Backend will run on http://localhost:8080

Step 3: Start Frontend

cd frontend
npm run dev

Frontend will run on http://localhost:5173 (or another port if 5173 is busy)

Step 4: (Optional) Start Celery Workers

For background job processing:

Terminal 1 - Celery Worker:

cd backend
source venv/bin/activate
celery -A app worker --loglevel=info

Terminal 2 - Celery Beat (Scheduler):

cd backend
source venv/bin/activate
celery -A app beat --loglevel=info

---

Features

User Features

• User registration and login
• View available parking lots
• Search parking lots by location, name, or PIN code
• Book parking spots
• View personal dashboard with statistics
• View parking analytics with charts
• Release occupied spots
• Generate parking reports (user-triggered jobs)
• Dedicated analytics/history page with tabular view
• Configure reminder & report preferences (time/channel)
• Export entire history as CSV (async job + email link)

Admin Features

• Admin dashboard with system overview
• Create, edit, and delete parking lots
• Manage parking spots (view, edit, delete)
• Dedicated “view all” lots page with utilization summaries
• Parking records page with global search & duration/cost stats
• View all users and their reservations
• Search functionality for users and lots
• View statistics and analytics with charts (includes earnings per lot)
• Force release occupied spots
• Daily reminders + monthly HTML reports for all users (scheduled jobs)
• Trigger on-demand admin system report (email + analytics snapshot)

Technical Features

• JWT token-based authentication
• Role-based access control (RBAC)
• Redis caching with expiry
• Celery for background jobs
• Scheduled tasks (monthly reports)
• User-triggered jobs (parking reports)
• RESTful API design
• Responsive UI design
• Data visualization with charts

---

API Endpoints

Authentication

• POST /api/register - User registration
• POST /api/login - User login
• POST /api/logout - User logout
• GET /api/profile - Get user profile
• PUT /api/profile - Update user profile

User Endpoints

• GET /api/user/dashboard - Get user dashboard data
• GET /api/user/lots - Get available parking lots
• POST /api/user/lots/:lot_id/reserve - Reserve a parking spot
• POST /api/user/reservations/:reservation_id/release - Release a parking spot
• GET /api/user/reservations/:reservation_id/confirm-release - Get release confirmation details
• POST /api/user/generate-parking-report - Generate parking report (user-triggered job)
• GET /api/user/parking-report/:task_id - Get parking report status
• GET/PUT /api/user/preferences - View or update reminder/report preferences
• GET /api/user/history - Tabular reservation history with analytics
• POST /api/user/export-reservations - Trigger async CSV export
• GET /api/user/export-reservations/:task_id - Poll CSV export status
• GET /api/user/export-reservations/download/:filename - Download generated CSV

Admin Endpoints

• GET /api/admin/dashboard - Get admin dashboard data
• GET /api/admin/users - Get all users
• GET /api/admin/users/:user_id/reservations - Get user reservations
• GET /api/admin/lots - Get all parking lots
• POST /api/admin/lots - Create parking lot
• GET /api/admin/lots/:lot_id - Get parking lot details
• PUT /api/admin/lots/:lot_id - Update parking lot
• DELETE /api/admin/lots/:lot_id - Delete parking lot
• GET /api/admin/lots/:lot_id/spots - Get parking spots for a lot
• GET /api/admin/spots/:spot_id - Get spot details
• POST /api/admin/spots/:spot_id/force-release - Force release a spot
• DELETE /api/admin/spots/:spot_id - Delete a spot
• GET /api/admin/parking-records - Get all parking records
• GET /api/admin/search - Search users and lots
• POST /api/admin/reports/generate - Kick off global admin analytics email
• GET /api/admin/reports/:task_id - Poll admin report task status

---

Celery Tasks

Scheduled Tasks

• Monthly User Reports: Generated automatically on the 1st of every month at midnight
  • Task: application.tasks.send_monthly_reports_to_all_users
  • Generates parking reports for all users
• Daily Reminder Sweep: Runs hourly and honours each user's chosen reminder hour/channel
  • Task: application.tasks.send_daily_reminders

User-Triggered Tasks

• Parking Details Report: Generated when user requests it
  • Task: application.tasks.generate_user_parking_details_report
  • Can specify date range for the report
• CSV Export: Generates downloadable CSV + email alert when ready
  • Task: application.tasks.generate_user_reservations_csv

---

Caching

Redis caching is implemented for:

• Admin dashboard data (5 minutes expiry)
• User parking lots data (2 minutes expiry)
• Admin parking records (3 minutes expiry)

Cache is automatically cleared when:

• New parking lots are added
• Reservations are made or released
• Spots are updated

---

Notes

• Make sure the backend server is running before using the frontend
• Make sure Redis is running for caching and Celery to work
• Keep Mailhog running (mailhog) to preview reminder/report/export emails at http://localhost:8025
• During demos/viva mention that SMTP traffic goes to port 1025 while the inbox lives at port 8025
• Celery workers are optional but required for background job processing
• Update the API endpoint in the frontend code if your backend runs on a different port or host
• The admin user is automatically created when the database is first initialized

---

Troubleshooting

Redis Connection Error

• Make sure Redis is installed and running
• Check if Redis is running on localhost:6379
• Verify Redis connection: redis-cli ping (should return PONG)

Celery Not Working

• Make sure Redis is running
• Check if Celery worker is running: celery -A app worker --loglevel=info
• Check if Celery beat is running for scheduled tasks: celery -A app beat --loglevel=info

Database Issues

• Delete backend/instance/database.sqlite3 to reset the database
• Restart the backend server to recreate the database

---

Development

Backend Development

• Backend uses Flask with SQLAlchemy ORM
• Database models are in backend/application/models.py
• Routes are in backend/application/routes.py
• Configuration is in backend/application/config.py

Frontend Development

• Frontend uses Vue.js 3 with Composition API
• Components are in frontend/src/views/
• API services are in frontend/src/services/api.js
• State management is in frontend/src/stores/auth.js

---

License

This project is for educational purposes.