# nixonaguero/caribeanocean_clientfrontend architecture

> Architecture diagram of the GitHub repository nixonaguero/caribeanocean_clientfrontend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nixonaguero/caribeanocean_clientfrontend
- Repository: https://github.com/nixonaguero/caribeanocean_clientfrontend

## Overview

1. **Overall shape**
   - This is a **React + TypeScript + Vite single-page application**.
   - The architecture is organized as a **feature-based frontend**: each business area owns its components, hooks, services, types, and styles.

2. **App shell and composition**
   - The top-level entry points are `src/main.tsx` and `src/App.tsx`.
   - `src/app/layout/MainLayout.tsx` likely defines the persistent frame around the app: **navbar, page content, footer, and promotional/ads UI**.
   - Layout-level components live under `src/app/layout/*`, separating chrome from feature content.

3. **Navigation and page boundaries**
   - Route-level pages are represented by feature pages such as `HomePage.tsx`, `RoomsPage.tsx`, and `BookingPage.tsx`.
   - `src/shared/components/AnimatedRoutes` suggests route transitions are animated rather than plain route swaps.
   - `ScrollToHash.tsx` indicates the app supports in-page anchor navigation, which matters for sections on long landing pages.

4. **Feature-module architecture**
   - Most domain areas are isolated under `src/features/*`: `hero`, `about-us`, `facilities`, `galery`, `offers`, `rooms`, `locations`, `booking`.
   - Each feature typically follows the same internal pattern:
     - `components/` for UI
     - `hooks/` for state and orchestration
     - `services/` for data fetching
     - `types/` for domain models
     - `styles/` for feature-scoped CSS
   - This makes each feature diagrammable as a self-contained subsystem.

5. **Landing-page content pipeline**
   - The homepage is assembled from multiple content sections: **hero, about us, facilities, gallery, offers, rooms, locations**.
   - The hero and offers sections include carousel/navigation hooks, implying interactive, media-rich UI rather than static content.
   - These modules are likely composed in the home page and driven by feature services rather than hardcoded data.

6. **Booking subsystem**
   - The booking area is the most workflow-oriented part of the app.
   - It includes a **search form**, **search results**, **room type cards**, **checkout form**, and a **success state**.
   - Hooks such as `useBooking`, `useBookingSearch`, and `useCheckout` suggest a staged flow:
     - collect criteria
     - query availability
     - select room/package
     - complete checkout
     - show confirmation
   - `date.utils.ts` is a supporting utility boundary for date calculations and formatting.

7. **Data access layer**
   - Each feature has a `services/*.service.ts` file, indicating the app uses a **service layer between UI hooks and backend/API calls**.
   - `src/shared/services/apiClient.ts` is the shared HTTP boundary, likely centralizing fetch/axios configuration and error handling.
   - The architecture therefore separates:
     - UI components
     - stateful hooks
     - API/service calls
     - shared client configuration

8. **Shared primitives and cross-cutting concerns**
   - `src/shared/components` contains reusable infrastructure pieces:
     - `Spinner` for loading states
     - `AnimatedRoutes` for navigation transitions
     - `ScrollToHash` for anchor behavior
   - `src/shared/hooks/useLoading.ts` suggests a shared loading state pattern reused across features.

9. **Styling and design system**
   - Styling is split between:
     - global CSS under `src/css/*` (`global`, `layout`, `typography`, `variables`, `components`)
     - feature-local CSS modules under each feature
   - This implies a **design-token + modular CSS** approach: global visual foundations with localized component styling.
   - The `.agents/skills/desing_standars` files confirm the repo has explicit design-system guidance, though those files are documentation rather than runtime code.

10. **Assets and visual content**
   - Static media is stored under `src/assets` and grouped by domain (`facilities`, `footer`, `rooms`).
   - This supports the content-heavy hotel/resort style UI suggested by the feature set.

