# tbarondar/furry-agents-of-chaos architecture

> Architecture diagram of the GitHub repository tbarondar/furry-agents-of-chaos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tbarondar/furry-agents-of-chaos
- Repository: https://github.com/tbarondar/furry-agents-of-chaos

## Overview

##### Project type and purpose
- This is a single‐page frontend application (SPA) built with React, TypeScript, Vite, Redux and Material-UI.
- Its purpose is to browse cat data: view breeds, individual cats, manage favorites (persisted in local storage), and display modals for details. Data comes from an external Cats API, validated with Zod.

##### File structure
- Top-level config & tooling:
- pre‐commit hooks (scripts/)
- ESLint, Prettier, Vite config, tsconfig, package.json
- public/index.html and assets
- Entry point: src/main.tsx → App.tsx → routing (create-router.tsx)
- src/config: axios instance, router factory, Redux store, MUI theme
- src/modules: feature modules (about, breeds, cats, favorites) each with page, components & hooks
- src/shared:
- components (layout, app bar, loading spinner, error handler, modals)
- dto definitions for API payloads
- Redux reducers, services (query wrapper, Zod validation), utility functions
- Deployment config: vercel.json, .env support

##### README for extra context
- Confirms tech stack: React Router, Redux store, Axios, Zod, MUI.
- Routes for “about”, “breeds”, “cats”, “favorites”.
- Goals: loading states, error handling, storing favorites in localStorage, CI/CD on Vercel.

a. Main components:
- UI Layer (React + MUI)
- Feature modules: BreedsPage, CatsPage, FavoritesPage, AboutPage
- Shared layout: AppBar, MainLayout, LoadingSpinner, GlobalErrorHandler, Modals (CatDetails)
- Routing Layer (React Router)
- State Management (Redux Store + Reducers)
- Service Layer (AxiosInstance + Query API + Zod Validation)
- Persistence: LocalStorage (guest user, favorites)
- External Service: Cats REST API
- Build/Dev Tools (Vite, ESLint, Prettier, pre-commit hooks)
- Deployment Platform: Vercel

b. Relationships & interactions:
- User interacts with UI components → dispatches Redux actions
- Redux middleware (thunks) invoke Service Layer
- AxiosInstance sends HTTP requests → external Cats API → JSON response
- Response flows through Zod validators → normalized DTOs → Redux reducers update store
- UI (subscribed to store) re-renders updated views
- Favorites actions also read/write to LocalStorage
- React Router switches pages & handles fallback errors via Shared ErrorHandler
- Build chain (Vite) bundles code; pre-commit hooks enforce lint/format rules; Vercel handles CI/CD

c. Architectural patterns & design principles:
- Feature-based modularization (each domain in its own folder)
- Unidirectional data flow (Redux)
- Separation of concerns: UI, routing, state, services, validation
- DTOs + Zod for safe API contracts
- Shared components for consistent look & feel

d. Key technologies/frameworks:
- React + React Router
- Redux Toolkit (store, reducers)
- Axios with custom instance & interceptors
- Zod for runtime schema validation
- Material-UI for UI
- Vite for development & bundling
- ESLint/Prettier for code quality
- Vercel for deployment

