gedaraStay

Sri Lankan homestay & cultural-stay booking platform — connecting travelers with verified local hosts for authentic, community-rooted stays.

Table of Contents

• Overview
• Problem Statement
• Key Features
• Tech Stack
• System Architecture
• Project Structure
• Getting Started
• Environment Variables
• Running the Project Locally
• Available Scripts
• Database Setup
• API Overview
• Internationalization
• Screenshots
• Testing
• Known Limitations
• Future Improvements
• Contributing
• License

Overview

gedaraStay is a full-stack marketplace for booking verified Sri Lankan homestays, local homes, and cultural-immersion stays (village homestays, heritage homes, tea/spice farm stays, eco-nature stays). It supports three roles — guests, hosts (room owners), and admins — with a request-to-book reservation flow, Stripe test-mode payments, an internal settlement ledger, a multi-stage host/property verification pipeline, an in-app notification system, and a support ticketing system. The UI is available in English, Sinhala, and Tamil.

This project is currently packaged as a portfolio/demo application, not a live production marketplace (see Known Limitations).

Problem Statement

Peer-to-peer short-term rentals face a trust gap on both sides: guests can't easily verify a listing is real and safe, and platforms/hosts need a way to prove property ownership, identity, and local tourism-authority compliance before accepting money. gedaraStay addresses this by:

• Gating every listing behind identity verification → property verification → SLTDA (Sri Lanka Tourism Development Authority) compliance review → admin approval, before it can be booked
• Using a request-to-book model instead of instant booking, giving hosts a review window
• Recording every money movement (guest payment, platform commission, pending/paid host payout, refunds) in an auditable ledger with idempotency guarantees
• Centralizing disputes, cancellations, and safety concerns into a structured support-case workflow instead of ad-hoc messaging

Key Features

Guest-facing

• Search and filter stays by location, stay type, price, and guest count
• Rich stay detail pages (gallery, amenities, meals, experiences, house rules, safety info)
• Wishlist with re-orderable priority
• Request-to-book flow with live quote calculation and availability/blocked-date checks
• Secure checkout via Stripe (test mode)
• Booking management (view, cancel) and post-stay reviews with photos
• In-app notifications and a self-service support ticket center
• Full English / Sinhala / Tamil localization

Host-facing

• Guided onboarding: profile → identity verification → property verification → SLTDA compliance → stay submission
• Listing management (create/edit/pause/archive stays)
• Accept / decline / cancel / complete booking requests
• Revenue dashboard backed by the internal ledger (pending vs. paid payouts)
• Reply to guest reviews

Admin-facing

• Verification queues for host identity, property, compliance, and stay approval (approve / request changes / reject / suspend)
• User, stay, booking, and payment management dashboards
• Operations center: support case queue, refund review queue, payout queue, safety report queue
• Platform-wide ledger view (guest payments received, commission earned, payouts pending/paid, refunds issued)

Platform-wide

• JWT (httpOnly cookie) authentication with bcrypt password hashing
• Role-based access control (guest / roomOwner / admin) enforced at the route level
• Idempotent Stripe webhook processing (checkout.session.completed, checkout.session.expired, payment_intent.payment_failed)
• Automatic expiry of stale booking requests and unpaid payment windows
• Cloudinary-backed image uploads for profile photos, verification documents, and stay galleries
• Google Maps Places Autocomplete for accurate stay locations

Tech Stack

Frontend

• React 19 + Vite 8, React Router 7
• Zustand 5 (state management — one store per domain)
• Tailwind CSS 3, Framer Motion, lucide-react
• react-hook-form, react-select
• i18next / react-i18next (en / si / ta)
• Axios (cookie-credentialed HTTP client)
• @react-google-maps/api, jsPDF + jspdf-autotable

Backend

• Node.js (ESM) + Express 5
• MongoDB + Mongoose 9 (11 schemas)
• JWT (jsonwebtoken) + bcryptjs
• Helmet, CORS allow-list, express-rate-limit
• Multer (uploads) → Cloudinary SDK
• Stripe SDK (test mode) — Checkout + webhooks

Database: MongoDB (designed for MongoDB Atlas, works with any Mongo instance)

