SpotSync

SpotSync is a high-performance parking spot reservation booking API built in Go. It is designed to be highly reliable, featuring pessimistic row locking (FOR UPDATE) to handle concurrent bookings safely without double-booking under load.

---

🔗 Deployment Details

• Live URL: https://spotsync-3ync.onrender.com

---

✨ Features

• Concurrency-Safe Bookings: Implements pessimistic locking to prevent race conditions when multiple users try to book the last available parking spot simultaneously.
• Role-Based Access Control: Standard JWT authentication protecting routes; specific actions (like creating zones or listing all bookings) are restricted to the admin role.
• Database Preloading: Nested models are fully resolved using GORM preloads to fetch user and zone details cleanly in one query.
• Automatic Migrations: Integrated GORM schema auto-migrations on startup.

---

🛠️ Tech Stack

• Language: Go (v1.26.2+)
• Web Framework: Echo (v5.2.1)
• ORM: GORM (v1.31.2)
• Database: PostgreSQL (Neon Serverless DB)
• Token Authentication: JWT (github.com/golang-jwt/jwt/v5)
• Hot-Reloading: Air (v1.65.3)

---

🏗️ Architecture & Layer Interaction

SpotSync follows a clean, layered modular architecture separating concerns into components.

graph TD
    Client[HTTP Client / Postman] -->|JSON & JWT Token| Router[Echo Router / Middleware]
    Router -->|Authenticate & Check Roles| Handler[Handlers / Controllers]
    Handler -->|Bind & Validate Request DTOs| Service[Services / Business Logic]
    Service -->|Process & Map Entities| Repository[Repositories / Data Access]
    Repository -->|Pessimistic Locks & Queries| DB[(Neon PostgreSQL Database)]

Loading

• Router & Middleware: Intercepts requests, validates JWT cryptographic signatures, extracts caller identities, and verifies role claims (e.g., checks if the user is an admin).
• Handlers (Controllers): Handles HTTP requests/responses, validates payloads via go-playground/validator, and forwards data to the service layer.
• Services: Houses business logic rules, coordinates domain operations, hashes passwords with bcrypt, and maps DB models to DTOs.
• Repositories (Data Access): Interacts with PostgreSQL using GORM. Uses transactions and pessimistic locks (FOR UPDATE) to serialize writes on key tables during booking.
• Models: Represents GORM schema models mapping to the database tables.

---

🚀 Setup & Local Installation

Prerequisites

• Go installed on your local machine (version 1.26.2 or higher).
• A PostgreSQL instance (either local or cloud-hosted on Neon DB).

Steps

1. Clone the Repository:

   git clone https://github.com/FajlaRabby24/spotsync.git
   cd spotsync

2. Install Dependencies:

   go mod tidy

3. Configure Environment Variables: Create a .env file at the root of the project:

   PORT=5000
   DSN="postgresql://username:password@your-host:5432/spotsync?sslmode=require"
   JWT_SECRET="your_secure_jwt_secret_key"

4. Run the Server:

   • Using Go run:

     go run cmd/main.go

   • Using Air (For hot reloading):

     air

---

📋 API Endpoints

Authentication & Users

Endpoint	Method	Access	Description
/api/v1/auth/register	POST	Public	Register a new user (role defaults to driver)
/api/v1/auth/login	POST	Public	Log in and receive a JWT Bearer Token

Parking Zones

Endpoint	Method	Access	Description
/api/v1/zones	GET	Public	Fetch all parking zones and their available spots
/api/v1/zones/:id	GET	Public	Fetch detailed information of a single parking zone
/api/v1/zones	POST	Admin	Create a new parking zone (requires admin role)

Reservations

Endpoint	Method	Access	Description
/api/v1/reservations	POST	Authenticated	Create a spot reservation
/api/v1/reservations	GET	Authenticated	Get all active/past reservations for the logged-in user
/api/v1/reservations/all	GET	Admin	Retrieve all reservations in the system with preloaded user/zone details
/api/v1/reservations/:id	DELETE	Owner	Cancel an active reservation (verified owner check)