Travel Easy is a full-stack web application that lets travelers find and book a nearby locker to safely store their luggage or belongings for a few hours or a few days — and lets local businesses (cafes, hotels, shops, gyms, stations) rent out their spare storage space as registered "kiosks." Think of it as an online booking system for physical lockers: search a city or use your GPS location, pick a storage spot, reserve a locker, and get a QR code that unlocks it in person.
It's a two-sided marketplace, conceptually similar to products like LuggageHero or Bounce:
- Travelers need somewhere safe and nearby to leave a bag for a few hours between checkout and a flight, during a day of sightseeing, or between meetings — without lugging it around.
- Hosts/partners (a cafe, a shop, a hotel front desk, a gym) have spare space they can turn into income by listing it as a storage location with a fixed number of lockers.
Anyone traveling or moving around a city with luggage runs into the same friction repeatedly:
- Hotel checkout is at 11am but the flight isn't until 9pm — where does the bag go for the day?
- A day-tripper doesn't want to carry a backpack through a museum or a hike.
- Train/airport left-luggage counters are often full, expensive, or nonexistent in smaller stations.
- Independently, small businesses with unused space (a back room, an empty locker bank, a storage closet) have no easy way to monetize that space or advertise it to travelers who need it.
Travel Easy solves both sides at once: it gives travelers a searchable, bookable network of storage points near them, and gives small businesses a lightweight way to list spare space, define locker inventory (by size), set their own hourly/daily rates, and get paid for bookings — with QR-code-based check-in/check-out so nobody needs a special app or hardware to hand over a bag.
- Search. On the home page, a traveler searches by city/place name (autocomplete backed by OpenStreetMap) or taps "use my location" to search nearby by GPS, along with a date and search radius.
- Browse. Results show as a list and an interactive map of storage locations — cafes, kiosks, hotels, shops — each with its rating, hours, distance, and live count of available lockers.
- Pick a spot. Opening a location shows its address, opening hours, amenities (CCTV, staffed, near transit, etc.), and hourly/daily pricing.
- Book. In the booking dialog, the traveler picks a drop-off and pick-up time, how many bags, and hourly vs. daily pricing. The app finds an available locker at that location, reserves it, and creates the booking.
- Confirmation. The booking is confirmed instantly with a unique booking number and a QR code. A confirmation email is sent asynchronously (or logged locally in dev) via a dedicated notification microservice.
- Drop off / pick up. At the location, the traveler's QR code is scanned to unlock the locker — this is validated against the booking's time window and flips the booking to "active" and the locker to "occupied." Check-in/check-out and cancellation are also supported.
- Hosting. A business that wants to list space registers/logs in, then submits its address, location type, opening hours, amenities, pricing, and how many lockers of each size (small/medium/large/extra-large) it has. The location and its locker inventory are created together, and the location immediately becomes searchable.
| Layer | Technology |
|---|---|
| Frontend | React 19 + TypeScript, Vite, React Router v6, Tailwind CSS, Leaflet/react-leaflet (maps), react-day-picker |
| API gateway | Go 1.21 + Gin — validates JWT, injects identity headers, reverse-proxies to services |
| Microservices | Go 1.21, Gin, GORM — auth, location, booking, review (each owns its own database) |
| Notifications | Go microservice — email + SMS via Brevo (SMTP / Resend fallbacks) |
| Messaging | NATS — async events (booking.confirmed, review.created) |
| Auth | JWT (HS256), bcrypt password hashing |
| Databases | PostgreSQL 15 — one database per service (isolation) |
| Geocoding | OpenStreetMap Nominatim (proxied via location-service) |
| Local orchestration | Docker Compose |
| Deployment | Kubernetes (Kustomize base + dev/prod overlays) |
| CI/CD | GitHub Actions → GHCR images → kustomize/kubectl deploy |
graph TD
U[User Browser] -->|:5173| FE[Frontend: React + Vite]
FE -->|REST :8080/api/v1| GW[API Gateway: JWT, CORS, routing]
GW --> AUTH[auth-service :8001]
GW --> LOC[location-service :8002]
GW --> BOOK[booking-service :8003]
GW --> REV[review-service :8004]
BOOK -->|reserve locker| LOC
BOOK -->|user lookup| AUTH
REV -->|user lookup| AUTH
BOOK -. booking.confirmed .-> NATS((NATS))
REV -. review.created .-> NATS
NATS -. email + SMS .-> NOTIF[notification-service :8090]
NATS -. rating update .-> LOC
NOTIF -->|email + SMS| BREVO[(Brevo)]
LOC -->|proxy| NOMINATIM[(OSM Nominatim)]
AUTH --> DBA[(auth db)]
LOC --> DBL[(location db)]
BOOK --> DBB[(booking db)]
REV --> DBR[(review db)]
| Service | Container port | Host port (compose) |
|---|---|---|
| Frontend (Vite dev server) | 5173 | 5173 |
| API gateway | 8080 | 8080 |
| auth-service | 8001 | internal |
| location-service | 8002 | internal |
| booking-service | 8003 | internal |
| review-service | 8004 | internal |
| notification-service | 8090 | 8090 |
| NATS | 4222 | 4222 |
| Postgres (auth / location / booking / review) | 5432 | 5434 / 5435 / 5436 / 5437 |
/Home — city/place search with autocomplete, date/time picker, radius selector, "use my location," post-booking confirmation modal/locationsLocations — search results as a list + Leaflet map; book directly from a card/locations/:idLocationDetails — full details for one location (hours, amenities, rating, map, "Book" CTA)/bookingsBookings — the logged-in user's active bookings and history/profileProfile — login / register / account details / logout/hostHost — "list your space": register a new location and its locker inventory
From the repo root:
docker compose up -d --build- Frontend: http://localhost:5173
- API gateway health: http://localhost:8080/health
- API base (via gateway): http://localhost:8080/api/v1
- notification-service health: http://localhost:8090/health
- Postgres (per service, host): 5434 (auth), 5435 (location), 5436 (booking), 5437 (review)
docker compose up also runs one-shot *-migrate init containers (per service) that run the database migrations — and seed demo data for auth and location — before the services start serving traffic.
To stop:
docker compose downTo reset the database (drops all data):
docker compose down -v
docker compose up -d --buildKnown local-dev quirk: the
frontendservice indocker-compose.ymlbind-mounts the repo'snode_modulesinto a Linux container. If that folder was previously installed on a macOS host, Vite'srolldown-vitenative binding will be for the wrong platform and the container will fail to start with aCannot find native bindingerror. If that happens, just run the frontend natively on the host instead —npm install && npm run dev— it will talk to the already-running Dockerized backend onlocalhost:8080without any extra configuration.
Kubernetes manifests live in k8s/, structured with Kustomize:
k8s/base/— shared manifests for every service (namespace-agnostic)k8s/overlays/dev/— namespacetravel-easy-dev,:devimages, 1 replica,GIN_MODE=debugk8s/overlays/prod/— namespacetravel-easy-prod,:prodimages, 2 replicas, resource limits,GIN_MODE=release
All secrets are centralized in Kubernetes Secret objects (k8s/base/secret.yaml plus per-env secret-patch.yaml) and consumed via secretKeyRef — no secret is hardcoded in application code. DATABASE_URL is composed in-manifest from $(DB_PASSWORD) so the password stays only in the Secret.
# preview a rendered environment (no cluster needed)
kubectl kustomize k8s/overlays/dev
# apply to a cluster
kubectl apply -k k8s/overlays/dev # → namespace travel-easy-dev
kubectl apply -k k8s/overlays/prod # → namespace travel-easy-prodRun it free locally with kind:
kind create cluster --name travel-easy
docker compose build
for s in gateway auth-service location-service booking-service review-service notification-service; do
kind load docker-image travel-easy/$s --name travel-easy
done
kubectl apply -k k8s/overlays/dev
kubectl -n travel-easy-dev port-forward svc/gateway 8080:8080| Workflow | Trigger | Purpose |
|---|---|---|
.github/workflows/ci.yml |
PRs, push to dev/master |
Go build + vet (all services), frontend build, Docker builds, kustomize validation |
.github/workflows/cd-dev.yml |
push to dev |
Build & push images, deploy overlays/dev |
.github/workflows/cd-prod.yml |
push to master / tag v* |
Build & push, deploy overlays/prod (gated by the prod Environment) |
.github/workflows/deploy.yml |
reusable | Shared build-push + kustomize apply used by both CD workflows |
Images are published to GHCR (ghcr.io/<owner>/travel-easy-<service>). Deploys run kustomize edit set image + kubectl apply -k. To enable cluster deploys, add two repository secrets — KUBE_CONFIG_DEV and KUBE_CONFIG_PROD (base64-encoded kubeconfigs) — and add required reviewers to the prod GitHub Environment for a release approval gate. Without a kubeconfig the pipeline still builds and pushes images and simply skips the cluster apply.
- This file: end-to-end architecture, API, models, flows
- QUICK-START.md: step-by-step run instructions (more detailed)
k8s/: Kubernetes (Kustomize) manifests for dev & prod.github/workflows/: CI/CD pipelines
All API traffic goes through the gateway:
http://localhost:8080/api/v1
The gateway validates the JWT, injects X-User-Id / X-User-Email, and reverse-proxies to the owning service. The frontend reads the base from VITE_API_URL.
Every API response is wrapped in a consistent envelope:
{
"success": true,
"message": "...",
"data": {}
}Errors use:
{
"success": false,
"error": "..."
}- Auth uses JWT
- Protected routes require:
Authorization: Bearer <token>200/201for success400for validation errors401for auth failures404for missing resources500for server/db failures
POST /auth/registerPOST /auth/login
GET /profile
GET /locations(filters:city,type)GET /locations/nearby(query:lat,lon, optionalradiusin km)GET /locations/:idGET /locations/:id/lockers(query: optionalsize,status, defaultstatus=AVAILABLEis recommended)POST /locations(protected; creates a location + locker inventory)
Note: there is currently no role/partner approval model — any authenticated user can call POST /locations.
GET /lockers/available(query: optionalsize,locationId; preloads location)
GET /geocode/suggest(query:qrequired,limitoptional, max 8) — proxies OpenStreetMap Nominatim so the frontend can offer place-name autocomplete without exposing a third-party API directly to the browser.
POST /bookings(create booking)GET /bookings(list your bookings; query: optionalstatus)GET /bookings/:idPOST /bookings/:id/unlock(validate QR + log access)POST /bookings/:id/checkinPOST /bookings/:id/checkoutPOST /bookings/:id/cancel
GET /reviews?locationId=<id>(public) — list reviews for a locationPOST /reviews(protected) — submit{ locationId, rating (1-5), comment }; one review per user per location. Publishes areview.createdevent that updates the location's aggregate rating.
A standalone Go microservice. It consumes the booking.confirmed event from NATS (and also exposes POST /notify/booking-confirmed for direct calls) and sends the confirmation as email + SMS via Brevo, with SMTP and Resend as fallbacks. If no provider is configured it logs the message instead of failing — a safe default for local dev that never blocks a booking. The service is structured along SOLID lines: email.Sender / sms.Sender interfaces with per-provider implementations, wired together in main.go.
GET /healthPOST /notify/booking-confirmed
curl -sS -X POST http://localhost:8080/api/v1/auth/register \
-H 'Content-Type: application/json' \
-d '{
"email": "test@example.com",
"password": "password123",
"name": "John Doe",
"phoneNumber": "+4512345678"
}'curl -sS -X POST http://localhost:8080/api/v1/auth/login \
-H 'Content-Type: application/json' \
-d '{"email":"test@example.com","password":"password123"}'curl -sS 'http://localhost:8080/api/v1/locations?city=London'curl -sS 'http://localhost:8080/api/v1/locations/nearby?lat=51.5308&lon=-0.1238&radius=10'curl -sS 'http://localhost:8080/api/v1/geocode/suggest?q=Mumbai&limit=5'curl -sS 'http://localhost:8080/api/v1/locations/<locationId>/lockers?status=AVAILABLE'TOKEN='<paste token>'
curl -sS -X POST http://localhost:8080/api/v1/bookings \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TOKEN" \
-d '{
"locationId": "<locationId>",
"lockerId": "<lockerId>",
"startTime": "2026-03-03T10:00:00Z",
"duration": 4,
"rateType": "HOURLY"
}'curl -sS -X POST http://localhost:8080/api/v1/bookings/<bookingId>/unlock \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TOKEN" \
-d '{"qrCode":"<booking.qrCode>"}'POST /locations creates the location and also generates lockers (numbered 1..N).
curl -sS -X POST http://localhost:8080/api/v1/locations \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TOKEN" \
-d '{
"name": "King's Cross Luggage Storage",
"type": "STORE",
"address": "King's Cross, London",
"city": "London",
"country": "United Kingdom",
"latitude": 51.5308,
"longitude": -0.1238,
"openingTime": "07:00",
"closingTime": "23:00",
"isOpen24Hours": false,
"amenities": ["CCTV", "Near transit"],
"hourlyRate": 5,
"dailyRate": 20,
"lockers": {"small": 4, "medium": 4, "large": 2, "xlarge": 1}
}'erDiagram
USERS {
uuid id PK
string email UK
string name
boolean is_active
timestamp created_at
}
LOCATIONS {
uuid id PK
string name
string type
string city
string country
float latitude
float longitude
float hourly_rate
float daily_rate
boolean is_active
}
LOCKERS {
uuid id PK
uuid location_id FK
string locker_number
string size
string status
boolean is_operational
}
BOOKINGS {
uuid id PK
uuid user_id FK
uuid location_id FK
uuid locker_id FK
string booking_number UK
timestamp start_time
timestamp end_time
string rate_type
float total_price
string status
string qr_code UK
}
ACCESS_LOGS {
uuid id PK
uuid booking_id FK
string action
timestamp timestamp
}
USERS ||--o{ BOOKINGS : places
LOCATIONS ||--o{ LOCKERS : contains
LOCATIONS ||--o{ BOOKINGS : receives
LOCKERS ||--o{ BOOKINGS : allocated_to
BOOKINGS ||--o{ ACCESS_LOGS : logs
classDiagram
class users {
+uuid id (PK)
+string email (UNIQUE)
+string password_hash
+string name
+string? phone_number
+bool is_active
+timestamp created_at
+timestamp updated_at
}
class locations {
+uuid id (PK)
+string name
+LocationType type
+string address
+string city
+string country
+float latitude
+float longitude
+string opening_time
+string closing_time
+bool is_open_24_hours
+text amenities_json
+float hourly_rate
+float daily_rate
+bool is_active
}
class lockers {
+uuid id (PK)
+uuid location_id (FK)
+string locker_number
+LockerSize size
+LockerStatus status
+bool is_operational
}
class bookings {
+uuid id (PK)
+uuid user_id (FK)
+uuid location_id (FK)
+uuid locker_id (FK)
+string booking_number (UNIQUE)
+timestamp start_time
+timestamp? end_time
+RateType rate_type
+float base_price
+float total_price
+BookingStatus status
+string qr_code (UNIQUE)
+PaymentStatus payment_status
}
class access_logs {
+uuid id (PK)
+uuid booking_id (FK)
+AccessAction action
+timestamp timestamp
+string? method
+string? device_info
}
users "1" --> "0..*" bookings : user_id
locations "1" --> "0..*" lockers : location_id
locations "1" --> "0..*" bookings : location_id
lockers "1" --> "0..*" bookings : locker_id
bookings "1" --> "0..*" access_logs : booking_id
class LocationType {
<<enumeration>>
KIOSK
GYM
CLUB
SCHOOL
HOTEL
CAFE
STORE
OTHER
}
class LockerSize {
<<enumeration>>
SMALL
MEDIUM
LARGE
XLARGE
}
class LockerStatus {
<<enumeration>>
AVAILABLE
OCCUPIED
RESERVED
MAINTENANCE
OUT_OF_SERVICE
}
class RateType {
<<enumeration>>
HOURLY
DAILY
MULTI_DAY
}
class BookingStatus {
<<enumeration>>
PENDING
CONFIRMED
ACTIVE
COMPLETED
CANCELLED
EXPIRED
}
class PaymentStatus {
<<enumeration>>
PENDING
PAID
PARTIALLY_PAID
REFUNDED
FAILED
}
class AccessAction {
<<enumeration>>
LOCK
UNLOCK
OPEN
CLOSE
}
The canonical schema is defined in backend/internal/models/models.go and migrated via backend/cmd/migrate/main.go.
-
User
emailunique,passwordhashed (bcrypt)- has many
bookings
-
Location — a registered storage "kiosk" (also modeled as a cafe, hotel, gym, school, club, or generic store)
type:KIOSK | GYM | CLUB | SCHOOL | HOTEL | CAFE | STORE | OTHER- geo:
latitude,longitude - pricing:
hourlyRate,dailyRate amenitiesis stored as a JSON array string (e.g.["CCTV","Staffed"])
-
Locker — one physical storage unit at a location
- belongs to
locationId size:SMALL | MEDIUM | LARGE | XLARGEstatus:AVAILABLE | RESERVED | OCCUPIED | MAINTENANCE | OUT_OF_SERVICE
- belongs to
-
Booking — a reservation of one locker for a time window
- belongs to
userId,locationId,lockerId - time:
startTime,endTime - pricing:
rateType+totalPrice - access:
qrCode, andaccessLogs - status:
PENDING | CONFIRMED | ACTIVE | COMPLETED | CANCELLED | EXPIRED
- belongs to
-
AccessLog — an audit trail entry for physical access to a locker
- belongs to
bookingId - action:
LOCK | UNLOCK | OPEN | CLOSE - method is currently logged as
QR_SCANfor unlock
- belongs to
Pricing is calculated server-side (never trust the client) — see backend/internal/services/booking_service.go:
HOURLY:ceil(hours) * hourlyRateDAILY:ceil(hours/24) * dailyRateMULTI_DAY: daily pricing with a 10% discount for > 1 day
The frontend's BookingDialog mirrors this formula only to show a live price estimate before submitting — the server always recomputes and is the source of truth.
sequenceDiagram
participant U as User
participant FE as Frontend
participant API as Backend API
participant DB as Postgres
participant N as notification-service
U->>FE: Search by city or use GPS
FE->>API: GET /locations or /locations/nearby
API->>DB: Query active locations
DB-->>API: Locations
API-->>FE: Locations list
U->>FE: Select location
FE->>API: GET /locations/:id/lockers?status=AVAILABLE
API->>DB: Query lockers
DB-->>API: Available lockers
API-->>FE: Lockers
U->>FE: Choose locker + duration
FE->>API: POST /bookings (JWT)
API->>DB: Create booking + reserve locker
DB-->>API: Booking
API-->>FE: Booking + QR code
API-)N: POST /notify/booking-confirmed (fire-and-forget)
N-->>N: Send/log confirmation email
sequenceDiagram
participant U as User
participant FE as Frontend
participant API as Backend API
participant DB as Postgres
U->>FE: Scan/enter QR code
FE->>API: POST /bookings/:id/unlock (JWT + qrCode)
API->>DB: Validate booking + qrCode
API->>DB: Insert access_log(UNLOCK)
API->>DB: Set booking ACTIVE + locker OCCUPIED (first unlock)
DB-->>API: OK
API-->>FE: { action: UNLOCK }
flowchart TD
H[Host/Partner] --> A[Register/Login]
A -->|JWT| C[Create Location + Lockers]
C --> L[Location visible in search]
L --> B[Users can book lockers]
On docker compose up, the auth-migrate and location-migrate init containers run ./migrate && ./seed.
The seed creates:
- Test user:
test@example.com/password123 - ~20 demo locations across multiple cities (Copenhagen, Bengaluru, New Delhi, Mumbai, London, New York) with small locker inventories and a sample booking
If you update the seed code and don't see changes, rebuild and re-run the init containers:
docker compose build auth-service location-service
docker compose run --rm auth-migrate
docker compose run --rm location-migrateThis section is a contract-style view of the REST API: required fields, types, and response shapes.
Envelope (all endpoints):
type ApiEnvelope<T> =
| { success: true; message?: string; data: T }
| { success: false; error: string }Auth header (protected endpoints):
Authorization: Bearer <jwt>Request:
type RegisterRequest = {
email: string
password: string // min length 6
name: string
phoneNumber?: string
}Response data:
type RegisterResponse = {
user: {
id: string
email: string
name: string
phoneNumber?: string | null
profileImageUrl?: string | null
isActive: boolean
createdAt: string
updatedAt: string
}
token: string
}Request:
type LoginRequest = {
email: string
password: string
}Response data: same shape as RegisterResponse.
Response data:
type ProfileResponse = {
id: string
email: string
name: string
phoneNumber?: string | null
profileImageUrl?: string | null
isActive: boolean
createdAt: string
updatedAt: string
}Query params:
type LocationsQuery = {
city?: string // substring match (ILIKE)
type?: 'KIOSK' | 'GYM' | 'CLUB' | 'SCHOOL' | 'HOTEL' | 'CAFE' | 'STORE' | 'OTHER'
}Response data:
type LocationsListResponse = {
count: number
locations: Location[]
}
type Location = {
id: string
name: string
type: LocationsQuery['type']
address: string
city: string
state?: string | null
zipCode?: string | null
country: string
latitude: number
longitude: number
openingTime?: string
closingTime?: string
isOpen24Hours: boolean
phoneNumber?: string | null
email?: string | null
description?: string | null
imageUrl?: string | null
amenities: string // JSON array string
hourlyRate: number
dailyRate: number
isActive: boolean
rating: number
totalReviews: number
createdAt: string
updatedAt: string
}Query params:
type NearbyQuery = {
lat: number
lon: number
radius?: number // km, default 10
}Response data:
type NearbyLocationsResponse = {
count: number
locations: Array<Location & { distance: number; availableLockers: number }>
}Response data:
type LocationDetailResponse = {
location: Location
availableLockers: number
}Query params:
type LocationLockersQuery = {
size?: 'SMALL' | 'MEDIUM' | 'LARGE' | 'XLARGE'
status?: 'AVAILABLE' | 'OCCUPIED' | 'RESERVED' | 'MAINTENANCE' | 'OUT_OF_SERVICE' // default AVAILABLE
}Response data:
type LockersResponse = {
count: number
lockers: Array<{
id: string
locationId: string
lockerNumber: string
size: LocationLockersQuery['size']
status: LocationLockersQuery['status']
isOperational: boolean
createdAt?: string
updatedAt?: string
}>
}Creates a location and generates locker inventory.
Request:
type CreateLocationRequest = {
name: string
type: LocationsQuery['type']
address: string
city: string
state?: string
zipCode?: string
country: string
latitude: number
longitude: number
openingTime?: string
closingTime?: string
isOpen24Hours?: boolean
phoneNumber?: string
email?: string
description?: string
imageUrl?: string
amenities?: string[]
hourlyRate?: number
dailyRate?: number
lockers: {
small: number
medium: number
large: number
xlarge: number
}
}Response data:
type CreateLocationResponse = { location: Location }Query params:
type AvailableLockersQuery = {
size?: 'SMALL' | 'MEDIUM' | 'LARGE' | 'XLARGE'
locationId?: string
}Response data:
type AvailableLockersResponse = {
count: number
lockers: Array<{
id: string
locationId: string
lockerNumber: string
size: AvailableLockersQuery['size']
status: 'AVAILABLE'
isOperational: boolean
location?: Location
}>
}Query params:
type GeocodeSuggestQuery = {
q: string // required, place/city name to search
limit?: number // optional, 1-8, default 5
}Response data:
type GeocodeSuggestResponse = {
count: number
suggestions: Array<{
lat: number
lon: number
title: string // first comma-segment of the display name
subtitle: string // remaining comma-segments
displayName: string // full Nominatim display name
}>
}Request:
type CreateBookingRequest = {
locationId: string
lockerId: string
startTime: string // RFC3339
duration: number // hours (can be float)
rateType: 'HOURLY' | 'DAILY' | 'MULTI_DAY'
}Response data:
type Booking = {
id: string
userId: string
locationId: string
lockerId: string
bookingNumber: string
startTime: string
endTime?: string | null
rateType: 'HOURLY' | 'DAILY' | 'MULTI_DAY'
basePrice: number
additionalCharges: number
totalPrice: number
status: 'PENDING' | 'CONFIRMED' | 'ACTIVE' | 'COMPLETED' | 'CANCELLED' | 'EXPIRED'
qrCode: string
qrCodeImageUrl?: string | null
checkInTime?: string | null
checkOutTime?: string | null
paymentStatus: 'PENDING' | 'PAID' | 'PARTIALLY_PAID' | 'REFUNDED' | 'FAILED'
paymentMethod?: string | null
transactionId?: string | null
notes?: string | null
cancellationReason?: string | null
createdAt: string
updatedAt: string
location?: Location
locker?: {
id: string
locationId: string
lockerNumber: string
size: 'SMALL' | 'MEDIUM' | 'LARGE' | 'XLARGE'
status: 'AVAILABLE' | 'OCCUPIED' | 'RESERVED' | 'MAINTENANCE' | 'OUT_OF_SERVICE'
isOperational: boolean
}
accessLogs?: Array<{
id: string
bookingId: string
action: 'LOCK' | 'UNLOCK' | 'OPEN' | 'CLOSE'
timestamp: string
method?: string | null
deviceInfo?: string | null
}>
}Query params:
type BookingsQuery = { status?: Booking['status'] }Response data:
type BookingsListResponse = { count: number; bookings: Booking[] }Response data: Booking (includes accessLogs).
Request:
type UnlockRequest = { qrCode: string }Response data:
type UnlockResponse = { action: 'UNLOCK'; timestamp: string }Response data:
type CheckInResponse = { checkInTime: string }Response data:
type CheckOutResponse = { checkOutTime: string }Request:
type CancelRequest = { reason?: string }Response data: null.
Request:
type BookingNotification = {
bookingNumber: string
userEmail: string
userName: string
locationName: string
locationAddress: string
startTime: string // RFC3339
endTime: string // RFC3339
bags: number
rateType: 'HOURLY' | 'DAILY' | 'MULTI_DAY'
totalPrice: number
qrCode: string
}Response: { "status": "sent" } (or logs the email and still returns success if RESEND_API_KEY is unset).
| Variable | Used by | Default | Purpose |
|---|---|---|---|
DATABASE_URL |
backend | (compose-provided) | Postgres connection string |
JWT_SECRET |
backend | your-super-secret-jwt-key-change-in-production |
Signs/validates auth tokens — change in production |
JWT_EXPIRY |
backend | 168h (7 days) |
Token lifetime |
PORT |
backend / notification-service | 8080 / 8090 |
Listen port |
GIN_MODE |
backend / notification-service | release |
Gin logging mode |
CORS_ORIGIN |
backend | http://localhost:5173 |
Allowed frontend origin |
RESEND_API_KEY |
notification-service | (empty) | Resend transactional email API key; if unset, emails are logged instead of sent |
RESEND_FROM |
notification-service | Travel Easy <onboarding@resend.dev> |
From-address for confirmation emails |
VITE_API_URL |
frontend | http://localhost:8080/api/v1 |
Base URL the frontend calls |
If you see errors around gen_random_uuid(), enable the Postgres extension:
CREATE EXTENSION IF NOT EXISTS pgcrypto;The backend allows the origin set in CORS_ORIGIN (default http://localhost:5173), plus http://localhost:3000. If you need a different origin, update backend/cmd/server/main.go.
See the Quick start note above — run npm run dev on the host instead of inside the frontend Docker service.
- No partner/role model. Any authenticated user can call
POST /locationsand start hosting — there's no approval workflow to distinguish verified partners from regular travelers. - No payment integration.
paymentStatus/paymentMethod/transactionIdexist on theBookingmodel but nothing currently drives them from a real payment provider. - Client-side price preview only. The frontend recomputes the price formula for display before submitting a booking; the server is always the source of truth and recalculates independently.
.
├── src/ # React frontend
│ ├── pages/ # Home, Locations, LocationDetails, Bookings, Profile, Host
│ ├── components/ # Layout, BookingDialog
│ ├── services/ # api, auth, storage (locations/lockers/bookings), geocode
│ └── types/ # shared domain types
├── notification-service/ # Go + Gin microservice for booking confirmation emails
└── backend/ # Go API (Gin + GORM)
├── cmd/ # server / migrate / seed
└── internal/ # handlers, models, services, middleware, utils