Auth/Security: httpOnly JWT cookies, bcrypt hashing, RBAC middleware (verifyToken, optionalVerifyToken, adminRoute, roomOwnerRoute, adminOrRoomOwnerRoute), startup rejection of placeholder JWT secrets, sensitive-data redaction in error responses and logs, masked document numbers in API output

Integrations: Stripe (payments), Cloudinary (media), Google Maps Places API (location)

Testing: Not currently configured (see Testing)

DevOps: No Dockerfile or CI pipeline is included; deployment is manual (see Known Limitations)

System Architecture

Request lifecycle example (booking → payment):

1. Guest submits a booking request → Booking created with status pending_host_confirmation, hostResponseDueAt set 48h out.
2. Host accepts → status becomes awaiting_guest_payment, paymentDueAt set (PAYMENT_DEADLINE_MINUTES, default 24h).
3. Guest starts checkout → a Stripe Checkout Session is created and a Payment record tracks it.
4. Stripe sends a signed webhook → verified, deduplicated via PaymentEvent, booking flips to confirmed, a LedgerEntry is posted, both parties are notified in-app.
5. If the host doesn't respond in time, or the guest doesn't pay in time, background checks (bookingLifecycle.js) automatically expire the booking and release the dates.

Project Structure

gedara-stay-main/
├── backend/
│   ├── controllers/        # Route handlers (auth, stay, booking, payment, host,
│   │                       #  admin verification, admin operations, ledger,
│   │                       #  notification, support, review, wishlist, user)
│   ├── models/              # Mongoose schemas (User, Stay, Booking, Payment,
│   │                        #  PaymentEvent, LedgerEntry, Review, Wishlist,
│   │                        #  Notification, SupportCase, VerificationDecision)
│   ├── routes/               # Express routers, one per resource
│   ├── middleware/           # JWT auth, RBAC guards, error handler, request logger
│   ├── services/             # notification.service.js, support.service.js
│   ├── utils/                 # booking lifecycle, quote calc, stay approval gates,
│   │                           # stay query builder, public stay serializer, JWT/cookie helper
│   ├── lib/                    # MongoDB connection, Cloudinary config
│   └── server.js               # Express app entry point
│
├── frontend/
│   ├── src/
│   │   ├── pages/               # Route-level pages (Home, BrowseStays, StayDetails,
│   │   │                        #  BookStay, HostOnboarding, RoomOwnerDashboard,
│   │   │                        #  adminDashboard, Wishlist, Notifications, Support…)
│   │   ├── components/
│   │   │   ├── admin/           # Admin dashboard UI (users, stays, bookings, payments)
│   │   │   ├── roomOwner/       # Host dashboard UI (listings, bookings, revenue)
│   │   │   ├── user/            # Guest-facing UI (profile, wishlist, reviews)
│   │   │   └── auth/            # Login, Signup, ProtectedRoute, PublicRoute
│   │   ├── stores/               # Zustand stores (auth, stay, booking, payment, ledger,
│   │   │                         #  wishlist, review, notification, support, host onboarding)
│   │   ├── i18n/                  # i18next config + en/si/ta translation JSON
│   │   ├── config/                 # roles.js, routes.js, brand.js
│   │   ├── lib/axios.js             # Configured Axios instance
│   │   └── App.jsx                  # Route definitions
│   └── provider/                     # GoogleMapsProvider / map context
│
├── scripts/
│   └── seed-demo-data.mjs             # Guarded demo data seeder
│
├── .env.example                        # Backend environment template
├── frontend/.env.example               # Frontend environment template
└── package.json                        # Backend/root dependencies & scripts

Getting Started

Prerequisites

