🌉 ResourceBridge

Campus Resource Sharing Network with Trust, Safety, and Physical Accountability A secure, production-ready Flask application designed for higher-education equipment and laboratory facility sharing.

Quick Access

Resource	Direct Link & Access Details
🚀 Live Application	https://resourcebridge-79f6.onrender.com
🟢 Health Monitoring	https://resourcebridge-79f6.onrender.com/health (`HTTP 200 OK`)
🔑 Demo Accounts (1-Click)	`student@campus.edu` • `manager@campus.edu` • `admin@campus.edu` (Password: `StudentPass123!` / `ManagerPass123!` / `AdminPass123!`) — Jump to Demo Walkthrough
⚠️ Cloud Storage & Limitations	Evaluator accounts are pre-seeded on cold start; live deployment runs on Render Free ephemeral storage — Jump to Limitations
🧪 Test Verification	70 automated tests passing (100%) + real Playwright Chromium browser tests — Jump to QA Report

📑 Table of Contents

Quick Access
1. Project Overview
2. Problem Statement
3. Solution
4. Target Users and Use Cases
5. Key Features
6. User Workflow
7. Technology Stack and Architecture
8. Installation and Local Setup
9. Demo and Test Instructions
10. Deployment
11. Testing and Quality Assurance
12. Known Limitations and Future Improvements
13. AI Assistance and Development Disclosure
14. Project Structure and Contribution Information

1. Project Overview

ResourceBridge is a campus resource-sharing and facility stewardship web application built with Python and Flask. It provides university communities with a centralized platform to discover, schedule, borrow, and inspect high-value equipment and specialized spaces. By replacing informal paper sign-up sheets and fragmented departmental emails with verified digital custody, automated interval-conflict checking, and condition reports, ResourceBridge bridges the gap between campus resources and student innovation.

2. Problem Statement

Across higher education institutions, millions of dollars worth of advanced academic assets—such as cinema cameras, laser cutters, 3D printers, deep-learning GPU servers, audio recording booths, and robotics workbenches—remain underutilized behind locked departmental doors.

Simultaneously, students working on capstone projects, research publications, and creative portfolios struggle to access these resources due to:

Departmental Silos: Equipment is often restricted to specific degree programs or physical buildings without cross-campus visibility.
Informal Paper Logs: Clipboards and manual sign-out sheets lead to lost accessories, untracked damage, and zero accountability.
Scheduling Conflicts: Accidental double-bookings disrupt lab sessions and waste valuable student and faculty time.
Reluctance to Loan: Facility managers hesitate to lend sensitive instruments without verifiable condition check-in and intake inspections.

3. Solution

ResourceBridge resolves these campus sharing challenges through an accountable lending workflow:

Centralized Campus Catalog: Students search and filter all institutional equipment and bookable rooms in one place, with transparent visibility into safety prerequisites and location.
Automated Scheduling Engine: Prevents double-booking via temporal overlap algorithms, enforces maximum borrowing limits (14 days), and checks asset operating status.
Two-Point Physical Custody Inspections: Facility managers file digital Check-In and Return Condition Reports (scoring physical condition 1–5 with mandatory notes) to guarantee fair, tamper-evident accountability.
Incident Escalation: Borrowers and managers can log formal incident tickets for equipment malfunctions or transit damage, tracked through administrative resolution.
Role-Based Security: Complete access segregation among students, departmental custodians, and campus administrators.

4. Target Users and Use Cases

ResourceBridge supports three distinct campus roles:

Role	Primary User Group	Core Responsibilities & Use Cases
Student (Borrower)	Enrolled undergraduates, graduate researchers, student organizations	• Browse catalog by keyword, location, and category. • Submit booking requests for academic projects. • Track active loans and scheduled return deadlines. • Report equipment defects or damage incidents.
Facility Manager (Custodian)	Lab directors, shop technicians, faculty advisors	• Review, approve, or reject reservation requests for their department. • Conduct physical handover check-in with condition reports. • Perform intake return inspections. • Investigate and resolve incident tickets.
Campus Administrator (Auditor)	Department chairs, safety officers, IT/operations directors	• Maintain institution-wide inventory (create, edit, retire resources). • Access complete chronological audit logs for all bookings. • Monitor platform health, dispute rates, and asset utilization.

5. Key Features

Every feature listed below is fully implemented and backed by automated test coverage:

Authentication & Role-Based Access Control:
- Secure registration restricted to verified student accounts (role='student').
- Salted password hashing via Werkzeug (scrypt / pbkdf2:sha256).
- Context-aware session management with @login_required, @manager_required, and @admin_required route guards.
Resource Discovery & Catalog:
- Full-text search matching asset title and description.
- Multi-criteria filtering by Category (Audio/Video, Lab Equipment, Computing, Workshop, Space) and Campus Building Location.
- Asset type segmentation (equipment vs. space).
- Clear display of safety rules, prerequisites, and custodian contact information.
Conflict-Aware Booking Engine:
- Mathematical temporal interval validation: (existing_start < requested_end) and (existing_end > requested_start).
- Automatic rejection of requests for inactive or maintenance-flagged assets.
- Maximum duration enforcement (up to 14 days).
- Thread-synchronized approval execution (threading.Lock) preventing double-booking race conditions.
Physical Accountability & Condition Reports:
- Mandatory handover check-in report before an asset is released.
- Mandatory return inspection report before a booking is closed.
- 1-to-5 condition rating scale (excellent, good, fair, poor) with mandatory descriptive notes.
Incident Management:
- Digital incident submission linked directly to specific bookings and resources.
- Severity tracking and administrative status updates (open, under_review, resolved).
Immutable Audit History:
- Centralized BookingAuditLog capturing timestamps, acting user ID, prior status, new status, and action summaries.

6. User Workflow

The platform guides users through an end-to-end borrowing lifecycle:

[1. Register / Sign In]
         │
         ▼
[2. Discover Resource]  ──►  Filter by Category & Campus Building
         │
         ▼
[3. Submit Reservation]  ──►  Select Start/End Timestamps (<= 14 Days)
         │
         ▼
[4. Manager Review]      ──►  Approve / Reject with Reason
         │ (Approved)
         ▼
[5. Physical Check-In]   ──►  Custodian Handover & Condition Report #1
         │
         ▼
[6. Active Loan Custody] ──►  Student Uses Asset for Academic Work
         │
         ▼
[7. Physical Return]     ──►  Intake Inspection & Condition Report #2
         │
         ▼
[8. Closed / Incident]   ──►  Asset Restocked; Optional Incident Escalation

7. Technology Stack and Architecture

ResourceBridge is built on a clean, maintainable, dependency-light Python web architecture:

Web Framework: Flask 3.0+ (Application Factory pattern in app.py)
Language: Python 3.10+ (Tested through Python 3.14)
Database & ORM: SQLAlchemy 3.1+ (SQLite default; PostgreSQL-ready)
Authentication: Flask-Login 0.6+ and Werkzeug Security
Production Server: Gunicorn 21.2+ (--workers 1 --threads 4 --timeout 60) / Waitress WSGI
Templating: Jinja2 (HTML5 with automatic contextual XSS escaping)
Design System: Custom Academic Slate CSS (no heavy external CSS frameworks or CDNs)
Client Scripting: Vanilla JavaScript ES6 (1-click demo selectors, mobile navigation toggling)
Testing: Pytest 9.1+ and Playwright Chromium real browser automation

System Architecture Diagram

flowchart TD
    subgraph Client ["Client Layer (Browser)"]
        Browser["Desktop & Mobile Browsers<br/>(Vanilla JS & Academic Slate CSS)"]
    end

    subgraph Server ["Application Layer (Flask 3.0 + WSGI)"]
        WSGI["Gunicorn WSGI Server<br/>(wsgi.py)"]
        AppFactory["Flask App Factory<br/>(app.py:create_app)"]
        AuthModule["Flask-Login & Werkzeug<br/>(RBAC: Student / Manager / Admin)"]
        BookingEngine["Reservation Engine<br/>(Interval Overlap & Concurrency Lock)"]
        SecurityHeaders["Security Middleware<br/>(CSRF, CSP, FrameOptions, SafeRedirect)"]
    end

    subgraph Data ["Persistence Layer (SQLAlchemy ORM)"]
        ORM["SQLAlchemy Models<br/>(models.py)"]
        Database[("SQLite (Local Development)<br/>or<br/>PostgreSQL (Production Cloud)")]
    end

    Browser -->|HTTPS Requests| WSGI
    WSGI --> AppFactory
    AppFactory --> SecurityHeaders
    SecurityHeaders --> AuthModule
    AuthModule --> BookingEngine
    BookingEngine --> ORM
    ORM --> Database

8. Installation and Local Setup

Prerequisites

Python 3.10 or higher
pip package manager
Git

Step 1: Clone the Repository

git clone https://github.com/syedhamzah-dev/resourcebridge.git
cd resourcebridge

Step 2: Create and Activate Virtual Environment

On Linux/macOS:

python3 -m venv venv
source venv/bin/activate