##### Diagramming recommendations
- UI components (blue)
- State/Routing (green)
- Services/Validation (purple)
- External systems (orange)
- Rectangles for modules/services
- Cloud symbol for external API

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        BreedsPage["BreedsPage"]:::ui
        BreedCard["BreedCard"]:::ui
        BreedsList["BreedsList"]:::ui
        useBreedCard["use-breed-card"]:::ui
        useBreedCats["use-breed-cats"]:::ui

        CatsPage["CatsPage"]:::ui
        CatCard["CatCard"]:::ui
        CatsList["CatsList"]:::ui
        useCatsPage["use-cats-page"]:::ui

        FavoritesPage["FavoritesPage"]:::ui
        FavoriteCard["FavoriteCard"]:::ui
        FavoritesList["FavoritesList"]:::ui
        useFavoritesPage["use-favorites-page"]:::ui

        AboutPage["AboutPage"]:::ui

        CustomAppBar["CustomAppBar"]:::ui
        MainLayout["MainLayout"]:::ui
        LoadingSpinner["LoadingSpinner"]:::ui
        GlobalErrorHandler["GlobalErrorHandler"]:::ui
        RouterErrorFallback["RouterErrorFallback"]:::ui
        CatModal["CatDetailsModal"]:::ui
        GuestCard["GuestCard"]:::ui
        useCatDetails["use-cat-details"]:::ui
    end

    %% State & Routing Layer
    subgraph "State & Routing Layer"
        direction TB
        Router["create-router"]:::state
        Store["Redux Store"]:::state
        AppReducer["app.reducer"]:::state
        CatsReducer["cats.reducer"]:::state
        LoadingReducer["loading.reducer"]:::state
    end

    %% Service & Validation Layer
    subgraph "Service & Validation Layer"
        direction TB
        AxiosInstance["axios-instance"]:::service
        QueryAPI["api (Query API Service)"]:::service
        QueryConfig["config (Query Config)"]:::service
        ZodEnhancer["zod-validation-enhancer"]:::service
        DTOs["DTO Definitions"]:::service
        ChunkUtils["chunk-arrays"]:::service
        ErrorTestBtn["ErrorTestButton"]:::service
    end

    %% Persistence & External
    subgraph "Persistence & External"
        direction TB
        LocalStorage["LocalStorage"]:::persistence
        CatsAPI["Cats REST API"]:::external
    end

    %% Build & Dev Pipeline
    subgraph "Build & Dev Pipeline"
        direction TB
        PreCommitESLint["pre-commit-eslint.sh"]:::pipeline
        PreCommitPrettier["pre-commit-prettier.sh"]:::pipeline
        ViteConfig["vite.config.ts"]:::pipeline
        ESLintConfig["eslint.config.mjs"]:::pipeline
        PrettierRC[".prettierrc"]:::pipeline
        VercelConfig["vercel.json"]:::pipeline
        TSConfigs["tsconfig*.json"]:::pipeline
        Readme["README.md"]:::pipeline
        PublicAssets["index.html & public/"]:::pipeline
        PackageManifests["package.json & lock"]:::pipeline
        PrettierIgnore[".prettierignore"]:::pipeline
        GitIgnore[".gitignore"]:::pipeline
    end

    %% Connections
    Router -->|"routes to"| BreedsPage
    Router -->|"routes to"| CatsPage
    Router -->|"routes to"| FavoritesPage
    Router -->|"routes to"| AboutPage

    BreedsPage -->|"uses"| BreedCard
    BreedsPage -->|"uses"| BreedsList
    BreedCard -->|"hook"| useBreedCard
    BreedsList -->|"hook"| useBreedCats

    CatsPage -->|"uses"| CatCard
    CatsPage -->|"uses"| CatsList
    CatsList -->|"hook"| useCatsPage

    FavoritesPage -->|"uses"| FavoriteCard
    FavoritesPage -->|"uses"| FavoritesList
    FavoritesList -->|"hook"| useFavoritesPage

    CatModal -->|"uses"| GuestCard
    CatModal -->|"hook"| useCatDetails

    BreedsPage -->|"dispatch actions"| Store
    CatsPage -->|"dispatch actions"| Store
    FavoritesPage -->|"dispatch actions"| Store

    Store -->|"thunks call"| AxiosInstance
    AxiosInstance -->|"HTTP Request"| CatsAPI
    CatsAPI -->|"JSON Response"| ZodEnhancer
    ZodEnhancer -->|"validated DTO"| QueryAPI
    QueryAPI -->|"returns data"| Store

    FavoritesPage -->|"read/write"| LocalStorage
    Store -->|"subscribe"| GlobalErrorHandler
    Store -->|"subscribe"| LoadingSpinner
    Store -->|"subscribe"| RouterErrorFallback

    %% Build pipeline connections
    PreCommitESLint --> ViteConfig
    PreCommitPrettier --> ViteConfig
    ViteConfig --> VercelConfig

    %% Click Events
    click BreedsPage "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/src/modules/breeds/breeds-page.tsx"
    click BreedCard "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/src/modules/breeds/components/breed-card.tsx"
    click BreedsList "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/src/modules/breeds/components/breeds-list.tsx"
    click useBreedCard "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/src/modules/breeds/hooks/use-breed-card.ts"
    click useBreedCats "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/src/modules/breeds/hooks/use-breed-cats.ts"
    click CatsPage "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/src/modules/cats/cats-page.tsx"
    click CatCard "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/src/modules/cats/components/cat-card.tsx"
    click CatsList "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/src/modules/cats/components/cats-list.tsx"
    click useCatsPage "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/src/modules/cats/hooks/use-cats-page.ts"
    click FavoritesPage "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/src/modules/favorites/favorites-page.tsx"
    click FavoriteCard "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/src/modules/favorites/components/favorite-card.tsx"
    click FavoritesList "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/src/modules/favorites/components/favorites-list.tsx"
    click useFavoritesPage "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/src/modules/favorites/hooks/use-favorites-page.ts"
    click AboutPage "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/src/modules/about/about.tsx"
    click CustomAppBar "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/src/shared/components/custom-app-bar.tsx"
    click MainLayout "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/src/shared/components/main-layout.tsx"
    click LoadingSpinner "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/src/shared/components/custom-loading-spinner.tsx"
    click GlobalErrorHandler "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/src/shared/components/global-error-handler.tsx"
    click RouterErrorFallback "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/src/shared/components/router-error-fallback.tsx"
    click CatModal "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/src/shared/components/modals/cat-details/cat-modal.tsx"
    click GuestCard "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/src/shared/components/modals/cat-details/guest-card.tsx"
    click useCatDetails "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/src/shared/components/modals/cat-details/hooks/use-cat-details.ts"
    click Router "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/src/config/create-router.tsx"
    click Store "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/src/config/store.ts"
    click AxiosInstance "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/src/config/axios-instance.ts"
    click ViteConfig "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/vite.config.ts"
    click ESLintConfig "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/eslint.config.mjs"
    click PreCommitESLint "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/scripts/pre-commit-eslint.sh"
    click PreCommitPrettier "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/scripts/pre-commit-prettier.sh"
    click VercelConfig "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/vercel.json"
    click TSConfigs "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/tsconfig.json"
    click PublicAssets "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/index.html"
    click PackageManifests "https://github.com/tbarondar/furry-agents-of-chaos/blob/main/package.json"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef state fill:#D0FFD0,stroke:#333,stroke-width:1px
    classDef service fill:#E8D0FF,stroke:#333,stroke-width:1px
    classDef external fill:#FFE8D0,stroke:#333,stroke-width:1px
    classDef persistence fill:#FFF0D0,stroke:#333,stroke-width:1px
    classDef pipeline fill:#F0F0F0,stroke:#333,stroke-width:1px
```