• Node.js 20+ (required by Vite 8 / Mongoose 9 — not pinned in the repo, but this is the minimum you'll need)
• MongoDB instance (local or MongoDB Atlas)
• A Stripe account (test mode keys)
• A Cloudinary account
• A Google Maps API key with the Places API enabled

Installation

# Clone the repository
git clone <your-repo-url>
cd gedara-stay-main

# Install backend/root dependencies
npm install

# Install frontend dependencies
cd frontend
npm install
cd ..

Environment Variables

Copy the example files and fill in real values. Never commit actual .env files.

cp .env.example .env
cp frontend/.env.example frontend/.env

Backend — .env

Frontend — frontend/.env

Running the Project Locally

Start the backend:

npm run dev      # nodemon, auto-restarts on change
# or
npm start        # plain node

Start the frontend (in a second terminal):

cd frontend
npm run dev

• Backend: http://localhost:5000
• Frontend: http://localhost:5173
• Health check: GET http://localhost:5000/api/health

Available Scripts

Root / backend (package.json)

Frontend (frontend/package.json)

Database Setup

1. Create a MongoDB database (Atlas or local) and put the connection string in MONGO_URI.
2. On first npm start/npm run dev, Mongoose creates collections and indexes automatically from the schemas in backend/models/.
3. Optional — seed demo data:

   SEED_DEMO_CONFIRM=true npm run seed:demo

The script is intentionally guarded:

• Requires SEED_DEMO_CONFIRM=true
• Requires SEED_DEMO_TARGET=demo if NODE_ENV=production
• Refuses to run without a real MONGO_URI and a non-placeholder JWT_SECRET

It creates demo admin, roomOwner, and guest accounts (demo.admin@gedarastay.local, demo.host@gedarastay.local, demo.guest@gedarastay.local), sample stays, bookings, payments, ledger entries, support cases, and notifications. Passwords are either read from DEMO_ADMIN_PASSWORD / DEMO_HOST_PASSWORD / DEMO_GUEST_PASSWORD or randomly generated and printed to the console — rotate or discard these before any real deployment.

API Overview

Base URL: /api. All protected routes expect a token httpOnly cookie set by /auth/login or /auth/signup/*.

The full route definitions (including method, middleware, and validation) live in backend/routes/.

Internationalization

The UI ships with English, Sinhala, and Tamil translations via i18next, organized into namespaces (common, navigation, auth, stays, booking, dashboard, support, notifications, validation, accessibility) under frontend/src/i18n/locales/. Language preference is persisted to localStorage and applied to <html lang>. Note: per the maintainers' own README, Sinhala/Tamil translations are draft coverage and need human review before production use.

Screenshots

Add screenshots or a short demo GIF here once available.

Testing

No automated tests are currently included in this repository. There is no test runner configured in either package.json, and no *.test.js/*.spec.js files exist in the codebase. The only current quality checks are:

npm audit
npm audit --omit=dev

cd frontend
npm audit
npm audit --omit=dev
npm run lint
npm run build

Adding unit tests (e.g., Vitest for the frontend, Jest/Vitest + Supertest for the backend) and at least smoke-level integration tests for the booking → payment webhook flow would be a high-value next step.

Known Limitations

This project is explicitly positioned by its own codebase as a portfolio/demo build, not production-ready:

• Stripe is configured for test mode only — no live payment processing
• Real refunds, Stripe Connect, and actual host payouts are not implemented (payouts are tracked in the ledger as "pending" but require manual settlement)
• Email, SMS, push, and WebSocket notifications are not implemented — notifications are in-app/polled only
• Sinhala and Tamil translations are draft-quality and need native-speaker review
• No automated test suite or CI pipeline
• No Docker/containerization
• No LICENSE file despite license: ISC being declared
• A few housekeeping inconsistencies: root package.json name (test_mapsapi) doesn't match the product name, one stray .tsx file exists without TypeScript tooling configured, and the streamifier dependency is unused

Future Improvements

• Automated testing (unit + integration) and a CI pipeline
• Live Stripe payments, Stripe Connect for automated host payouts, and real refund processing
• Email/SMS notifications and real-time updates (WebSockets) for booking and payment status
• Professional review of Sinhala/Tamil translations
• Dockerize the backend and frontend for consistent local/prod environments
• Rename the root package for consistency and add a proper LICENSE file
• Expand automated accessibility (WCAG) auditing

Contributing

Contributions are welcome. To propose a change:

1. Fork the repository and create a feature branch (git checkout -b feature/your-feature)
2. Make your changes with clear, focused commits
3. Run npm run lint and npm run build in frontend/ before submitting
4. Open a pull request describing the change and its motivation

Please avoid committing real credentials, .env files, or production data in any PR.

License

This project is declared under the ISC License in package.json. Add a LICENSE file at the repository root with the full ISC (or your chosen license) text to make this legally explicit.

Built as a portfolio demonstration of a full-stack, multi-role marketplace with real-world concerns: verification workflows, payment reconciliation, and role-based access control.