# ximepaparella/challenge-xp architecture

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

- Interactive diagram: https://gitdiagram.com/ximepaparella/challenge-xp
- Repository: https://github.com/ximepaparella/challenge-xp

## Overview

##### Project Type and Purpose
- This is a full-stack, server‐rendered web application (Next.js + TypeScript) for exploring GitHub user profiles.
- It provides search, user detail pages, favorites management, offline mode (mock data), caching, request deduplication, and comprehensive error handling.

##### Main Architectural Components
a. User Interface (Browser)
- Next.js pages (Server-Side Rendering + Client hydration)
- React components (core UI library + feature-specific components)
- Global styles, CSS Modules
b. Application Logic (Client + Server)
- Core hooks (useDebounce, useDeduplication, useApiClientInstance, retry, pagination)
- Feature modules (users, favorites, repositories, home)
- Context API (FavoritesContext)
c. Data & Services
- ApiClient (core/api) interacting with GitHub REST API
- Caching layer (in-memory cache in ApiClient + useGithubCache hook)
- Request deduplication layer (in-flight request tracker)
- Retry strategy (useRetryStrategy hook)
- MockDataService (fallback when offline or API limit reached)
- Environment variables (.env.local for GitHub token)
d. External Systems
- GitHub public API
- Optional local mock data (fallback)

##### Relationships and Data Flow
1) User enters query in SearchBar → debounced input triggers useGithubService (feature/users)
2) useGithubService calls ApiClient → checks cache → if miss, checks deduplication → issues HTTP request to GitHub API or MockDataService
3) ApiClient receives response → updates cache → resolves promise → hook returns data to component
4) React component renders user list or detail → user may click “favorite” → FavoritesContext updates persisted state (e.g., localStorage)
5) Pages (_app.tsx, index.tsx, [username].tsx) orchestrate SSR, data fetching (getServerSideProps) and wrap components in MainLayout with Header/Footer

