# isuu1/gifinity architecture

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

- Interactive diagram: https://gitdiagram.com/isuu1/gifinity
- Repository: https://github.com/isuu1/gifinity

## Overview

##### Project Type and Purpose
- Gifinity is a full-stack Next.js web application built with the App Router. Its primary functionality is to let users search and browse GIFs and stickers from the Giphy API. The app supports guest usage (storing favorites locally) and registered accounts (transferring and saving favorites to a database via Supabase). Additional features include smooth UI animations with Framer Motion.

##### File Structure
- Top-level directories and key parts include:
- The “app” folder, which contains pages segmented by user flows (authentication, main app pages, modals) following Next.js concepts.
- The “api” folder under “app” that provides backend endpoints for authentication, categories, search (including autocomplete, gifs, stickers), trending searches, and trending data.
- Feature-specific folders (“features/auth”, “features/categories”, “features/collections”, “features/favourites”, “features/media”, “features/search”, “features/user”) that separate the core application logic such as actions, components, schemas, types, and utilities.
- Shared components under “components” and layout definitions under “layouts” that reinforce separation of UI elements.
- Integration with Supabase (see “utils/supabase” folder), which handles authentication and database interactions.
- The file tree reflects a modular and organized approach, dividing presentation, business logic, and API interactions.

##### Key Components
a. Frontend:
- Next.js App: Represented by the “app” directory with segmented routes for:
- Auth Module: login, signup pages, and modals.
- Main Content: categories, trending, search, error pages, and user profiles.
- Special UI components for modals, headers, footers, etc.
- Shared Components and Layouts: All the UI elements imported from “components” and “layouts” provide the visual part of the application.
- Client-Side State & Local Storage: Illustrate how favorites are stored locally for non-authenticated users.
- Animations: Note that Framer Motion is used to enhance the smooth UI transitions.

b. API & Backend:
- Next.js API Routes: Under “app/api” handling business logic for authentication and content retrieval from the Giphy API.
- External API Integration: Clearly indicate the interaction with the Giphy API to fetch GIFs and stickers.
- Supabase Integration: Represent the Supabase service that manages authentication and is linked to database actions (like syncing favorites) as encapsulated in the “utils/supabase” module.

c. Data Storage:
- Local Storage: For persisting guest user favorites.
- Database (Supabase): For storing authenticated user data and favorites, which is synchronized during login.

##### Component Relationships & Data Flow
- The Browser/User Interface sends user inputs (search queries, actions like adding/removing favorites) to Next.js page components.
- Data returned from external services (Giphy API) flows into the API routes, then transformed and passed to the UI.
- Authentication modules interact with Supabase to handle user sessions and data storage, with local storage used for guest sessions.

##### Architectural Patterns & Design Principles
- Modularization: The separation into multiple “features” folders (auth, search, etc.) indicates a modular design that isolates functionality.
- Separation of concerns: Clean division between UI (presentation), business logic (features/actions), and backend (API endpoints).
- API Gateway/Back-end for Frontend: Next.js API routes serve as the middle layer connecting the frontend to external APIs and the database.
- Client-side vs. Server-side rendering: Next.js under the App Router suggests a mix of both patterns, with server-side endpoints fetching data and UI composed by dynamic React components.

