A production-ready, full-stack Airbnb clone built with Next.js 15, FastAPI, and Clean Architecture.
- About
- Live Demo
- Features
- Tech Stack
- Architecture
- Folder Structure
- Database Design
- API Overview
- Booking Flow
- Installation
- Environment Variables
- Deployment
- Performance Optimizations
- Dark Mode
- Future Improvements
- Assignment Requirements Checklist
- Learning Outcomes
- Author
This project is a high-fidelity, full-stack Airbnb clone developed as part of a Software Development Engineer (SDE) hiring assignment.
Assignment Objective: Build a robust, scalable accommodation booking platform that demonstrates mastery of modern web development, API design, and database modeling.
Inspiration: Designed to closely mirror the aesthetic, UX, and performance of the actual Airbnb platform. It utilizes a highly decoupled architecture, ensuring that the backend can scale independently from the frontend.
Key Engineering Goals:
- Strict adherence to Clean Architecture on the backend.
- Advanced state management separating server cache (React Query) and UI state (Zustand).
- Responsive, accessible, and semantic Dark Mode theming.
- Production-ready deployment configuration.
- Frontend (Vercel): Airbnb Clone
- Backend API (Render): FastAPI Backend
- GitHub Repository: Akrishna4/airbnb-clone
- Browse listings: High-performance grid with skeleton loaders.
- Search: Dynamic location, date, and guest capacity search.
- Filters & Categories: Filter by property type, amenities, and price.
- Wishlist: Optimistic UI updates for favoriting properties.
- Listing Details: Comprehensive view including host info, amenities, and dynamic maps.
- Reviews: View aggregate ratings and individual paginated reviews.
- Availability Calendar: Prevent double-booking with disabled unavailable dates.
- Booking Flow: Sticky pricing widget adapting to date selection and guest count.
- Checkout: Simulated booking confirmation workflow.
- Trips: Manage upcoming, past, and cancelled reservations.
- Dark Mode: Fully semantic, system-aware dark theme.
- Responsive Design: Pixel-perfect adaptation from mobile to desktop.
- Dashboard: Track active listings.
- CRUD Listings: Create, read, update, and delete properties.
- Image Upload: Manage listing gallery.
- Booking Management: View reservations made by guests.
- FastAPI REST API: High-performance asynchronous Python backend.
- Modular Architecture: Decoupled Routers, Services, and Repositories.
- Type-safe APIs: End-to-end type safety using Pydantic and TypeScript.
- React Query caching: Efficient server state management and deduplication.
- Pagination: Offset-based pagination for listings and reviews.
- Validation: Strict runtime validation using Zod (Frontend) and Pydantic (Backend).
- Alembic Migrations: Version-controlled database schema.
- Optimistic UI: Immediate feedback on user actions (e.g., hearting a listing).
| Technology | Purpose |
|---|---|
| Next.js 15 (App Router) | Frontend Framework (SSR/SSG & Client components) |
| TypeScript | Static typing across both frontend and backend tooling |
| Tailwind CSS v4 | Utility-first styling and layout structure |
| shadcn/ui | Accessible, unstyled primitive UI components |
| React Query | Asynchronous server state caching and data fetching |
| Zustand | Synchronous global client state management |
| Framer Motion | Fluid page transitions and micro-interactions |
| FastAPI | High-performance Python REST API framework |
| SQLAlchemy 2.0 | ORM for database modeling and queries |
| SQLite / Alembic | Relational database storage and schema migrations |
| Pydantic v2 | Backend data validation and serialization |
The application implements a strict separation of concerns, heavily utilizing Clean Architecture patterns on the backend to decouple business logic from data access.
graph TD
Client[Browser / Mobile Client] -->|HTTPS Requests| Frontend[Next.js App Router]
Frontend -->|REST API| Backend[FastAPI Server]
subgraph Backend Architecture
Backend --> Routers[Routers Layer]
Routers --> Services[Service Layer]
Services --> Repositories[Repository Layer]
Repositories --> Database[(SQLite Database)]
end
airbnb-clone/
├── frontend/
│ ├── src/
│ │ ├── app/ # Next.js App Router (Pages & Layouts)
│ │ ├── components/ # Reusable UI components (Booking, Listings, etc.)
│ │ ├── hooks/ # Custom React hooks (React Query integrations)
│ │ ├── lib/ # Utilities, API clients, and constants
│ │ ├── store/ # Zustand global state (Auth, Search)
│ │ └── types/ # TypeScript interfaces
│ ├── public/ # Static assets
│ └── tailwind.config.ts
│
├── backend/
│ ├── app/
│ │ ├── core/ # Security, Config, Logging
│ │ ├── models/ # SQLAlchemy ORM Models
│ │ ├── repositories/ # Database access layer
│ │ ├── routers/ # FastAPI endpoint definitions
│ │ ├── schemas/ # Pydantic validation schemas
│ │ └── services/ # Business logic layer
│ ├── alembic/ # Database migrations
│ ├── tests/ # Pytest test suite
│ ├── main.py # Application entry point
│ └── requirements.txt
The relational database is normalized to ensure data integrity and query efficiency.
- Users: Manages authentication (email, hashed password), roles (guest vs. host), and profiles.
- Listings: Stores property details, pricing, location data, and configuration (max guests).
- Photos: One-to-many relationship with Listings for galleries.
- Bookings: Tracks reservation lifecycle, linking a User (Guest) to a Listing with date ranges.
- Reviews: Linked to a completed Booking, providing rating aggregates for Listings.
- Wishlist: Many-to-many mapping between Users and Listings.
- Amenities: Lookup table for available property features mapped via a join table.
All endpoints are prefixed with /api/v1
| Domain | Major Endpoints |
|---|---|
| Authentication | POST /auth/register, POST /auth/login, GET /auth/me |
| Listings | GET /listings, GET /listings/{id}, GET /listings/categories |
| Bookings | POST /bookings, GET /bookings/my-trips, PUT /bookings/{id}/cancel |
| Reviews | GET /listings/{id}/reviews, POST /reviews |
| Host | POST /listings, PUT /listings/{id}, DELETE /listings/{id}, GET /bookings/host |
| Wishlist | GET /favorites, POST /favorites/{listing_id} |
sequenceDiagram
participant User
participant Frontend
participant Backend
participant Database
User->>Frontend: Search Destination & Dates
Frontend->>Backend: GET /listings?city=...&check_in=...
Backend->>Database: Query Available Properties
Database-->>Backend: Results
Backend-->>Frontend: Listing Array
User->>Frontend: Click Listing
Frontend->>Backend: GET /listings/{id}/availability
Backend-->>Frontend: Unavailable Dates
User->>Frontend: Select Valid Dates & Guests
Frontend->>Frontend: Calculate Subtotal & Fees
User->>Frontend: Click Reserve (Checkout Modal)
User->>Frontend: Confirm Booking
Frontend->>Backend: POST /bookings
Backend->>Database: Validate & Insert Transaction
Database-->>Backend: Success
Backend-->>Frontend: Booking ID
Frontend->>User: Redirect to Trips Page
- Node.js 20+
- Python 3.11+
git clone https://github.com/Akrishna4/airbnb-clone.git
cd airbnb-clonecd backend
python -m venv venv
source venv/bin/activate # On Windows use `venv\Scripts\activate`
pip install -r requirements.txt
# Run migrations and seed database
alembic upgrade head
python -m app.seed.seed
# Start the server
uvicorn app.main:app --reload --port 8000cd frontend
npm install
# Start the development server
npm run dev| Variable | Description |
|---|---|
DATABASE_URL |
SQLite or PostgreSQL connection string |
SECRET_KEY |
Secret key for JWT encoding |
ALGORITHM |
JWT Algorithm (e.g., HS256) |
ACCESS_TOKEN_EXPIRE_MINUTES |
Token lifespan |
| Variable | Description |
|---|---|
NEXT_PUBLIC_API_URL |
URL to FastAPI backend (e.g., http://localhost:8000/api/v1) |
- Frontend (Vercel): Deployed automatically via Vercel GitHub integration. Leverages Next.js Edge caching and Server Components for optimal TTFB (Time to First Byte).
- Backend (Render): Hosted on Render utilizing a Python Web Service environment. Configure CORS in
config.pyto accept requests strictly from the Vercel domain.
- React Query: Deduplicates identical API requests across components and caches server state, preventing redundant network waterfalls.
- Next/Image: Automatic image optimization, WebP format conversion, and lazy loading for high-resolution listing galleries.
- Pagination: The backend restricts payload size via offset/limit queries, rendering only necessary DOM nodes on the frontend.
- Code Splitting: Next.js automatically chunks JavaScript bundles per route, ensuring the initial payload remains lightweight.
Dark Mode was implemented from the ground up to reflect a production-quality semantic design system:
next-themes: Provides system preference detection and hydration-safe theme toggling.- CSS Custom Properties: Tailwind configuration maps variables (e.g.,
bg-card,text-foreground) rather than hardcoded hex values. - Adaptability: Changing the theme seamlessly transitions all backgrounds, text, borders, and overlays without modifying React components logic.
While feature-complete for the assignment, a production iteration would include:
- PostgreSQL: Migrate from SQLite to Postgres for geospatial queries (PostGIS) and transaction concurrency.
- Stripe Integration: Replace the mock checkout modal with Stripe PaymentIntents.
- Docker & CI/CD: Containerize the FastAPI backend and implement GitHub Actions for automated pytest pipelines.
- Maps & Geo: Integrate Mapbox or Google Maps API for interactive listing exploration.
- Real-time Chat: Implement WebSockets for host-guest communication.
- Cloudinary / AWS S3: Offload image asset management to a dedicated CDN.
| Requirement | Status |
|---|---|
| Home Page | ✅ |
| Listing Details | ✅ |
| Booking Flow | ✅ |
| Trips Dashboard | ✅ |
| Host CRUD | ✅ |
| Wishlist | ✅ |
| Custom Filters / Search | ✅ |
| Reviews | ✅ |
| Dark Mode | ✅ |
| Responsive Layout | ✅ |
| Vercel Deployment | ✅ |
- System Design: Gained deep insights into abstracting logic between Routers, Services, and Repositories in FastAPI, making the codebase highly testable.
- Next.js Caching: Mastered the boundary between Client and Server Components in the Next.js App Router.
- State Management Synchronization: Learned how to effectively separate asynchronous server state (React Query) from synchronous UI state (Zustand) without prop-drilling or race conditions.
- Semantic Theming: Understood the importance of defining UI through semantic variables rather than hardcoded colors for scalable design systems.
[Ayush Krishna]
Full Stack Software Engineer
- 💼 LinkedIn: https://www.linkedin.com/in/ayush-krishna-b5b149304/
- 🐙 GitHub: https://github.com/Akrishna4
- ✉️ Email: akrishna1_be22@thapar.edu
This project is licensed under the MIT License - see the LICENSE file for details.