On Windows (PowerShell):

python -m venv venv
.\venv\Scripts\Activate.ps1

Step 3: Install Dependencies

pip install -r requirements.txt

Step 4: Configure Environment Variables (Optional)

The application works out of the box with safe local defaults. To customize secrets:

# On Linux/macOS
cp .env.example .env

# On Windows (PowerShell)
copy .env.example .env

Step 5: Initialize and Seed the Database

Initialize the database tables and populate sample demonstration data:

python seed_demo.py

(Alternatively, you can run flask init-db followed by flask seed)

Step 6: Run the Local Development Server

python app.py

Or via the production WSGI runner:

python wsgi.py

Open your web browser and navigate to: 👉 http://127.0.0.1:5000

9. Demo and Test Instructions

For evaluation, presentations, and hackathon judging, the database includes three pre-configured accounts:

⚠️ DEMONSTRATION USE ONLY: The credentials below are provided strictly for local evaluation and hackathon testing. Never use production secrets or real passwords.

Role	Account Name	Email	Password	Primary Workflow to Test
Student	Alex Rivera	`student@campus.edu`	`StudentPass123!`	Browse catalog, submit booking request, view booking status.
Manager	Dr. Elena Vance	`manager@campus.edu`	`ManagerPass123!`	Review pending requests, approve booking, conduct check-in and return.
Admin	Marcus Brody	`admin@campus.edu`	`AdminPass123!`	Manage catalog resources, review institutional audit log, check platform metrics.

⚡ 1-Click Evaluation

On the Sign In screen (/login), click any of the 1-Click Demo Profile buttons to automatically fill the credentials and sign in instantly without typing.

Step-by-Step Demonstration Script

Student Request: Sign in as student@campus.edu. Go to /resources, select Sony FX6 Cinema Camera, and submit a booking request for tomorrow 10:00–14:00. Status becomes pending. Sign out.
Manager Approval & Check-In: Sign in as manager@campus.edu. Navigate to /manager/bookings, locate Alex's request, and click Approve. Click Check-In Resource, rate the initial physical condition (e.g., 5/5, "Pristine condition"), and confirm. Status becomes checked_in.
Manager Return: On the same booking detail page, click Return Resource, enter the intake condition (e.g., 4/5, "Minor tripod plate wear"), and submit. Status transitions to returned.
Admin Audit: Sign in as admin@campus.edu. Open /dashboard to review campus-wide utilization, and inspect the chronological event log on the booking detail page.

10. Deployment

ResourceBridge is deployed and publicly accessible for hackathon judging:

Verified Live URL: 👉 https://resourcebridge-79f6.onrender.com
Health Check Endpoint: https://resourcebridge-79f6.onrender.com/health Returns HTTP 200 OK: {"status": "healthy", "database": "connected"}
Hosting Platform: Render.com (Web Service connected to GitHub repository main branch)
WSGI Server: Gunicorn 21.2.0 (web: gunicorn wsgi:app --workers 1 --threads 4 --timeout 60)
Runtime: Python 3.11.8 (runtime.txt)
Transport Security: Enforced TLS/HTTPS, SESSION_COOKIE_SECURE=True, HttpOnly, SameSite=Lax

Production Environment Variables Reference

Variable	Required?	Production Value	Description
`FLASK_ENV`	Yes	`production`	Enforces production mode, disables debugger, activates secure cookie defaults.
`SECRET_KEY`	Yes	(64-char hex string)	Cryptographic key for session signing and CSRF tokens. Application halts if missing in production.
`SESSION_COOKIE_SECURE`	Yes	`true`	Restricts session cookies strictly to HTTPS connections.
`DATABASE_URL`	Optional	`postgresql://...`	Connection URI. Defaults to local SQLite if omitted. Automatically normalizes legacy `postgres://` prefixes.
`PYTHON_VERSION`	Optional	`3.11.8`	Target Python runtime for buildpacks.

11. Testing and Quality Assurance

The application is validated across three testing layers:

A. Automated Test Suite (70 Tests Passing)

Run the complete automated test suite locally:

python -m pytest -v

============================= test session starts =============================
platform win32 -- Python 3.14.6, pytest-9.1.1, pluggy-1.7.0
rootdir: C:\Users\mohdh\Desktop\Projects\resourcebridge
plugins: anyio-4.15.1, Faker-40.43.0, platformdirs-4.13.4, asyncio-1.4.0, cov-7.1.0
collected 70 items

