# abidev2003/the-wild-oasis-website architecture

> Architecture diagram of the GitHub repository abidev2003/the-wild-oasis-website, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abidev2003/the-wild-oasis-website
- Repository: https://github.com/abidev2003/the-wild-oasis-website

## Overview

#### Purpose and Runtime
This is a Next.js App Router application for discovering cabins and managing a guest booking lifecycle: authentication, reservations, checkout, reviews, wishlists, and trip itineraries. The primary UI entry is `app/page.js`; global composition is in `app/layout.js`. It runs as a Next.js server/client application, with deploy-oriented configuration in `next.config.mjs` and request interception in `proxy.js`.

#### Route and UI Composition
Route segments organize the product by domain:
- Cabin discovery and detail: `app/cabins/page.js`, `app/cabins/[cabinId]/page.js`
- Auth and recovery: `app/login/page.js`, `app/signup/page.js`, `app/forgot-password/page.js`
- Account area: `app/account/layout.js`, `app/account/reservations/page.js`, `app/account/wishlist/page.js`
- Booking payment: `app/checkout/[bookingId]/page.js`, `app/cabins/thankyou/page.js`

Reusable components under `app/_components` implement the shell, cabin catalogue, booking forms, account views, and interactive widgets. `Header.js`, `Navigation.js`, and `SideNavigation.js` define the shared navigation boundary.

#### Data Access and Domain Actions
Server-side data and mutations are centralized in:
- `app/_lib/data-service.js`
- `app/_lib/actions.js`
- `app/_lib/booking-logic.js`

Pages and forms should cross into these modules rather than directly coupling UI to persistence. Booking-specific rules are separated from general action orchestration, indicating a lifecycle where cabin selection and date input become a validated reservation, then transition into editing, checkout, or deletion flows.

#### Supabase Persistence and Authorization
Supabase is the primary backend for authentication and relational application data. Client/server access is separated by:
- `app/_lib/supabase/client.js`
- `app/_lib/supabase/server.js`
- `app/_lib/supabase/middleware.js`

The schema evolves through ordered migrations in `supabase/migrations`, including guest identity/RLS (`0001_guests_auth_id.sql`, `0002_rls_policies.sql`), reviews and wishlists (`0006_reviews.sql`, `0007_wishlists.sql`), payments, itineraries, conversations, search, and availability RPCs. This makes database authorization and RPC boundaries architecturally important, rather than merely UI-level access controls.

#### Identity and Protected Account Flow
Authentication behavior is encapsulated in `app/_lib/auth.js` and completed through `app/auth/callback/route.js`. Account pages are grouped beneath `app/account`, with a dedicated layout likely serving as the protected-area boundary. Authentication UI includes login, signup, password recovery, password update, and profile update components; account operations should rely on server-side auth/session context rather than browser-only state.

#### Reservations, Checkout, and Payment
The reservation flow spans cabin detail, booking UI, account management, and checkout:
- `app/_components/ReservationForm.js`
- `app/account/reservations/edit/[bookingId]/page.js`
- `app/checkout/[bookingId]/page.js`

`app/_lib/razorpay.js` identifies Razorpay as the payment integration, while `supabase/migrations/0008_payment_fields.sql` persists payment state. The booking identifier is the control-flow handoff between reservation creation/editing and checkout; the thank-you route is the post-payment destination.

#### AI, Search, and Stateful Client Features
Two server API boundaries expose automation features:
- `app/api/chat/route.js`
- `app/api/recommend/route.js`

These are backed by `app/_lib/groq.js`, with rate limiting in `app/_lib/rate-limit.js`; chat persistence is supported by `supabase/migrations/0011_conversations.sql`. Cabin search parsing and recommendation logic are separated in `app/_lib/parse-search.js` and `app/_lib/suggestions.js`, with database search support in `00012_search.sql`. Client-wide state is limited to explicit contexts: `app/_context/ReservationContext.js` and `app/_context/ThemeContext.js`.