11. **Tooling and build/runtime**
   - The project uses **Vite** for development/build, **ESLint** for code quality, and **TypeScript** for type safety.
   - `plopfile.mjs` suggests code generation scaffolding is part of the workflow, likely to keep feature structure consistent.

12. **Key architectural boundary for a diagram**
   - The main boundary to draw is:
     - **App shell/layout**
     - **Feature modules**
     - **Shared utilities/infrastructure**
     - **Data/API services**
   - Feature hooks sit between UI and services, while layout-level components wrap and coordinate navigation and persistent chrome.

Main entry points: [`src/features/home/HomePage.tsx`](https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/features/home/HomePage.tsx) (Home page), [`src/app/layout/MainLayout.tsx`](https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/app/layout/MainLayout.tsx) (Main layout), [`src/shared/services/apiClient.ts`](https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/shared/services/apiClient.ts) (API client), [`src/App.tsx`](https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/App.tsx) (App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["App Shell"]
  node_main["main.tsx<br/>entry<br/>[main.tsx]"]
  node_app["App<br/>root<br/>[App.tsx]"]
  node_layout["Main layout<br/>[MainLayout.tsx]"]
  node_navbar["Navbar<br/>chrome<br/>[MainNavBar.tsx]"]
  node_footer["Footer<br/>chrome<br/>[Footer.tsx]"]
  node_ads["Ads modal<br/>chrome<br/>[PubModal.tsx]"]
end

subgraph group_landing["Landing Features"]
  node_home["Home page<br/>[HomePage.tsx]"]
  node_hero["Hero<br/>feature<br/>[Hero.tsx]"]
  node_about["About us<br/>feature<br/>[AboutUs.tsx]"]
  node_facilities["Facilities<br/>feature<br/>[Facilities.tsx]"]
  node_gallery["Gallery<br/>feature<br/>[Gallery.tsx]"]
  node_offers["Offers<br/>feature<br/>[Offers.tsx]"]
  node_locations["Locations<br/>feature<br/>[Locations.tsx]"]
  node_rooms["Rooms<br/>feature<br/>[Rooms.tsx]"]
  node_rooms_page["Rooms page<br/>[RoomsPage.tsx]"]
end

subgraph group_booking["Booking Flow"]
  node_booking_page["Booking page<br/>[BookingPage.tsx]"]
  node_booking["Booking flow<br/>workflow<br/>[Booking.tsx]"]
end

subgraph group_shared["Shared Infra"]
  node_routes["Animated routes<br/>routing<br/>[AnimatedRoutes.tsx]"]
  node_scroll["Scroll hash<br/>routing<br/>[ScrollToHash.tsx]"]
  node_spinner(("Spinner<br/>ui<br/>[Spinner.tsx]"))
  node_api["API client<br/>http<br/>[apiClient.ts]"]
  node_loading["useLoading<br/>hook<br/>[useLoading.ts]"]
end

node_main -->|"bootstraps"| node_app
node_app -->|"wraps"| node_layout
node_app -->|"navigates"| node_routes
node_app -->|"supports"| node_scroll
node_layout -->|"contains"| node_navbar
node_layout -->|"contains"| node_footer
node_layout -->|"contains"| node_ads
node_layout -->|"hosts"| node_home
node_layout -->|"hosts"| node_rooms_page
node_layout -->|"hosts"| node_booking_page
node_home -->|"assembles"| node_hero
node_home -->|"assembles"| node_about
node_home -->|"assembles"| node_facilities
node_home -->|"assembles"| node_gallery
node_home -->|"assembles"| node_offers
node_home -->|"assembles"| node_locations
node_home -->|"assembles"| node_rooms
node_hero -->|"loads data"| node_api
node_about -->|"loads data"| node_api
node_facilities -->|"loads data"| node_api
node_gallery -->|"loads data"| node_api
node_offers -->|"loads data"| node_api
node_locations -->|"loads data"| node_api
node_rooms -->|"loads data"| node_api
node_rooms_page -->|"uses"| node_rooms
node_booking_page -->|"uses"| node_booking
node_booking -->|"loads data"| node_api
node_booking -->|"tracks"| node_loading
node_booking -->|"shows"| node_spinner

click node_main "https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/main.tsx"
click node_app "https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/App.tsx"
click node_layout "https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/app/layout/MainLayout.tsx"
click node_navbar "https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/app/layout/Navbar/MainNavBar.tsx"
click node_footer "https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/app/layout/Footer/Footer.tsx"
click node_ads "https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/app/layout/Ads/PubModal.tsx"
click node_routes "https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/shared/components/AnimatedRoutes/AnimatedRoutes.tsx"
click node_scroll "https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/shared/components/ScrollToHash.tsx"
click node_spinner "https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/shared/components/Spinner/Spinner.tsx"
click node_api "https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/shared/services/apiClient.ts"
click node_loading "https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/shared/hooks/useLoading.ts"
click node_home "https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/features/home/HomePage.tsx"
click node_hero "https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/features/hero/components/Hero.tsx"
click node_about "https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/features/about-us/components/AboutUs.tsx"
click node_facilities "https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/features/facilities/components/Facilities.tsx"
click node_gallery "https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/features/galery/components/Gallery.tsx"
click node_offers "https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/features/offers/components/Offers.tsx"
click node_locations "https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/features/locations/components/Locations.tsx"
click node_rooms "https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/features/rooms/components/Rooms.tsx"
click node_rooms_page "https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/features/rooms/components/RoomsPage.tsx"
click node_booking_page "https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/features/booking/BookingPage.tsx"
click node_booking "https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/features/booking/components/Booking.tsx"

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_main,node_app,node_layout,node_navbar,node_footer,node_ads toneBlue
class node_home,node_hero,node_about,node_facilities,node_gallery,node_offers,node_locations,node_rooms,node_rooms_page toneAmber
class node_booking_page,node_booking toneMint
class node_routes,node_scroll,node_spinner,node_api,node_loading toneRose
```

## Components

### App Shell

Entry, persistent layout, and route orchestration.

- [main.tsx](https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/main.tsx): entry · Vite/React bootstrap entry point. · `src/main.tsx`
- [App](https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/App.tsx): root · Top-level application composition. · `src/App.tsx`
- [Main layout](https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/app/layout/MainLayout.tsx): layout · Persistent frame for navbar, content, footer, and ads. · `src/app/layout/MainLayout.tsx`
- [Navbar](https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/app/layout/Navbar/MainNavBar.tsx): chrome · Primary site navigation. · `src/app/layout/Navbar/MainNavBar.tsx`
- [Footer](https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/app/layout/Footer/Footer.tsx): chrome · Persistent footer content. · `src/app/layout/Footer/Footer.tsx`
- [Ads modal](https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/app/layout/Ads/PubModal.tsx): chrome · Publicity or promotional modal layer. · `src/app/layout/Ads/PubModal.tsx`

### Landing Features

Homepage sections and content modules.

- [Home page](https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/features/home/HomePage.tsx): page · Landing page composition container. · `src/features/home/HomePage.tsx`
- [Hero](https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/features/hero/components/Hero.tsx): feature · Carousel-led hero section with navigation controls. · `src/features/hero/components/Hero.tsx`
- [About us](https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/features/about-us/components/AboutUs.tsx): feature · Brand/story section. · `src/features/about-us/components/AboutUs.tsx`
- [Facilities](https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/features/facilities/components/Facilities.tsx): feature · Amenities and facility list section. · `src/features/facilities/components/Facilities.tsx`
- [Gallery](https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/features/galery/components/Gallery.tsx): feature · Image gallery with main image and thumbnails. · `src/features/galery/components/Gallery.tsx`
- [Offers](https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/features/offers/components/Offers.tsx): feature · Promotions carousel and offer cards. · `src/features/offers/components/Offers.tsx`
- [Locations](https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/features/locations/components/Locations.tsx): feature · Location and map-oriented content. · `src/features/locations/components/Locations.tsx`
- [Rooms](https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/features/rooms/components/Rooms.tsx): feature · Room showcase and carousel. · `src/features/rooms/components/Rooms.tsx`
- [Rooms page](https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/features/rooms/components/RoomsPage.tsx): page · Route-level rooms listing page. · `src/features/rooms/components/RoomsPage.tsx`

### Booking Flow

Booking page and staged reservation workflow.

- [Booking page](https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/features/booking/BookingPage.tsx): page · Route-level booking entry page. · `src/features/booking/BookingPage.tsx`
- [Booking flow](https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/features/booking/components/Booking.tsx): workflow · Search, selection, checkout, and success states. · `src/features/booking/components/Booking.tsx`

### Shared Infra

Reusable routing, loading, and API boundaries.

- [Animated routes](https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/shared/components/AnimatedRoutes/AnimatedRoutes.tsx): routing · Animated page transitions around route changes. · `src/shared/components/AnimatedRoutes/AnimatedRoutes.tsx`
- [Scroll hash](https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/shared/components/ScrollToHash.tsx): routing · Anchor and in-page hash navigation helper. · `src/shared/components/ScrollToHash.tsx`
- [Spinner](https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/shared/components/Spinner/Spinner.tsx): ui · Shared loading indicator. · `src/shared/components/Spinner/Spinner.tsx`
- [API client](https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/shared/services/apiClient.ts): http · Shared HTTP client and central request boundary. · `src/shared/services/apiClient.ts`
- [useLoading](https://github.com/nixonaguero/caribeanocean_clientfrontend/blob/main/src/shared/hooks/useLoading.ts): hook · Shared loading-state hook. · `src/shared/hooks/useLoading.ts`

## Connections

- main.tsx → App: bootstraps · Application starts here.
- App → Main layout: wraps · App composition uses the persistent shell.
- App → Animated routes: navigates · Route changes are animated.
- App → Scroll hash: supports · Anchor navigation is enabled across pages.
- Main layout → Navbar: contains · Top navigation sits in the shell.
- Main layout → Footer: contains · Footer is part of the persistent frame.
- Main layout → Ads modal: contains · Promotional UI is layered into the shell.
- Main layout → Home page: hosts · Layout renders routed content.
- Main layout → Rooms page: hosts · Rooms is a route-level page.
- Main layout → Booking page: hosts · Booking is a route-level page.
- Home page → Hero: assembles · Homepage begins with the hero section.
- Home page → About us: assembles · Homepage includes brand/story content.
- Home page → Facilities: assembles · Homepage includes amenities content.
- Home page → Gallery: assembles · Homepage includes visual gallery content.
- Home page → Offers: assembles · Homepage includes promotions.
- Home page → Locations: assembles · Homepage includes location content.
- Home page → Rooms: assembles · Homepage includes room showcase content.
- Hero → API client: loads data · Section data is sourced through shared HTTP access.
- About us → API client: loads data · Content is fetched via service layer.
- Facilities → API client: loads data · Amenities content comes from services.
- Gallery → API client: loads data · Gallery media is sourced from services.
- Offers → API client: loads data · Promotions are retrieved through the service boundary.
- Locations → API client: loads data · Location content is fetched via services.
- Rooms → API client: loads data · Room catalog data is fetched through services.
- Rooms page → Rooms: uses · Rooms page renders the rooms subsystem.
- Booking page → Booking flow: uses · Booking page renders the reservation workflow.
- Booking flow → API client: loads data · Availability and checkout operations use the shared client.
- Booking flow → useLoading: tracks · Workflow uses shared loading state.
- Booking flow → Spinner: shows · Loading feedback is shared across booking steps.