tests\test_auth.py ............                                          [ 17%]
tests\test_bookings.py ................                                  [ 40%]
tests\test_frontend.py .....                                             [ 47%]
tests\test_lifecycle.py ...........                                      [ 62%]
tests\test_resources.py ...............                                  [ 84%]
tests\test_security.py ...........                                       [100%]

============================= 70 passed in 31.51s =============================

Coverage Breakdown:

test_auth.py (12 tests): Password hashing, role escalation rejection, CSRF token presence, public registration, first-login vs. returning greetings, email pre-fill.
test_bookings.py (16 tests): Duration limits (<=14 days), forward-looking dates, status transitions, approval authorization, multi-user conflict rejection.
test_frontend.py (4 tests): WCAG contrast, responsive layout markers, 1-click demo helpers, about page milestones.
test_lifecycle.py (11 tests): Check-in and return condition reports, note requirements, privacy isolation between students, incident reporting.
test_resources.py (15 tests): Catalog searching, category filtering, building location filtering, manager inventory CRUD, empty states.
test_security.py (12 tests): HTTP defense headers (nosniff, SAMEORIGIN), safe open redirect validation, custom 403/404/500 handlers, multithreaded concurrency mutex lock.

B. Local Real Browser Automation (Playwright Chromium)

Verified through real, automated headless Chromium browser execution against http://127.0.0.1:5001:

Registered brand-new student account (local_browser_*@campus.edu).
Confirmed successful account creation alert and pre-filled email.
Verified initial login greeting: "Welcome to ResourceBridge, <Name>!".
Signed out and terminated browser context.
Opened fresh browser session; verified returning greeting: "Welcome back, <Name>!".
Terminated and restarted the Flask application process.
Verified persistent sign-in after server restart with SQLite.

C. Deployed Live Browser Automation (Playwright Chromium on Render)

Verified through real automated Chromium browser execution against https://resourcebridge-79f6.onrender.com:

Navigated to live /register endpoint.
Registered live user (browser_user_*@campus.edu).
Verified post-registration redirect with pre-filled email and success flash alert.
Completed first login; verified "Welcome to ResourceBridge" greeting and dashboard access.
Signed out and closed browser context.
Opened fresh browser session (Context 2) with clean cookie jar; verified successful login with "Welcome back".
Tested bad-password attempt in Context 3; verified rejection with "Invalid email or password".

12. Known Limitations and Future Improvements

Note

Engineering Transparency: In the spirit of complete architectural honesty, ResourceBridge documents its current deployment scope, cloud persistence behavior, and concurrency boundaries below. These reflect standard free-tier cloud infrastructure trade-offs rather than application defects.

Architectural Disclosures & Constraints Matrix

Constraint Area	Practical Impact & Developer Finding	Built-in Mitigation & Production Path
Cloud Ephemeral Storage (Render Free Web Service)	Render's free tier runs in ephemeral Docker containers. Idle spin-downs (after 15 min of inactivity) or new git deploys recreate the container disk, resetting the local SQLite file.	Evaluator Safeguard: `wsgi.py` auto-initializes and re-seeds the 3 demo accounts on startup so judges always land on an active demo. Production Path: Pre-configured in `app.py` to seamlessly connect Render Free PostgreSQL via `DATABASE_URL`.
Concurrency Locking Scope (Process-Level Synchronization)	The in-memory `threading.Lock` within `app.py` safely serializes booking approvals across concurrent threads within a single Python process (`gunicorn -w 1 --threads 4`).	Scaling Path: For horizontally scaled multi-worker clusters (`gunicorn -w 4`) or multi-server deployments, distributed row locking (`SELECT ... FOR UPDATE`) or Redis locks can be enabled.
Outbound Notifications (Communication Channels)	Booking approvals, condition reports, and incident tickets update the database and dashboard in real-time, but do not yet dispatch external email or SMS alerts.	Roadmap Path: Architected for plug-and-play integration with Celery/Redis background task workers and university SMTP relays without schema modifications.
Physical Handover Check-In (Condition Intake Inspection)	Condition reports (ratings 1–5 and mandatory descriptive notes) are recorded via authenticated web forms during in-person check-in and return handovers.	Roadmap Path: In a physical campus deployment, pairing this workflow with mobile camera QR barcode scanning will streamline physical equipment intake.
Preventive Maintenance Planning (Historical Data Synthesis)	Condition reports, incident tickets, and usage logs track individual loans, but are not yet aggregated into preventive maintenance trends.	Roadmap Path: Synthesize historical condition degradation and incident records to help managers schedule servicing and prioritize inspections based on objective data rather than automated blame.

Realistic Future Roadmap