##### Putting It All Together
- Out behavioral flows:
- From user interactions on the search page to the API fetch from Giphy API.
- From actions (like favorite selection) that initially update local storage and then are migrated to Supabase upon authentication.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interface (Frontend)"
        UI1["Next.js Auth Page"]
        UI2["Next.js Main Page: Categories"]
        UI3["Next.js Modal: Login"]
        UI4["Header Component"]
        UI5["Auth Pages Layout"]
        UI6["User Page Layout"]
        UI7["Framer Motion Animations"]
        UI8["Local Storage (Favorites)"]
    end

    subgraph "Backend/API & Business Logic"
        subgraph "API Endpoints"
            API1["API: Auth Confirm"]
            API2["API: Search GIFs"]
            API3["API: Trending Stickers"]
        end
        subgraph "Feature Modules"
            FAuth1["Auth Action"]
            FAuth2["Login Form"]
            FAuth3["Signup Form"]
            FCat["Categories Menu"]
            FCol1["Create Collection Action"]
            FCol2["Add To Collection Modal"]
            FFav1["Favourite Button"]
            FFav2["Favourites Grid"]
            FMedia1["Media Data Grid"]
            FMedia2["Media Overlay"]
            FSearch1["Autocomplete Component"]
            FSearch2["Search Component"]
            FUser1["Change User Details Action"]
            FUser2["Profile Component"]
        end
    end

    subgraph "External Services & Data"
        Ext1["Giphy API"]
        Ext2["Supabase Service"]
        Ext3["Supabase Client"]
        Ext4["Supabase Server"]
    end

    %% Data Flow: UI -> API/Features
    UI1 -->|"submitLogin"| API1
    UI2 -->|"getGifs"| API2
    UI2 -->|"search"| FSearch2
    UI2 -->|"displayCategories"| FCat
    UI3 -->|"triggerModal"| UI1

    %% Data Flow: Feature Modules invoking API actions
    FAuth2 -->|"triggerAuth"| API1
    FFav1 -->|"storeFavorite"| UI8
    FFav2 -->|"syncFavorites"| Ext2

    %% Data Flow: API Endpoints interacting with External Services
    API2 -->|"fetchGIFs"| Ext1
    API1 -->|"verifyUser"| Ext2

    %% Data Flow: Migrating Data from Guest Storage to Database
    UI8 -->|"migrateFavorites"| Ext2

    %% Supabase Integration Details
    Ext3 -->|"connectsTo"| Ext2
    Ext4 -->|"connectsTo"| Ext2

    %% Styling Definitions
    class UI1,UI2,UI3,UI4,UI5,UI6,UI7,UI8 ui
    class API1,API2,API3 api
    class FAuth1,FAuth2,FAuth3,FCat,FCol1,FCol2,FFav1,FFav2,FMedia1,FMedia2,FSearch1,FSearch2,FUser1,FUser2 feature
    class Ext1,Ext2,Ext3,Ext4 external

click UI1 "https://github.com/isuu1/gifinity/blob/main/app/(auth)/login/page.tsx"
click UI2 "https://github.com/isuu1/gifinity/blob/main/app/(main)/categories/page.tsx"
click UI3 "https://github.com/isuu1/gifinity/blob/main/app/@modal/login/page.tsx"
click UI4 "https://github.com/isuu1/gifinity/blob/main/components/Header/Header.tsx"
click UI5 "https://github.com/isuu1/gifinity/blob/main/layouts/AuthPagesLayout.tsx"
click UI6 "https://github.com/isuu1/gifinity/blob/main/layouts/UserPageLayout.tsx"

click API1 "https://github.com/isuu1/gifinity/blob/main/app/api/auth/confirm/route.ts"
click API2 "https://github.com/isuu1/gifinity/blob/main/app/api/search/gifs/route.ts"
click API3 "https://github.com/isuu1/gifinity/blob/main/app/api/trending/stickers/route.ts"

click FAuth1 "https://github.com/isuu1/gifinity/blob/main/features/auth/actions/auth.ts"
click FAuth2 "https://github.com/isuu1/gifinity/blob/main/features/auth/components/LoginForm.tsx"
click FAuth3 "https://github.com/isuu1/gifinity/blob/main/features/auth/components/SignupForm.tsx"

click FCat "https://github.com/isuu1/gifinity/blob/main/features/categories/components/CategoriesMenu.tsx"

click FCol1 "https://github.com/isuu1/gifinity/blob/main/features/collections/actions/createCollection.ts"
click FCol2 "https://github.com/isuu1/gifinity/blob/main/features/collections/components/AddToCollectionModal.tsx"

click FFav1 "https://github.com/isuu1/gifinity/blob/main/features/favourites/components/FavouriteButton.tsx"
click FFav2 "https://github.com/isuu1/gifinity/blob/main/features/favourites/components/FavouritesGrid.tsx"

click FMedia1 "https://github.com/isuu1/gifinity/blob/main/features/media/components/DataGrid.tsx"
click FMedia2 "https://github.com/isuu1/gifinity/blob/main/features/media/components/MediaOverlay.tsx"

click FSearch1 "https://github.com/isuu1/gifinity/blob/main/features/search/components/Autocomplete.tsx"
click FSearch2 "https://github.com/isuu1/gifinity/blob/main/features/search/components/Search.tsx"

click FUser1 "https://github.com/isuu1/gifinity/blob/main/features/user/actions/changeUserDetails.ts"
click FUser2 "https://github.com/isuu1/gifinity/blob/main/features/user/components/Profile.tsx"

click Ext3 "https://github.com/isuu1/gifinity/blob/main/utils/supabase/client.ts"
click Ext4 "https://github.com/isuu1/gifinity/blob/main/utils/supabase/server.ts"

classDef ui fill:#ADD8E6,stroke:#000,stroke-width:2px;
classDef api fill:#90EE90,stroke:#000,stroke-width:2px;
classDef feature fill:#FFD700,stroke:#000,stroke-width:2px;
classDef external fill:#FFB6C1,stroke:#000,stroke-width:2px;
```