##### Architectural Patterns & Principles
- Modular domain-driven structure: core vs features
- Separation of concerns: UI (components) vs data logic (services, hooks)
- Context API for global state (favorites)
- Custom hooks for cross-cutting concerns (debounce, caching, retry, deduplication)
- Fallback strategy: graceful degradation to mock services
- SSR for SEO and performance, client hydration for interactivity

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer (Browser Client)
    subgraph "Browser Client" 
        direction TB
        subgraph "UI Components" 
            direction TB
            SearchBar["SearchBar"]:::frontend
            UserList["UserList / UserGrid / UserCard"]:::frontend
            UserDetailComp["UserDetail / UserProfile / UserStats"]:::frontend
            FavoriteButton["FavoriteButton"]:::frontend
            Header["Header"]:::frontend
            Footer["Footer"]:::frontend
        end
        subgraph "Pages (CSR Hydration)"
            direction TB
            HomePage["HomeView"]:::frontend
        end
    end

    %% Hooks & Services Layer
    subgraph "Hooks & Services" 
        direction TB
        useGithubService["useGithubService"]:::service
        useDebounce["useDebounce"]:::service
        useDeduplication["useDeduplication"]:::service
        useGithubCache["useGithubCache"]:::service
        useRetry["useRetryStrategy"]:::service
        ApiClientInstance["useApiClientInstance"]:::service
        GithubService["GithubService"]:::service
        MockDataService["MockDataService"]:::external
    end

    %% API Client Layer
    subgraph "ApiClient Layer"
        direction TB
        ApiClient["ApiClient"]:::service
        Cache["In-Memory Cache"]:::store
        Dedup["Request Deduplication"]:::store
        RetryStrategy["Retry Strategy"]:::store
    end

    %% Context & Caching
    subgraph "Global State"
        direction TB
        FavoritesContext["FavoritesContext"]:::store
        LocalStorage["LocalStorage"]:::store
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        GithubAPI["GitHub Public API"]:::external
    end

    %% Next.js Server (SSR)
    subgraph "Next.js Server (SSR)"
        direction TB
        App["_app.tsx"]:::frontend
        Document["_document.tsx"]:::frontend
        HomePageSSR["index.tsx"]:::frontend
        FavoritesPage["favorites.tsx"]:::frontend
        UserDetailPage["user/[username].tsx"]:::frontend
    end

    %% Styles & Env
    Styles["Global Styles & CSS Modules"]:::frontend
    Env[".env.local"]:::external

    %% Connections
    SearchBar -->|debounced input| useDebounce
    useDebounce --> useGithubService
    UserList --> useGithubService
    UserDetailComp --> useGithubService
    useGithubService --> ApiClientInstance
    ApiClientInstance --> ApiClient
    ApiClient --> Cache
    ApiClient --> Dedup
    ApiClient --> RetryStrategy
    ApiClient -->|HTTP Request| GithubAPI
    ApiClient -->|Fallback| MockDataService
    ApiClient -->|Response| useGithubService
    useGithubService --> SearchBar
    FavoriteButton --> FavoritesContext
    FavoritesContext --> LocalStorage
    SSR_BACKEND_CALLS --> ApiClient
    HomePageSSR --> ApiClientInstance
    FavoritesPage --> ApiClientInstance
    UserDetailPage --> ApiClientInstance
    App --> HomePageSSR
    App --> FavoritesPage
    App --> UserDetailPage
    App --> Document
    Styles --> SearchBar
    Styles --> Header
    Styles --> Footer
    Styles --> HomePageSSR
    Env --> ApiClient

    %% Click Events
    click App "https://github.com/ximepaparella/challenge-xp/blob/main/src/pages/_app.tsx"
    click Document "https://github.com/ximepaparella/challenge-xp/blob/main/src/pages/_document.tsx"
    click HomePageSSR "https://github.com/ximepaparella/challenge-xp/blob/main/src/pages/index.tsx"
    click FavoritesPage "https://github.com/ximepaparella/challenge-xp/blob/main/src/pages/favorites.tsx"
    click UserDetailPage "https://github.com/ximepaparella/challenge-xp/blob/main/src/pages/user/[username].tsx"
    click Header "https://github.com/ximepaparella/challenge-xp/blob/main/src/core/components/Header/index.tsx"
    click Footer "https://github.com/ximepaparella/challenge-xp/blob/main/src/core/components/Footer/index.tsx"
    click SearchBar "https://github.com/ximepaparella/challenge-xp/blob/main/src/core/components/SearchBar/index.tsx"
    click ApiClient "https://github.com/ximepaparella/challenge-xp/blob/main/src/core/api/ApiClient.ts"
    click MockDataService "https://github.com/ximepaparella/challenge-xp/blob/main/src/core/services/MockDataService.ts"
    click useApiClientInstance "https://github.com/ximepaparella/challenge-xp/blob/main/src/core/hooks/useApiClientInstance.ts"
    click useDebounce "https://github.com/ximepaparella/challenge-xp/blob/main/src/core/hooks/useDebounce.ts"
    click useDeduplication "https://github.com/ximepaparella/challenge-xp/blob/main/src/core/hooks/useDeduplication.ts"
    click useGithubCache "https://github.com/ximepaparella/challenge-xp/blob/main/src/core/hooks/useGithubCache.ts"
    click useRetryStrategy "https://github.com/ximepaparella/challenge-xp/blob/main/src/core/hooks/useRetryStrategy.ts"
    click FavoritesContext "https://github.com/ximepaparella/challenge-xp/blob/main/src/features/favorites/context/FavoritesContext.tsx"
    click GithubService "https://github.com/ximepaparella/challenge-xp/blob/main/src/features/users/services/GithubService.ts"
    click useGithubService "https://github.com/ximepaparella/challenge-xp/blob/main/src/features/users/hooks/useGithubService.ts"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,stroke-width:1px
    classDef service fill:#E6FFED,stroke:#28A745,stroke-width:1px
    classDef store fill:#FFF5D1,stroke:#C9510C,stroke-width:1px
    classDef external fill:#F3E5FF,stroke:#6F42C1,stroke-width:1px
```
