# duc-dev-starter/pawbloom architecture

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

- Interactive diagram: https://gitdiagram.com/duc-dev-starter/pawbloom
- Repository: https://github.com/duc-dev-starter/pawbloom

## Overview

##### Main Architectural Components
- Frontend (Presentation Layer):
– The “app” folder is organized into subdirectories such as (auth), (client), admin, and foster. Each of these holds pages and layouts specific to different user areas.
– The “components” and “sections” directories encapsulate UI elements. You have general-purpose UI components (found in components/common and components/ui) as well as domain-specific components (e.g., components/adopt, components/blog, components/product, etc.).

- Business Logic / Service Layer:
– “services” contains modules (e.g., auth.ts, blog.ts, category.ts, pet.ts, product.ts, user.ts) that encapsulate API calls and business logic.
– “hooks” provide custom React hooks (e.g., use-debounce, use-favorite) to handle client-side behavior and state interactions.
– “store” with Redux slices (authSlice.ts, cartSlice.ts) indicates state management across the application.

- Data and Schema Definitions:
– Directories like “interfaces”, “types”, “schema”, and “constants” are used to define data structures, type contracts, and configuration values. This ensures consistency across API interactions and internal data flows.

- External Integrations and Utilities:
– The “lib” directory (with files like firebase.ts and arcjet.ts) suggests integration with external services (such as Firebase) and helper utilities.
– Configuration files (like next.config.js, tailwind.config.ts, and postcss.config.mjs) along with ESLint and other tool configurations underline the project’s build and deployment setups.

##### Relationships and Data Flows
- Page Routing and Layouts:
– The file-based routing provided by Next.js allows clear segmentation between user types. For instance, the “app/(client)” routes handle public-facing pages while “app/admin” and “app/foster” are focused on their respective dashboards.
– Each of these sections uses its own “layout.tsx” and possibly a “layoutProvider.tsx” to share common UI pieces and context providers.

- API and Business Logic Interaction:
– UI pages and components (from the “app” and “components” folders) call functions within the “services” folder to fetch or process data.
– The “store” and hooks act as intermediaries managing state changes, ensuring UI components react appropriately to changes (for example in authentication status or cart details).

- Data Consistency and Validation:
– Type definitions and schemas ensure that data flows between the frontend, service layer, and any external services (like Firebase) remain accurate. This is also critical for API calls handled by the services using axios (via the “services/axiosInstance.ts”).

