# devmdfaiz/cloud-clove architecture

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

- Interactive diagram: https://gitdiagram.com/devmdfaiz/cloud-clove
- Repository: https://github.com/devmdfaiz/cloud-clove

## Overview

##### Main Components

- Frontend Interface:
– Represent the “src/app” folder as the primary UI layer.
– Highlight different groups: the (auth) group for sign-in/sign-up flows and the (dashboard) group for logged-in user interactions.
– Include key elements like pages (page.tsx files), layout components (layout.tsx), and shared components such as sidebars, headers, and file cards.

- API Layer:
– Identify “src/app/api” which contains endpoints for authentication (e.g. “api/auth”) and versioned endpoints under “api/v1”.
– Show these API routes as services that handle data requests and business logic.

- Business Logic & Actions:
– Include the “src/action” directory that defines actions like auth.action.ts, file.action.ts, paddle.action.ts, and subscription.action.ts.
– Represent these as the bridge between the user interactions and backend processing.

- UI Components & Presentation:
– Indicate that these components are reused across various pages and layouts.

- State Management & Hooks:
– For application state and interactions, include modules from “src/context” and “src/hooks” (for mobile detection, paddle integration, toast messages, etc.).

- Authentication and External Services:
– Also include “src/lib/paddle”, “src/lib/pinata”, and any other integration libraries for third-party services.

- Database Layer:
– Showcase “src/lib/database” with its schema definitions (e.g., file.model.ts and subscription.model.ts) as the core of persistent storage.

##### Relationships and Data Flows

- That these actions call API routes under “src/app/api” to perform operations like authentication, file handling, or subscription management.
- That API endpoints interact with internal services – notably authentication via “src/lib/better-auth” and data persistence via the “database” layer.
- How UI components (from the components folder) are assembled into page layouts and how they render data fetched from API endpoints.

- Integration flows where external services come into play (for example, Paddle for payment/subscription processing and Pinata for storage or related tasks).

##### Architectural Patterns / Key Design Concepts