Main entry points: [`app/_lib/actions.js`](https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/_lib/actions.js) (Domain actions), [`app/_lib/auth.js`](https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/_lib/auth.js) (Session auth), [`app/_lib/supabase/server.js`](https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/_lib/supabase/server.js) (Supabase access), [`app/checkout/[bookingId]/page.js`](https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/checkout/%5BbookingId%5D/page.js) (Checkout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Next.js UI"]
  node_app_shell["App shell<br/>Next.js layout<br/>[layout.js]"]
  node_home["Discovery home<br/>page<br/>[page.js]"]
  node_cabins["Cabin catalogue<br/>pages<br/>[page.js]"]
  node_booking_ui["Reservation form<br/>[ReservationForm.js]"]
  node_account["Protected account<br/>layout and pages<br/>[layout.js]"]
  node_reservation_edit["Reservation editing<br/>page<br/>[page.js]"]
  node_checkout["Checkout<br/>page<br/>[page.js]"]
  node_thank_you["Payment confirmation<br/>page<br/>[page.js]"]
  node_auth_ui["Authentication UI<br/>pages<br/>[page.js]"]
  node_navigation["Shared navigation<br/>components<br/>[Header.js]"]
  node_client_context["Client contexts<br/>React contexts"]
end

subgraph group_domain["Server Domain"]
  node_data_service["Data service<br/>server data access<br/>[data-service.js]"]
  node_actions["Domain actions<br/>server actions<br/>[actions.js]"]
  node_booking_logic["Booking rules<br/>domain logic<br/>[booking-logic.js]"]
  node_auth["Session auth<br/>auth service<br/>[auth.js]"]
end

subgraph group_platform["Supabase &amp; Integrations"]
  node_supabase_access["Supabase access<br/>client/server adapters<br/>[server.js]"]
  node_supabase_db[("Supabase database<br/>relational database")]
  node_auth_callback["Auth callback<br/>route handler<br/>[route.js]"]
  node_razorpay{{"Razorpay<br/>payment integration<br/>[razorpay.js]"}}
  node_ai_api["AI APIs<br/>route handlers<br/>[route.js]"]
  node_ai_services{{"AI search services<br/>AI and search logic<br/>[groq.js]"}}
  node_request_proxy["Request proxy<br/>request interception<br/>[proxy.js]"]
end

node_app_shell -->|"renders"| node_navigation
node_home -->|"discovery flow"| node_cabins
node_cabins -->|"selects cabin"| node_booking_ui
node_booking_ui -->|"creates reservation"| node_actions
node_client_context -->|"reservation state"| node_booking_ui
node_account -->|"manages bookings"| node_reservation_edit
node_reservation_edit -->|"updates reservation"| node_actions
node_actions -->|"applies rules"| node_booking_logic
node_actions -->|"persists changes"| node_data_service
node_data_service -->|"queries and RPCs"| node_supabase_access
node_supabase_access -->|"data and RLS"| node_supabase_db
node_auth_ui -->|"completes sign-in"| node_auth_callback
node_auth_callback -->|"establishes session"| node_auth
node_account -->|"requires session"| node_auth
node_auth -->|"uses server session"| node_supabase_access
node_request_proxy -->|"request session"| node_auth
node_checkout -->|"loads booking"| node_actions
node_checkout -->|"initiates payment"| node_razorpay
node_razorpay -->|"payment state"| node_supabase_db
node_checkout -->|"payment complete"| node_thank_you
node_ai_api -->|"automation requests"| node_ai_services
node_ai_services -->|"search and conversations"| node_supabase_access

click node_app_shell "https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/layout.js"
click node_home "https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/page.js"
click node_cabins "https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/cabins/page.js"
click node_booking_ui "https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/_components/ReservationForm.js"
click node_account "https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/account/layout.js"
click node_reservation_edit "https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/account/reservations/edit/%5BbookingId%5D/page.js"
click node_checkout "https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/checkout/%5BbookingId%5D/page.js"
click node_thank_you "https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/cabins/thankyou/page.js"
click node_auth_ui "https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/login/page.js"
click node_navigation "https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/_components/Header.js"
click node_client_context "https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/_context/ReservationContext.js"
click node_data_service "https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/_lib/data-service.js"
click node_actions "https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/_lib/actions.js"
click node_booking_logic "https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/_lib/booking-logic.js"
click node_auth "https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/_lib/auth.js"
click node_supabase_access "https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/_lib/supabase/server.js"
click node_supabase_db "https://github.com/abidev2003/the-wild-oasis-website/tree/master/supabase/migrations"
click node_auth_callback "https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/auth/callback/route.js"
click node_razorpay "https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/_lib/razorpay.js"
click node_ai_api "https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/api/chat/route.js"
click node_ai_services "https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/_lib/groq.js"
click node_request_proxy "https://github.com/abidev2003/the-wild-oasis-website/blob/master/proxy.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_shell,node_home,node_cabins,node_booking_ui,node_account,node_reservation_edit,node_checkout,node_thank_you,node_auth_ui,node_navigation,node_client_context toneBlue
class node_data_service,node_actions,node_booking_logic,node_auth toneAmber
class node_supabase_access,node_supabase_db,node_auth_callback,node_razorpay,node_ai_api,node_ai_services,node_request_proxy toneMint
```

## Components

### Next.js UI

App Router pages, layouts, and shared client features.

- [App shell](https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/layout.js): Next.js layout · `app/layout.js`
- [Discovery home](https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/page.js): page · `app/page.js`
- [Cabin catalogue](https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/cabins/page.js): pages · Cabin listing and detail routes. · `app/cabins/page.js`
- [Reservation form](https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/_components/ReservationForm.js): Captures dates and cabin reservation intent. · `app/_components/ReservationForm.js`
- [Protected account](https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/account/layout.js): layout and pages · Reservations and wishlist area. · `app/account/layout.js`
- [Reservation editing](https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/account/reservations/edit/%5BbookingId%5D/page.js): page · `app/account/reservations/edit/[bookingId]/page.js`
- [Checkout](https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/checkout/%5BbookingId%5D/page.js): page · Uses booking ID as the payment handoff. · `app/checkout/[bookingId]/page.js`
- [Payment confirmation](https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/cabins/thankyou/page.js): page · `app/cabins/thankyou/page.js`
- [Authentication UI](https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/login/page.js): pages · Login, signup, and recovery routes. · `app/login/page.js`
- [Shared navigation](https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/_components/Header.js): components · `app/_components/Header.js`
- [Client contexts](https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/_context/ReservationContext.js): React contexts · Reservation and theme state. · `app/_context/ReservationContext.js`

### Server Domain

Centralized server-side data, actions, and booking rules.

- [Data service](https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/_lib/data-service.js): server data access · UI persistence boundary. · `app/_lib/data-service.js`
- [Domain actions](https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/_lib/actions.js): server actions · Orchestrates mutations and lifecycle transitions. · `app/_lib/actions.js`
- [Booking rules](https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/_lib/booking-logic.js): domain logic · Validates and manages reservation lifecycle rules. · `app/_lib/booking-logic.js`
- [Session auth](https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/_lib/auth.js): auth service · `app/_lib/auth.js`

### Supabase & Integrations

Identity, relational data, authorization, payments, and AI services.

- [Supabase access](https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/_lib/supabase/server.js): client/server adapters · Separate browser and server database clients. · `app/_lib/supabase/server.js`
- [Supabase database](https://github.com/abidev2003/the-wild-oasis-website/tree/master/supabase/migrations): relational database · Bookings, guests, reviews, wishlists, payments, and conversations. · `supabase/migrations`
- [Auth callback](https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/auth/callback/route.js): route handler · `app/auth/callback/route.js`
- [Razorpay](https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/_lib/razorpay.js): payment integration · `app/_lib/razorpay.js`
- [AI APIs](https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/api/chat/route.js): route handlers · Chat and recommendation endpoints. · `app/api/chat/route.js`
- [AI search services](https://github.com/abidev2003/the-wild-oasis-website/blob/master/app/_lib/groq.js): AI and search logic · Groq-backed chat/recommendations with parsing, suggestions, and rate limits. · `app/_lib/groq.js`
- [Request proxy](https://github.com/abidev2003/the-wild-oasis-website/blob/master/proxy.js): request interception · Applies request-time session handling. · `proxy.js`

## Connections

- App shell → Shared navigation: renders
- Discovery home → Cabin catalogue: discovery flow
- Cabin catalogue → Reservation form: selects cabin
- Reservation form → Domain actions: creates reservation
- Client contexts → Reservation form: reservation state
- Protected account → Reservation editing: manages bookings
- Reservation editing → Domain actions: updates reservation
- Domain actions → Booking rules: applies rules
- Domain actions → Data service: persists changes
- Data service → Supabase access: queries and RPCs
- Supabase access → Supabase database: data and RLS
- Authentication UI → Auth callback: completes sign-in
- Auth callback → Session auth: establishes session
- Protected account → Session auth: requires session
- Session auth → Supabase access: uses server session
- Request proxy → Session auth: request session
- Checkout → Domain actions: loads booking
- Checkout → Razorpay: initiates payment
- Razorpay → Supabase database: payment state
- Checkout → Payment confirmation: payment complete
- AI APIs → AI search services: automation requests
- AI search services → Supabase access: search and conversations