{"id":31646576,"url":"https://github.com/km-saifullah/smart-event-scheduler","last_synced_at":"2026-05-04T08:42:46.343Z","repository":{"id":314782581,"uuid":"1056720147","full_name":"km-saifullah/smart-event-scheduler","owner":"km-saifullah","description":"Timezone Aware Event Booking System with Automatic Status Updates","archived":false,"fork":false,"pushed_at":"2025-09-14T18:00:53.000Z","size":22,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-14T19:44:14.417Z","etag":null,"topics":["cron-jobs","expressjs","node-cron","nodejs","scheduler"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/km-saifullah.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-14T17:07:18.000Z","updated_at":"2025-09-14T18:00:56.000Z","dependencies_parsed_at":"2025-09-14T19:44:19.792Z","dependency_job_id":"54b9da24-47e4-4d1b-8be1-0a347ae9e222","html_url":"https://github.com/km-saifullah/smart-event-scheduler","commit_stats":null,"previous_names":["km-saifullah/smart-event-scheduler"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/km-saifullah/smart-event-scheduler","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/km-saifullah%2Fsmart-event-scheduler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/km-saifullah%2Fsmart-event-scheduler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/km-saifullah%2Fsmart-event-scheduler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/km-saifullah%2Fsmart-event-scheduler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/km-saifullah","download_url":"https://codeload.github.com/km-saifullah/smart-event-scheduler/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/km-saifullah%2Fsmart-event-scheduler/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278728289,"owners_count":26035412,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cron-jobs","expressjs","node-cron","nodejs","scheduler"],"created_at":"2025-10-07T05:54:49.433Z","updated_at":"2025-10-07T05:54:50.647Z","avatar_url":"https://github.com/km-saifullah.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Smart Event Scheduler\n\nA Node.js application that allows users to create, view and book events in their **local timezone**. Event statuses are automatically updated (`scheduled → active → ended`) using a scheduler and bookings are allowed only when events are active.\n\n![Node.js](https://img.shields.io/badge/Node.js-339933?style=for-the-badge\u0026logo=node.js\u0026logoColor=white)\n![Cron Job](https://img.shields.io/badge/Cron%20Job-FF6C37?style=for-the-badge\u0026logo=cron\u0026logoColor=white)\n![Express](https://img.shields.io/badge/Express-000000?style=for-the-badge\u0026logo=express\u0026logoColor=white)\n![Mongoose](https://img.shields.io/badge/Mongoose-880000?style=for-the-badge\u0026logo=mongodb\u0026logoColor=white)\n\n## Features\n\n- Create events in **user local time**\n- Automatic **status updates** using `node-cron`\n- Display events in **user selected timezone**\n- Booking allowed only during **active events**\n- Stores all timestamps in **UTC** for consistency\n\n## The Problem\n\nWhen users create events in their local timezone, storing the time directly in MongoDB without converting it to a standard format can cause issues:\n\n- Events display incorrect times for users in other timezones\n- Scheduler cannot accurately update event status (scheduled, active, ended)\n- Booking may allow users to register for ended events or block users from active events\n\n**Example Issue:**\n\nA user in Dhaka creates an event at 22:35 Dhaka time. If the backend interprets it as UTC, the event appears 6 hours earlier, breaking scheduling and bookings.\n\n## How I resolve the problem\n\nI have solved this problem by implementing a timezone aware approach using:\n\n- Luxon for timezone conversion\n- Node-cron for scheduled status updates\n- UTC storage in MongoDB for consistency\n\n**Key Steps:**\n\n1. **User Local Time** → **UTC**: Convert user input with timezone to UTC before saving in the database.\n2. **Scheduler Updates Status**: Node-cron runs every minute to change event status from `scheduled` → `active` → `ended`.\n3. **Display in User Timezone**: Convert UTC timestamps back to the user’s local timezone when fetching events.\n4. **Booking Validation**: Allow booking only if the event is currently `active`.\n\n## Project Structure\n\n```bash\ntimezone-event-booking/\n├─ controller/\n│  └─ eventController.js\n├─ models/\n│  ├─ event.js\n│  └─ booking.js\n├─ routes/\n│  └─ eventRoutes.js\n├─ scheduler/\n│  └─ scheduler.js\n├─ server.js\n├─ package.json\n├─ .env\n```\n\n## Technologies Used\n\n- **Node.js** \u0026 **Express.js** – Backend server\n- **MongoDB** – Database for events and bookings\n- **Luxon** – Timezone conversion\n- **Node-cron** – Event status automation\n\n## Installation and Usage\n\n1. Clone the repository\n\n```bash\ngit clone https://github.com/km-saifullah/smart-event-scheduler.git\ncd smart-event-scheduler\n```\n\n2. Install dependencies\n\n```bash\nnpm install\n```\n\n3. Start the server\n\n```bash\nnpm start\n```\n\n## API Documentation\n\n**Base URL**\n\n```bash\nhttp://localhost:8000/api\n```\n\n### 1️⃣ Create Event\n\n**Endpoint**\n\n```bash\nPOST /events\n```\n\n**Description:**\nCreate a new event in the user’s local timezone. The backend converts it to UTC for storage and automatically sets the initial status (scheduled, active, ended).\n\n**Request Body**\n\n```json\n{\n  \"title\": \"Band Show\",\n  \"description\": \"Live Concert\",\n  \"startTime\": \"2025-09-14T22:35:00\",\n  \"endTime\": \"2025-09-14T22:40:00\",\n  \"timezone\": \"Asia/Dhaka\"\n}\n```\n\n**Response**\n\n```json\n{\n  \"status\": true,\n  \"event\": {\n    \"_id\": \"68c6ee95b2de328cb9879e76\",\n    \"title\": \"Band Show\",\n    \"description\": \"Live Concert\",\n    \"startTime\": \"2025-09-14T16:35:00.000Z\",\n    \"endTime\": \"2025-09-14T16:40:00.000Z\",\n    \"status\": \"scheduled\",\n    \"createdAt\": \"2025-09-14T16:34:29.822Z\",\n    \"__v\": 0\n  }\n}\n```\n\n**Notes:**\n\n- The `startTime` and `endTime` should **not include** `Z`, as it will be interpreted as UTC.\n- `timezone` is required for correct conversion.\n\n### 2️⃣ Get All Events\n\n**Endpoint**\n\n```bash\nGET /events\n```\n\n**Description:**\nRetrieve all events. Optionally, you can display events in a specific timezone.\n\n**Query Parameters:**\n\n```bash\n?timezone=\u003cIANA Timezone String\u003e\n```\n\n**Example:**\n\n```bash\nGET /events?timezone=Asia/Dhaka\n```\n\n**Response**\n\n```json\n{\n  \"status\": true,\n  \"events\": [\n    {\n      \"_id\": \"68c6ee95b2de328cb9879e76\",\n      \"title\": \"Band Show\",\n      \"description\": \"Live Concert\",\n      \"startTime\": \"2025-09-14T16:35:00.000Z\",\n      \"endTime\": \"2025-09-14T16:40:00.000Z\",\n      \"status\": \"active\",\n      \"startTimeLocal\": \"2025-09-14 10:35 PM\",\n      \"endTimeLocal\": \"2025-09-14 10:40 PM\",\n      \"createdAt\": \"2025-09-14T16:34:29.822Z\",\n      \"__v\": 0\n    }\n  ]\n}\n```\n\n**Notes:**\n\n- `startTimeLocal` and `endTimeLocal` are converted to the user’s timezone for display.\n\n### 3️⃣ Book Event\n\n**Endpoint**\n\n```bash\nPOST /events/:id/book\n```\n\n**Description:**\nBook a seat for an event. Booking is allowed only if the event status is `active`.\n\n**Request Parameters:**\n\n- Here, `id` → Event ID to book\n\n**Request Body:**\n\n```json\n{\n  \"name\": \"John Doe\",\n  \"email\": \"john@example.com\"\n}\n```\n\n**Response (Success)**\n\n```json\n{\n  \"status\": true,\n  \"booking\": {\n    \"_id\": \"68c6f0a6b2de328cb9879e77\",\n    \"event\": \"68c6ee95b2de328cb9879e76\",\n    \"name\": \"John Doe\",\n    \"email\": \"john@example.com\",\n    \"createdAt\": \"2025-09-14T16:36:00.000Z\",\n    \"__v\": 0\n  }\n}\n```\n\n**Response (Event Not Active):**\n\n```json\n{\n  \"status\": false,\n  \"message\": \"Event is not active for booking\"\n}\n```\n\n### 4️⃣ Event Status Scheduler\n\n**Description:**\n\n- Automatically updates event statuses from `scheduled` → `active` → `ended`.\n- Uses **node-cron** to run every minute.\n- Operates based on UTC stored in the database, ensuring correct status for all users globally.\n\n**Status Rules:**\n\n- **Scheduled**: Current time \u003c startTime\n- **Active**: startTime ≤ Current time \u003c endTime\n- **Ended**: Current time ≥ endTime\n\n## Conclusion\n\nHandling timezones properly is crucial for global applications. By converting user times to UTC, using a scheduler and displaying times in the user’s local timezone, you can create a robust, reliable event **booking system**. This approach ensures:\n\n- Correct event display for all users\n- Accurate automatic status updates\n- Booking allowed only during active periods\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkm-saifullah%2Fsmart-event-scheduler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkm-saifullah%2Fsmart-event-scheduler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkm-saifullah%2Fsmart-event-scheduler/lists"}