Maintenance Planning from Condition & Incident Records: Utilizing accumulated condition reports, incident logs, and checkout history to help resource managers identify equipment that repeatedly returns damaged or requires attention. Rather than assigning automated blame or generating automated schedules, aggregated historical trends provide custodians with actionable insights to plan preventive maintenance, prioritize inspections, and allocate departmental repair budgets more effectively.
Automated Alerts: Email and SMS dispatch for reservation approvals and upcoming return reminders.
Mobile QR Scanning: Quick camera scanning for asset barcode tags during physical handover.
Calendar Synchronization: Export approved bookings to iCalendar (.ics) and Google Calendar.
Campus Single Sign-On (SSO): SAML 2.0 / OAuth2 integration with university identity providers.

13. AI Assistance and Development Disclosure

In accordance with hackathon competition rules and transparency best practices:

Human Author & Engineering Lead: Syed Mohammad Hamzah.
- Drove all problem discovery, system architecture, database schema design, business rule constraints, security policies, verification strategy, and final code reviews.
AI Pair Programming Assistant: Google Antigravity (powered by DeepMind Gemini models).
- Assisted with writing repetitive boilerplate, expanding pytest test fixtures, authoring CSS design tokens, diagnosing edge cases in authentication redirects, and automating Playwright browser test scripts.
Verification & Oversight: Every line of code, template element, test case, and documentation deliverable was reviewed, tested, and validated by the human developer. All automated tests (70 passing) and real browser tests were executed and confirmed.

14. Project Structure and Contribution Information

Directory Layout

resourcebridge/
├── app.py                  # Flask Application Factory, routes, error handlers, CLI commands
├── models.py               # SQLAlchemy models (User, Resource, Booking, ConditionReport, Incident, AuditLog)
├── seed_demo.py            # Standalone demonstration database initialization script
├── wsgi.py                 # Production WSGI entrypoint with auto-seeding
├── Procfile                # Render/Heroku process configuration (Gunicorn command)
├── runtime.txt             # Python runtime specification (python-3.11.8)
├── requirements.txt        # Pinned project dependencies
├── .env.example            # Environment variable template
├── .gitignore              # Git ignore rules (excludes SQLite files, caches, virtualenvs)
├── templates/              # Jinja2 HTML templates
│   ├── base.html           # Master layout with responsive navbar and flash alerts
│   ├── index.html          # Public landing page with featured resources
│   ├── about.html          # Campus sharing mission and roadmap
│   ├── login.html          # Sign-in form with 1-Click Demo Profiles
│   ├── register.html       # Student registration form
│   ├── dashboard.html      # Role-aware dashboard with live statistics
│   ├── resources/          # Catalog browse, detail, and inventory management
│   └── bookings/           # Reservation requests, manager queues, condition reports
├── static/
│   ├── css/style.css       # Academic Slate design system (high-contrast, responsive)
│   └── js/main.js          # Demo autofill and UI interaction scripts
├── tests/                  # Automated pytest test suites (70 tests)
│   ├── test_auth.py        # Authentication and registration tests
│   ├── test_bookings.py    # Booking engine and conflict tests
│   ├── test_frontend.py    # UI layout and accessibility tests
│   ├── test_lifecycle.py   # Check-in, return, and incident tests
│   ├── test_resources.py   # Catalog and inventory CRUD tests
│   └── test_security.py    # Security headers, cookies, CSRF, and concurrency tests
└── reports/                # Local evidence package (excluded from Git)
    ├── PROJECT_SUMMARY.md  # Detailed summary dossier with issue audit
    └── ResourceBridge_Submission_Summary.pdf # Formatted submission summary PDF

Contributing & Reporting Issues

Fork the repository and create a feature branch (git checkout -b feature/amazing-feature).
Run the test suite (python -m pytest) to ensure all 70 tests pass without regression.
Commit your changes with clear semantic messages (git commit -m "feat: add amazing feature").
Push to your branch (git push origin feature/amazing-feature) and open a Pull Request.
To report a bug or request an enhancement, please open an Issue on GitHub.

📜 License

This project is licensed under the MIT License — see the LICENSE file for details. Built for educational and hackathon demonstration purposes.

Name		Name	Last commit message	Last commit date
instance		instance
static		static
templates		templates
tests		tests
.env.example		.env.example
.gitignore		.gitignore
Procfile		Procfile
README.md		README.md
app.py		app.py
models.py		models.py
requirements.txt		requirements.txt
runtime.txt		runtime.txt
seed_demo.py		seed_demo.py
wsgi.py		wsgi.py

Latest commit

History

Folders and files

Repository files navigation