🗺️ 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.

---

🎯 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
• 🛠 Tech Stack
• 🚀 Getting Started
  • Prerequisites
  • 📁 Project Structure
  • Issue & Project Workflow
    • 1. Find an Issue
    • 2. Create a Branch
    • 3. Submit a Pull Request (PR)
    • 4. Code Review & Merge
  • Branching & Git Workflow
    • Branch Naming Convention
      • 1. Switch to develop branch
      • 2. Create a feature branch linked to an issue
      • 3. Make your changes in the code
      • 4. Once you're done with your changes, commit
      • 5. Push to remote branch
      • 6. Create a pull request (PR)
  • Commit Message Guidelines
    • Commit Message Format
    • Allowed Commit Types
      • Examples
  • 📋 Pull Request Guidelines
    • PR Title Format:
    • PR Description Template

---

� 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

       

---

🚀 Getting Started

Prerequisites

Ensure you have the following installed:

• Node.js (LTS version recommended)
• Git
• Yarn or npm

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>

3. Clone the repository, add . on the end to extract files to current directory.

git clone https://github.com/ArduinoDayPH2025/activity-map.git .

4. Install dependencies

npm install

5. 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

• Use the branching convention.
• Start coding!

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