# udarakavishka/ceylonroots architecture

> Architecture diagram of the GitHub repository udarakavishka/ceylonroots, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/udarakavishka/ceylonroots
- Repository: https://github.com/udarakavishka/ceylonroots

## Overview

##### Project Type & Purpose
- CeylonRoots is a full-stack travel agency platform with:
- A Next.js 14 frontend (app router, server+client components, API routes)
- A Spring Boot backend exposing REST endpoints
- Persistent storage (MySQL) and object storage (AWS S3)
- Third-party integrations (Stripe/PayPal, Google Maps, JWT auth)

##### High-Level Components
A. Client Browser
- Renders React pages served by Next.js
- Interacts via HTTP/HTTPS (SSR + CSR + API calls)
B. Next.js Frontend
- UI Layer (pages under app/, reusable components)
- App Router + SSR/SSG
- API Routes (app/api) acting as BFF or proxy to backend
- Tailwind CSS, context providers, hooks
C. Spring Boot Backend
- MVC Layers:
- Controllers (AccommodationController, BlogPostController, etc.)
- Services (AccommodationService, AwsS3Service, etc.)
- Repositories (JPA interfaces to MySQL)
- Global exception handling, DTO converters
- Security: JWT authentication filter
- Configuration: CorsConfig, application.properties
D. Data Stores
- MySQL relational database (schemas for Users, Packages, BlogPosts, etc.)
- AWS S3 buckets (for Gallery images)
E. External Services
- Payment gateways (Stripe, PayPal)
- Google Maps API (maps, geocoding)
- Optional Chat/Live chat provider

##### Interactions & Data Flow
1. User → Browser: requests UI routes or performs client-side navigation.
2. Browser ↔ Next.js:
- SSR/SSG pages served by Next.js server
- CSR API calls to /api/* endpoints for dynamic data
3. Next.js API Routes → Spring Boot Backend:
- Translates front-end requests into REST calls (e.g., GET /api/destinations → GET /backend/destinations)
- Handles JWT tokens (passes Authorization header)
4. Spring Boot → MySQL & AWS S3:
- CRUD via JPA repositories to MySQL
- File uploads/downloads via AwsS3Service to S3
5. Spring Boot → External APIs:
- Payment processing POSTs to Stripe/PayPal
- Data from Google Maps
6. Response chains back to user

##### Architectural Patterns & Principles
- Next.js as BFF (Backend-for-Frontend) for consolidated API
- MVC (Controller → Service → Repository) in Spring Boot
- Layered security with JWT and CORS configuration
- Separation of concerns: UI vs application logic vs data access
- Reusable UI components and contexts in frontend

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Browser
    subgraph "User Browser"
        Browser["Client Browser"]:::frontend
    end

    %% Next.js Frontend
    subgraph "Next.js Frontend"
        direction TB
        UI["UI Layer<br/>Next.js 14, React 18"]:::frontend
        API["API Routes (BFF)"]:::frontend
        Contexts["Context Providers & Hooks"]:::frontend
        ServiceModule["Service Module (api.ts)"]:::frontend
        Styles["Global Styles<br/>Tailwind CSS"]:::frontend
    end

    %% Spring Boot Backend
    subgraph "Spring Boot Backend"
        direction TB
        Entry["BackendApplication.java"]:::backend
        Controllers["Controllers"]:::backend
        Services["Services"]:::backend
        Repos["Repositories"]:::backend
        Config["Configuration"]:::backend
        Exceptions["Global Exception Handling & Converters"]:::backend
        DTOs["DTOs"]:::backend
        Models["Domain Models"]:::backend
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        MySQL["MySQL"]:::database
        S3["AWS S3"]:::database
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Payment["Stripe/PayPal"]:::external
        Maps["Google Maps API"]:::external
        Chat["Chat Provider"]:::external
    end

    %% Connections
    Browser -->|"HTTP/HTTPS SSR/CSR"| UI
    UI -->|"uses contexts/hooks"| Contexts
    UI -->|"navigates to API"| API
    API -->|"REST/HTTP + JWT"| Controllers
    Entry -->|starts app| Controllers
    Controllers -->|"calls"| Services
    Services -->|"JPA SQL"| Repos
    Services -->|"S3 API"| S3
    Services -->|"process payments HTTPS"| Payment
    Services -->|"maps HTTPS"| Maps
    Repos -->|"SQL"| MySQL
    Controllers -->|"uses DTOs & Models"| DTOs
    Controllers -->|"uses DTOs & Models"| Models
    Config -->|"provides props & CORS"| Controllers
    Exceptions -->|"handles exceptions"| Controllers

    %% Click Events
    click UI "https://github.com/udarakavishka/ceylonroots/tree/main/ceylonroots/app"
    click API "https://github.com/udarakavishka/ceylonroots/tree/main/ceylonroots/app/api"
    click Contexts "https://github.com/udarakavishka/ceylonroots/blob/main/ceylonroots/app/contexts/UserContext.tsx"
    click Contexts "https://github.com/udarakavishka/ceylonroots/blob/main/ceylonroots/app/hooks/useToast.ts"
    click ServiceModule "https://github.com/udarakavishka/ceylonroots/blob/main/ceylonroots/app/service/api.ts"
    click Styles "https://github.com/udarakavishka/ceylonroots/blob/main/ceylonroots/globals.css"
    click Styles "https://github.com/udarakavishka/ceylonroots/blob/main/ceylonroots/postcss.config.mjs"
    click Entry "https://github.com/udarakavishka/ceylonroots/blob/main/backend/src/main/java/com/example/backend/BackendApplication.java"
    click Controllers "https://github.com/udarakavishka/ceylonroots/tree/main/backend/src/main/java/com/example/backend/controller/"
    click Services "https://github.com/udarakavishka/ceylonroots/tree/main/backend/src/main/java/com/example/backend/service/"
    click Repos "https://github.com/udarakavishka/ceylonroots/tree/main/backend/src/main/java/com/example/backend/repository/"
    click Config "https://github.com/udarakavishka/ceylonroots/blob/main/backend/src/main/java/com/example/backend/config/CorsConfig.java"
    click Config "https://github.com/udarakavishka/ceylonroots/blob/main/backend/src/main/resources/application.properties"
    click Exceptions "https://github.com/udarakavishka/ceylonroots/blob/main/backend/src/main/java/com/example/backend/exception/GlobalExceptionHandler.java"
    click Exceptions "https://github.com/udarakavishka/ceylonroots/blob/main/backend/src/main/java/com/example/backend/converter/LongListConverter.java"
    click DTOs "https://github.com/udarakavishka/ceylonroots/tree/main/backend/src/main/java/com/example/backend/dto/"
    click Models "https://github.com/udarakavishka/ceylonroots/tree/main/backend/src/main/java/com/example/backend/model/"
    click S3 "https://github.com/udarakavishka/ceylonroots/blob/main/backend/src/main/java/com/example/backend/service/AwsS3Service.java"
    click MySQL "https://github.com/udarakavishka/ceylonroots/blob/main/backend/src/main/resources/application.properties"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064;
    classDef backend fill:#E8F5E9,stroke:#1B5E20;
    classDef database fill:#FFF3E0,stroke:#E65100;
    classDef external fill:#F3E5F5,stroke:#6A1B9A;
```
