NYU Study Spaces Status Reporter

A real-time, community-driven monitoring system that reports on the status and quality of study spaces at various NYU locations. Students can submit reviews with ratings for silence, crowdedness, and overall quality, helping others find the best study spaces before making trips across campus.

🌐 Live Application

URL: http://159.65.43.42

The application is deployed on Digital Ocean with automated CI/CD via GitHub Actions.

Team Members

• Zeba Shafi
• Jubilee Tang
• Connor Lee
• Catherine Yu
• Evelynn Mak

Prerequisites

• Docker and Docker Compose installed
• Git for cloning the repository
• A Docker Hub account (for pushing custom images)

Configuration

1. Environment Variables

Copy the example environment file:

cp .env.example .env

Edit .env with your configuration:

SECRET_KEY=your-secret-key-here-change-in-production
FLASK_ENV=production

Important: Never commit the actual .env file to version control!

2. MongoDB Setup

No additional configuration needed. MongoDB will automatically:

• Create the database (default: proj4) on first run
• Store data in a Docker volume for persistence

Running the Application

Using Docker Compose (Recommended)

1. Clone the repository:

git clone https://github.com/swe-students-fall2025/5-final-superfunteam.git
cd 5-final-superfunteam

2. Configure environment variables:

cp .env.example .env
# Edit .env with your SECRET_KEY

3. Build and start all containers:

docker-compose up --build

4. Access the application:

   • Web App: http://localhost:5001
   • MongoDB: localhost:27017

5. Stop the application:

# Stop containers (keeps data)
docker-compose down

# Stop containers and remove volumes (clean slate)
docker-compose down -v

Running Locally (Development)

1. Install dependencies:

cd webapp
pip install -r requirements.txt

2. Set environment variables:

export MONGO_URI=mongodb://localhost:27017/proj4
export SECRET_KEY=dev-secret-key
export FLASK_ENV=development

3. Start MongoDB (if not using Docker):

mongod --dbpath /path/to/data/db

4. Run the application:

python app.py

Seeding the Database

To populate the database with sample study spaces:

# Start the containers
docker-compose up -d

# Add sample study spaces via API
curl -X POST http://localhost:5001/api/spaces \
  -H "Content-Type: application/json" \
  -d '{
    "building": "Bobst Library",
    "sublocation": "2nd Floor Study Area"
  }'

# Add a review (requires authentication)
curl -X POST http://localhost:5001/api/reviews \
  -H "Content-Type: application/json" \
  -H "Cookie: session=YOUR_SESSION_COOKIE" \
  -d '{
    "space_id": "SPACE_ID_HERE",
    "rating": 4,
    "silence": 5,
    "crowdedness": 3,
    "review": "Great quiet space with good lighting"
  }'

API Endpoints

Study Spaces

• GET /api/spaces - Get all study spaces
• GET /api/spaces/<id> - Get specific study space with recent reviews
• POST /api/spaces - Add new study space
• PUT /api/spaces/<id> - Update study space info
• DELETE /api/spaces/<id> - Delete study space

Reviews

• POST /api/reviews - Submit a study space review (requires authentication)
• GET /api/reviews - Get all reviews (most recent first)
• GET /api/reviews?space_id=<id> - Get reviews for specific study space

Testing

Run the test suite:

cd webapp
pytest tests/ -v --cov=app --cov-report=html

View coverage report:

open htmlcov/index.html  # On macOS
# or
start htmlcov/index.html  # On Windows

CI/CD Pipeline

The project uses GitHub Actions for continuous integration and deployment:

• Workflow File: .github/workflows/webapp-ci.yml
• Triggers: Push or PR to main branch
• Steps:
  1. Run unit tests with pytest
  2. Check code coverage (minimum 80%)
  3. Build Docker image
  4. Push to Docker Hub
  5. Deploy to Digital Ocean

Project Structure

5-final-superfunteam/
├── .github/
│   └── workflows/
│       ├── webapp-ci.yml      # CI/CD pipeline
│       └── webapp-deploy.yml  # Deployment workflow
├── webapp/                     # Flask web application
│   ├── static/
│   │   ├── css/
│   │   │   └── style.css
│   │   └── js/
│   │       └── main.js
│   ├── templates/
│   │   ├── base.html
│   │   └── index.html
│   ├── tests/
│   │   ├── __init__.py
│   │   └── test_app.py
│   ├── .dockerignore
│   ├── .env.example
│   ├── app.py
│   ├── Dockerfile
│   ├── README.md
│   └── requirements.txt
├── .dockerignore
├── .env.example
├── .gitignore
├── docker-compose.yml
├── instructions.md
├── LICENSE
├── pyproject.toml
└── README.md

Technologies Used

• Backend: Python 3.11, Flask 3.0.0, PyMongo 4.6.0
• Frontend: HTML5, CSS3, JavaScript
• Database: MongoDB 7.0
• Containerization: Docker, Docker Compose
• Web Server: Gunicorn
• Testing: Pytest
• CI/CD: GitHub Actions
• Deployment: Digital Ocean

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Documentation

• Database Schema: See webapp/README.md for database setup and schema documentation
• Deployment Guide: See DEPLOYMENT.md for complete Digital Ocean droplet deployment instructions
• Quick Start: See QUICKSTART.md for quick deployment reference

Deployment

This application can be deployed to a Digital Ocean droplet with automated CI/CD via GitHub Actions.

Quick Setup:

1. Create a Digital Ocean droplet
2. Run the setup script: ./setup-droplet.sh
3. Configure GitHub Secrets (Docker Hub credentials, droplet SSH key)
4. Push to main branch - automatic deployment!

See DEPLOYMENT.md for detailed instructions.

License

This project is part of an academic exercise for NYU's Software Engineering course.