- Next.js App Router Pattern: Demonstrate the separation of concerns within the “app” directory using nested layouts and grouped routes (e.g., (auth) and (dashboard)).
- API Route Convention: Emphasize how dynamic API routes (using [...all] and [[...route]] patterns) allow for versioning and extensibility.
- Component Driven UI: Use the “components/ui” folder to showcase how presentation logic is modularized, reusable, and styled consistently.
- Business Logic Separation: Indicate that the “action” modules and “lib” functions keep the business logic decoupled from the view logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Group
    subgraph "Frontend"
        UIApp["UI Pages & Layouts"]:::frontend
        AuthUI["Auth Routes"]:::frontend
        DashboardUI["Dashboard Routes"]:::frontend
        Components["UI Components"]:::component
        CustomComp["Custom Components"]:::component
        Icons["Icons"]:::component
        UIlib["UI Library"]:::component
        StateContext["State (Context)"]:::state
        Hooks["Hooks"]:::state
    end

    %% Backend Group
    subgraph "Backend"
        API["API Endpoints"]:::api
        AuthAPI["Auth API Endpoint"]:::api
        VersionedAPI["Versioned API Endpoints"]:::api

        subgraph "Action Handlers"
            AuthAction["auth.action.ts"]:::action
            FileAction["file.action.ts"]:::action
            PaddleAction["paddle.action.ts"]:::action
            SubscriptionAction["subscription.action.ts"]:::action
        end

        BetterAuth["Better Auth Service"]:::integration
        PaddleIntegration["Paddle Integration"]:::integration
        PinataIntegration["Pinata Integration"]:::integration

        subgraph "Database"
            DatabaseCore["Database Core"]:::database
            DBFile["DB File"]:::database
            Schema["Schema Definitions"]:::database
            FileModel["file.model.ts"]:::database
            SubscriptionModel["subscription.model.ts"]:::database
        end
    end

    %% Relationships from Frontend to Backend
    UIApp -->|"request"| API
    UIApp -->|"renders"| Components
    UIApp -->|"manages"| StateContext
    UIApp -->|"manages"| Hooks
    UIApp --> AuthUI
    UIApp --> DashboardUI

    %% Frontend internal relationships
    Components --> CustomComp
    Components --> Icons
    Components --> UIlib

    %% API breakdown
    API --> AuthAPI
    API --> VersionedAPI

    %% API to Action Handlers
    API --> AuthAction
    API --> FileAction
    API --> PaddleAction
    API --> SubscriptionAction

    %% Action Handlers calling internal services
    AuthAction -->|"calls"| BetterAuth
    AuthAction -->|"calls"| DatabaseCore

    FileAction -->|"calls"| DatabaseCore
    FileAction -->|"calls"| PinataIntegration

    PaddleAction -->|"calls"| PaddleIntegration

    SubscriptionAction -->|"calls"| DatabaseCore
    SubscriptionAction -->|"calls"| PaddleIntegration

    %% Database relationships
    DatabaseCore --> DBFile
    DatabaseCore --> Schema
    Schema --> FileModel
    Schema --> SubscriptionModel

    %% Click Events for Frontend
    click UIApp "https://github.com/devmdfaiz/cloud-clove/tree/main/src/app"
    click AuthUI "https://github.com/devmdfaiz/cloud-clove/tree/main/src/app/(auth)"
    click DashboardUI "https://github.com/devmdfaiz/cloud-clove/tree/main/src/app/(dashboard)"

    %% Click Events for API Layer
    click API "https://github.com/devmdfaiz/cloud-clove/tree/main/src/app/api"
    click AuthAPI "https://github.com/devmdfaiz/cloud-clove/tree/main/src/app/api/auth"
    click VersionedAPI "https://github.com/devmdfaiz/cloud-clove/tree/main/src/app/api/v1"

    %% Click Events for Business Logic & Actions
    click AuthAction "https://github.com/devmdfaiz/cloud-clove/blob/main/src/action/auth.action.ts"
    click FileAction "https://github.com/devmdfaiz/cloud-clove/blob/main/src/action/file.action.ts"
    click PaddleAction "https://github.com/devmdfaiz/cloud-clove/blob/main/src/action/paddle.action.ts"
    click SubscriptionAction "https://github.com/devmdfaiz/cloud-clove/blob/main/src/action/subscription.action.ts"

    %% Click Events for UI Components
    click CustomComp "https://github.com/devmdfaiz/cloud-clove/tree/main/src/components/custom"
    click Icons "https://github.com/devmdfaiz/cloud-clove/tree/main/src/components/icons"
    click UIlib "https://github.com/devmdfaiz/cloud-clove/tree/main/src/components/ui"

    %% Click Events for State Management & Hooks
    click StateContext "https://github.com/devmdfaiz/cloud-clove/blob/main/src/context/query-provider.tsx"
    click Hooks "https://github.com/devmdfaiz/cloud-clove/blob/main/src/hooks/use-mobile.tsx"

    %% Click Events for Authentication and External Services
    click BetterAuth "https://github.com/devmdfaiz/cloud-clove/tree/main/src/lib/better-auth"
    click PaddleIntegration "https://github.com/devmdfaiz/cloud-clove/tree/main/src/lib/paddle"
    click PinataIntegration "https://github.com/devmdfaiz/cloud-clove/tree/main/src/lib/pinata"

    %% Click Events for Database Layer
    click DatabaseCore "https://github.com/devmdfaiz/cloud-clove/tree/main/src/lib/database"
    click DBFile "https://github.com/devmdfaiz/cloud-clove/blob/main/src/lib/database/db.ts"
    click Schema "https://github.com/devmdfaiz/cloud-clove/tree/main/src/lib/database/schema"
    click FileModel "https://github.com/devmdfaiz/cloud-clove/blob/main/src/lib/database/schema/file.model.ts"
    click SubscriptionModel "https://github.com/devmdfaiz/cloud-clove/blob/main/src/lib/database/schema/subscription.model.ts"

    %% Class Definitions for styling with colors
    classDef frontend fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef api fill:#C7F7C7,stroke:#333,stroke-width:2px;
    classDef action fill:#FFF2B2,stroke:#333,stroke-width:2px;
    classDef component fill:#D1E8E2,stroke:#333,stroke-width:2px;
    classDef state fill:#FFC0CB,stroke:#333,stroke-width:2px;
    classDef integration fill:#E6E6FA,stroke:#333,stroke-width:2px;
    classDef database fill:#FFA07A,stroke:#333,stroke-width:2px;
```