##### Architectural Patterns & Design Principles
- File-based Routing & Multi-tenancy:
– The usage of dynamic directories (e.g., “app/(client)/adopt/[slug]”) leverages Next.js dynamic routing for flexible and clean URL management.
- Separation of Concerns:
– UI components, business logic, state management, and data definitions are clearly separated into different directories.
- Reusability & Modularity:
– The presence of domain-specific components (for admin, client, and foster areas) alongside common and UI components promotes reuse and consistent styling.
- External Service Integration:
– With libraries like Firebase integrated within the “lib” folder, the project is designed to work with external backend services.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Presentation Layer
    subgraph "Presentation Layer"
        subgraph "Frontend User Areas"
            A["Auth Pages"]:::presentation
            B["Client Pages"]:::presentation
            C["Admin Dashboard"]:::presentation
            D["Foster Dashboard"]:::presentation
        end
        subgraph "UI Components"
            E["Components Common"]:::presentation
            F["Components UI"]:::presentation
            G["Components Adopt"]:::presentation
            H["Components Blog"]:::presentation
            I["Components Product"]:::presentation
        end
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        subgraph "API Services"
            J["Auth Service"]:::business
            K["Blog Service"]:::business
            L["Category Service"]:::business
            M["Pet Service"]:::business
            N["Product Service"]:::business
            O["User Service"]:::business
            P["Axios Instance"]:::business
        end
        subgraph "Client Behavior"
            Q["Hook: use-debounce"]:::business
            R["Hook: use-favorite"]:::business
            S["Auth State Slice"]:::business
            T["Cart State Slice"]:::business
        end
    end

    %% Data & Integration Layer
    subgraph "Data & Integration Layer"
        subgraph "Data Definitions"
            U["API Interfaces"]:::data
            V["Auth Types"]:::data
            W["Blog Types"]:::data
            X["Category Types"]:::data
            Y["Pet Types"]:::data
            Z["Post Types"]:::data
            AA["Product Types"]:::data
            AB["Status Types"]:::data
            AC["User Types"]:::data
            AD["Auth Schema"]:::data
            AE["Blog Schema"]:::data
            AF["Category Schema"]:::data
            AG["Pet Schema"]:::data
            AH["Product Schema"]:::data
            AI["Project Constants"]:::data
        end
        subgraph "External & Config"
            AJ["Firebase Integration"]:::external
            AK["Arcjet Integration"]:::external
            AL["Utility Functions"]:::external
            AM["Next Config"]:::external
            AN["Tailwind Config"]:::external
            AO["PostCSS Config"]:::external
            AP["ESLint Config"]:::external
        end
    end

    %% Connections between layers
    %% Presentation to Business Logic
    A -->|"calls"| J
    B -->|"calls"| K
    C -->|"calls"| L
    D -->|"calls"| M

    E -->|"updates"| S
    F -->|"updates"| T
    G -->|"uses"| Q
    H -->|"uses"| R
    I -->|"uses"| S

    %% Business Logic to Data Definitions & External
    J -->|"validates"| V
    K -->|"validates"| W
    L -->|"validates"| X
    M -->|"validates"| Y
    N -->|"validates"| AA
    O -->|"validates"| AC
    P -->|"configures"| U

    J -->|"integrates"| AJ
    P -->|"uses"| AM

    Q -->|"updates"| S
    R -->|"updates"| T

    %% Data Definitions interactions (representative)
    K ---|"returns"| W
    M ---|"returns"| Y

    %% Styling
    classDef presentation fill:#FFF3CD,stroke:#E0A800,stroke-width:2px;
    classDef business fill:#D1E7DD,stroke:#0F5132,stroke-width:2px;
    classDef data fill:#D1ECF1,stroke:#0C5460,stroke-width:2px;
    classDef external fill:#F8D7DA,stroke:#842029,stroke-width:2px;

    %% Click Events for Presentation Layer
    click A "https://github.com/duc-dev-starter/pawbloom/tree/master/app/(auth)"
    click B "https://github.com/duc-dev-starter/pawbloom/tree/master/app/(client)"
    click C "https://github.com/duc-dev-starter/pawbloom/tree/master/app/admin"
    click D "https://github.com/duc-dev-starter/pawbloom/tree/master/app/foster"
    click E "https://github.com/duc-dev-starter/pawbloom/tree/master/components/common"
    click F "https://github.com/duc-dev-starter/pawbloom/tree/master/components/ui"
    click G "https://github.com/duc-dev-starter/pawbloom/tree/master/components/adopt"
    click H "https://github.com/duc-dev-starter/pawbloom/tree/master/components/blog"
    click I "https://github.com/duc-dev-starter/pawbloom/tree/master/components/product"

    %% Click Events for Business Logic Layer - API Services
    click J "https://github.com/duc-dev-starter/pawbloom/blob/master/services/auth.ts"
    click K "https://github.com/duc-dev-starter/pawbloom/blob/master/services/blog.ts"
    click L "https://github.com/duc-dev-starter/pawbloom/blob/master/services/category.ts"
    click M "https://github.com/duc-dev-starter/pawbloom/blob/master/services/pet.ts"
    click N "https://github.com/duc-dev-starter/pawbloom/blob/master/services/product.ts"
    click O "https://github.com/duc-dev-starter/pawbloom/blob/master/services/user.ts"
    click P "https://github.com/duc-dev-starter/pawbloom/blob/master/services/axiosInstance.ts"

    %% Click Events for Business Logic Layer - Client Behavior
    click Q "https://github.com/duc-dev-starter/pawbloom/blob/master/hooks/use-debounce.tsx"
    click R "https://github.com/duc-dev-starter/pawbloom/blob/master/hooks/use-favorite.tsx"
    click S "https://github.com/duc-dev-starter/pawbloom/blob/master/store/authSlice.ts"
    click T "https://github.com/duc-dev-starter/pawbloom/blob/master/store/cartSlice.ts"

    %% Click Events for Data Definitions
    click U "https://github.com/duc-dev-starter/pawbloom/blob/master/interfaces/api.ts"
    click V "https://github.com/duc-dev-starter/pawbloom/blob/master/types/auth.ts"
    click W "https://github.com/duc-dev-starter/pawbloom/blob/master/types/blog.ts"
    click X "https://github.com/duc-dev-starter/pawbloom/blob/master/types/category.ts"
    click Y "https://github.com/duc-dev-starter/pawbloom/blob/master/types/pet.ts"
    click Z "https://github.com/duc-dev-starter/pawbloom/blob/master/types/post.ts"
    click AA "https://github.com/duc-dev-starter/pawbloom/blob/master/types/product.ts"
    click AB "https://github.com/duc-dev-starter/pawbloom/blob/master/types/status.ts"
    click AC "https://github.com/duc-dev-starter/pawbloom/blob/master/types/user.ts"
    click AD "https://github.com/duc-dev-starter/pawbloom/blob/master/schema/auth.ts"
    click AE "https://github.com/duc-dev-starter/pawbloom/blob/master/schema/blog.ts"
    click AF "https://github.com/duc-dev-starter/pawbloom/blob/master/schema/category.ts"
    click AG "https://github.com/duc-dev-starter/pawbloom/blob/master/schema/pet.ts"
    click AH "https://github.com/duc-dev-starter/pawbloom/blob/master/schema/product.ts"
    click AI "https://github.com/duc-dev-starter/pawbloom/tree/master/constants"

    %% Click Events for External & Config
    click AJ "https://github.com/duc-dev-starter/pawbloom/blob/master/lib/firebase.ts"
    click AK "https://github.com/duc-dev-starter/pawbloom/blob/master/lib/arcjet.ts"
    click AL "https://github.com/duc-dev-starter/pawbloom/blob/master/lib/utils.ts"
    click AM "https://github.com/duc-dev-starter/pawbloom/blob/master/next.config.js"
    click AN "https://github.com/duc-dev-starter/pawbloom/blob/master/tailwind.config.ts"
    click AO "https://github.com/duc-dev-starter/pawbloom/blob/master/postcss.config.mjs"
    click AP "https://github.com/duc-dev-starter/pawbloom/blob/master/.eslintrc.json"
```
