{"id":31508164,"url":"https://github.com/abhinandanwadwa/overbookr","last_synced_at":"2026-04-29T16:07:05.629Z","repository":{"id":314329167,"uuid":"1052975567","full_name":"abhinandanwadwa/overbookr","owner":"abhinandanwadwa","description":"A scalable backend system for event hosting and seat-level bookings.","archived":false,"fork":false,"pushed_at":"2025-09-14T14:42:49.000Z","size":424,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-24T11:10:36.816Z","etag":null,"topics":["api","backend","gin-gonic","go","golang","postgresql","rest-api"],"latest_commit_sha":null,"homepage":"https://overbookr-production.up.railway.app","language":"Go","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/abhinandanwadwa.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-08T20:10:49.000Z","updated_at":"2025-09-14T14:45:15.000Z","dependencies_parsed_at":"2025-09-11T22:24:44.173Z","dependency_job_id":"bae75f3b-60ac-4d1c-9447-938fd0d0a49c","html_url":"https://github.com/abhinandanwadwa/overbookr","commit_stats":null,"previous_names":["abhinandanwadwa/overbookr"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/abhinandanwadwa/overbookr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abhinandanwadwa%2Foverbookr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abhinandanwadwa%2Foverbookr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abhinandanwadwa%2Foverbookr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abhinandanwadwa%2Foverbookr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/abhinandanwadwa","download_url":"https://codeload.github.com/abhinandanwadwa/overbookr/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abhinandanwadwa%2Foverbookr/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32432991,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T13:34:34.882Z","status":"ssl_error","status_checked_at":"2026-04-29T13:34:29.830Z","response_time":110,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["api","backend","gin-gonic","go","golang","postgresql","rest-api"],"created_at":"2025-10-02T21:07:12.366Z","updated_at":"2026-04-29T16:07:05.596Z","avatar_url":"https://github.com/abhinandanwadwa.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🎟️ Overbookr\r\n\r\nA scalable backend system for **event seat-level bookings**.\r\nBuilt with **Go (Gin framework)** and **PostgreSQL**, designed to handle **high concurrency, idempotent bookings, seat holds, and waitlists**.\r\n\r\n---\r\n\r\n## ✨ Features\r\n\r\n* 👤 **User Management** – Register, login (JWT-based authentication), roles (`user`, `admin`)\r\n* 🎫 **Event Management** – Create, list, and view events with seat capacity\r\n* 💺 **Seat-Level Reservations** – Bulk insert seats, query seat maps\r\n* ⏳ **Seat Holds** – Temporarily reserve seats with a hold token (5 minutes)\r\n* 🛡 **Idempotent Bookings** – Prevents duplicate bookings with idempotency keys\r\n* 📋 **Waitlist** – Users can queue when an event is full, auto-promoted when seats free\r\n* ❌ **Cancellations** – Cancel bookings safely and trigger waitlist promotions\r\n* 📊 **Analytics** – Bookings per day, cancellations, utilization, and top events\r\n* ⚡ **Background Workers** – Expire holds, promote waitlists, reconcile mismatches\r\n\r\n---\r\n\r\n## 🛠 Tech Stack\r\n\r\n* **Language:** Go (Gin framework)\r\n* **Database:** PostgreSQL + SQLC for queries\r\n* **Auth:** JWT (role-based)\r\n* **Deployment:** [Railway](http://overbookr-production.up.railway.app/)\r\n* **Documentation:** [Swagger](http://overbookr-production.up.railway.app/docs)\r\n* **Load Testing:** k6\r\n\r\n---\r\n\r\n## 📂 Project Structure\r\n\r\n```\r\n.\r\n├── cmd/               # Main entrypoint\r\n├── internal/          \r\n│   ├── api/           # Full API logic\r\n│   ├── db/            # SQLC generated queries\r\n│   ├── queries/       # Plain SQL Queries\r\n│   └── workers/       # Background workers\r\n├── migrations/        # SQL migrations\r\n└── README.md\r\n```\r\n\r\n---\r\n\r\n## ⚙️ Setup \u0026 Run\r\n\r\n### 1. Clone Repo\r\n\r\n```bash\r\ngit clone https://github.com/abhinandanwadwa/.git\r\ncd \u003crepo-name\u003e\r\n```\r\n\r\n### 2. Environment Variables\r\n\r\nCreate a `.env` file with the following:\r\n\r\n```env\r\n# Server\r\nPOSTGRESQL_URI=\"postgresql://user:password@localhost:5432/overbookr?sslmode=disable\"\r\nPORT=\"8080\"\r\n\r\nJWT_SECRET=\"your_jwt_secret_key_here\"\r\n\r\nGMAIL_USER=\"your_email_address\"\r\nGMAIL_PASS=\"your_email_password(app_passwords are recommended)\"\r\n```\r\n\r\n### 3. Run Migrations\r\n\r\n```bash\r\nmigrate -path migrations -database \"$POSTGRESQL_URI\" up\r\n```\r\n\r\n*(or use `goose`/`atlas` depending on your migration tool)*\r\n\r\n### 4. Start API\r\n\r\n```bash\r\ngo run cmd/main.go\r\n```\r\n\r\n### 5. Run Tests\r\n\r\n```bash\r\nk6 run internal/api/tests/k6_full_load.js\r\n```\r\n\r\n---\r\n\r\n## 🏗 Architecture\r\n\r\n![Architecture Diagram](./internal/api/server/docs/architecture.png)\r\n\r\n* Clients → API Layer (Gin) → PostgreSQL\r\n* Background Workers:\r\n\r\n  * Promote waitlists when seats free\r\n  * Expire holds every 30s\r\n  * Reconcile mismatches hourly\r\n\r\n---\r\n\r\n## 📊 ER Diagram\r\n\r\n![ER Diagram](./internal/api/server/docs/er-diagram.png)\r\n\r\n* **Users** ↔ **Bookings** ↔ **Seats** ↔ **Events**\r\n* **Seat Holds** reserve seats before booking\r\n* **Waitlist** queues users for full events\r\n\r\n---\r\n\r\n## 🔑 Design Decisions \u0026 Tradeoffs\r\n\r\n* **Atomic Booked Count Guard**\r\n  Prevent overselling by only incrementing `booked_count` if it stays under capacity.\r\n\r\n* **Seat Holds First, Book Later**\r\n  Users can’t directly book seats. They first create a **hold**, then confirm with a hold token. This avoids race conditions.\r\n\r\n* **Idempotency Keys**\r\n  Guarantees duplicate booking requests don’t create multiple bookings.\r\n\r\n* **Tradeoff: Waitlist Ordering**\r\n  Current implementation uses `MAX(position)+1` which works, but under heavy concurrency, an **event-level counter** or **per-event sequence** would be stronger.\r\n\r\n* **Background Reconciliation**\r\n  Periodically fixes mismatches. In production, we’d prefer logging + alerting instead of silent auto-fix.\r\n\r\n---\r\n\r\n## 📈 Load Testing Results\r\n\r\n📊 **k6 Test with 50 VUs for \\~85s**\r\n\r\n* **Requests handled:** \\~5,300 (\\~62 req/s)\r\n* **Avg response time:** 1.2 ms\r\n* **p95 latency:** 1.46 ms (99% of requests \u003c2ms)\r\n* **Max latency:** \\~61 ms\r\n* **Bookings created:** 96 (100% consistency with holds)\r\n* **Conflicts handled:** \\~2272 (all returned 409, no double-bookings)\r\n* **Waitlists joined:** 45 successful, 214 duplicates rejected correctly\r\n* **Cancellations:** 12 successful, all freed seats cleanly\r\n\r\n✅ **Highlights:**\r\n\r\n* Concurrency-safe: no double bookings under race conditions\r\n* Data integrity preserved under stress\r\n* Blazing fast: 99% of requests \u003c2ms\r\n* Resilient workers: holds expired, waitlists promoted, mismatches reconciled\r\n\r\n---\r\n\r\n## 🚀 Future Improvements\r\n\r\n* Redis-backed seat holds for even faster operations at scale\r\n* Message queues for large-scale waitlist promotions\r\n* Prometheus/Grafana for observability\r\n* Sharding or partitioning events across DBs for extreme scale\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabhinandanwadwa%2Foverbookr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabhinandanwadwa%2Foverbookr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabhinandanwadwa%2Foverbookr/lists"}