Skip to content

README.md

Latest commit

 

History

History
293 lines (208 loc) · 9.76 KB

README.md

File metadata and controls

293 lines (208 loc) · 9.76 KB

🗺️ Activity Map

A smart capacity management and virtual queuing system for Arduino Day Philippines 2025

Activity Map is a real-time web application designed to optimize crowd flow and venue navigation. Unlike standard event maps, this system acts as a traffic control engine, intelligently managing booth capacity by distinguishing between pre-scheduled visitors and walk-in attendees.

Next.js React TypeScript Tailwind CSS

🎯 Overview

Activity Map integrates directly with the event's registration system to provide a seamless experience for attendees and organizers. It solves the problem of overcrowding by implementing a Dual-Priority Queue System:

  • 🚀 Priority Access: Users with a pre-booked itinerary for a specific time/section are granted immediate entry.

  • ⏳ Virtual Walk-in Queue: Users without a booking can join a digital waitlist when a section reaches capacity, freeing them to roam the venue instead of standing in line.

  • 📊 Live Capacity Tracking: Real-time monitoring of section occupancy driven by physical entry/exit scans.

  • 🤝 Shared Identity: No new accounts required—attendees log in simply by scanning their existing Registration QR code.

Whether you are an attendee checking your itinerary or a guard managing section entry, Activity Map ensures the right people get to the right place at the right time.

📌 Table of Contents

� System Documentation

We maintain detailed documentation for the system architecture, logic flows, and database schema in the docs/ folder.

Document Description
🏗️ System Architecture High-level system overview, component breakdown, and integration points.
🔄 Application Flowchart Detailed logic flow from authentication to queue management.
💾 Database Schema (ERD) Entity relationship diagrams and table definitions.

�🛠 Tech Stack

Next.js  React  Tailwind CSS  TypeScript 

🚀 Getting Started

Prerequisites

Ensure you have the following installed:

  1. Create a New folder where you can store the project file to be referred as the Project Folder

  2. Open command prompt, change current directory to as the Project Folder

cd <PATH TO PROJECT FOLDER>
  1. Clone the repository, add . on the end to extract files to current directory.
git clone https://github.com/ArduinoDayPH2025/activity-map.git .
  1. Install dependencies
npm install
  1. Run the development server:
npm run dev

Open http://localhost:3000 with your browser to see the result.

📁 Project Structure

📦 Activity Map
├── 📂 .next
├── 📂 node_modules
├── 📂 public               # Static assets
├── 📂 src
│   ├── 📂 app              # Next.js app directory (routing & pages)
│   │   ├── 📂 components   # Reusable UI components
│   │   │   ├── 📂 features # Feature-specific components
│   │   │   └── 📂 ui       # Generic, reusable UI components
│   │   ├── 📂 context      # Global state management (React context)
│   │   ├── 📂 lib          # Utility functions and helpers
│   │   └── 📂 types        # TypeScript types and interfaces
├── .gitignore
├── eslint.config.mjs
├── next-env.d.ts
├── next.config.ts
├── package.json
├── postcss.config.mjs
├── README.md               # Project documentation
├── tailwind.config.ts      # Tailwind CSS configuration
├── tsconfig.json           # TypeScript configuration
├── .prettierrc.json        # Prettier configuration
├── package-lock.json

Issue & Project Workflow

We use GitHub Projects to manage tasks and issues. Follow these steps when working on issues:

1. Find an Issue

  • Go to the GitHub Issues page.
  • Assign issue to yourself.
  • Move the issue to "In Progress" in the project board.

2. Create a Branch

3. Submit a Pull Request (PR)

  • Reference the issue in the PR description (e.g., Closes #123).
  • Move the issue to "Review" in the project board.

4. Code Review & Merge

  • Once approved, the PR gets merged into develop.
  • The issue is moved to "Done."

Branching & Git Workflow

Branch Naming Convention

Branch Type Naming Convention Example
Main main main
Development dev dev
Feature feature/ISSUE-ID-feature-name feature/123-add-auth
Bugfix bugfix/ISSUE-ID-issue-name bugfix/234-fix-footer
Hotfix hotfix/ISSUE-ID-critical-fix hotfix/345-fix-login

1. Switch to develop branch

git checkout dev
git pull origin dev

2. Create a feature branch linked to an issue

git checkout -b feature/ISSUE-ID-feature-name

Example:

git checkout -b feature/123-add-login-auth

3. Make your changes in the code

4. Once you're done with your changes, commit

git add .
git commit -m "feat(auth): add login authentication (Closes #123)"

5. Push to remote branch

git push origin feature/ISSUE-ID-feature-name

6. Create a pull request (PR)

  • Go to GitHub
  • Open a new PR from feature/ISSUE-ID-feature-name → develop
  • Use the PR Template below

Commit Message Guidelines

Commit Message Format

<type>(<scope>): <description>

Allowed Commit Types

This project follows Conventional Commits.

Type Description
feat A new feature
fix A bug fix
docs Documentation changes
style Code style changes (formatting, etc.)
refactor Code changes that neither fix a bug nor add a feature
perf Performance improvements
test Adding or modifying tests
chore Maintenance and other minor tasks

Examples

git commit -m "feat(auth): add user authentication with JWT "
git commit -m "fix(navbar): resolve mobile responsiveness issue "
git commit -m "docs(readme): update contribution guide "

📋 Pull Request Guidelines

PR Title Format:

<type>(<scope>): <short description>

Example

feat(auth): add user login functionality
fix(navbar): resolve mobile responsiveness issue

PR Description Template

✨ What’s New?
- [x] Briefly explain what was added

📷 Screenshots of website (IMPORTANT)
_Add relevant screenshots/gifs_

🔗 Related Issues
Closes #ISSUE_NUMBER

✅ Checklist (from issue)
- [ ] Code follows project conventions
- [ ] Linted & formatted
- [ ] Tested locally