# davidskdevgithub/challenge-fravegatech architecture

> Architecture diagram of the GitHub repository davidskdevgithub/challenge-fravegatech, 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/davidskdevgithub/challenge-fravegatech
- Repository: https://github.com/davidskdevgithub/challenge-fravegatech

## Overview

##### Project type and purpose
- This is a full-stack React application built on Next.js.
- It implements a GitHub user search and detail viewer with client-side fetching (CSR) for the home/search page and server-side rendering (SSR) for user detail pages.
- It uses feature-based modules under `src/modules`, React Query for data fetching, Zustand for client state (favorites), Tailwind CSS for styling, and is deployed via Vercel with GitHub Actions CI/CD.

##### Main components
a. Browser (Client)
- Next.js front-end in the user’s browser
- UI components: SearchBar, UserList, UserCard, UserDetail, FavoriteIcon
- React Query layer (caching, loading/error states)
- Zustand store (favorites state)
b. Next.js Server (Serverless)
- SSR pages (e.g., `/users/[username]`)
- API Routes (e.g., `/api/hello`)
- Next.js build & static hosting (public assets, optimized fonts)
c. External Services
- GitHub REST API endpoints:
- GET /users
- GET /search/users?q={term}
- GET /users/{username}
d. CI/CD Pipeline & Hosting
- GitHub Actions workflows (ci.yml, cd.yml)
- Vercel deployment
e. Developer Tooling & Config
- ESLint, Tailwind config, Vitest (tests)

##### Relationships and data flow
1. Browser → Next.js SSR
- User navigates to `/users/[username]` → Next.js server pre-renders page
2. Browser → Next.js CSR
- Home page loads React app; SearchBar hook (`useDebounce`) invokes React Query
3. React Query → GitHub API
- Direct fetch calls from the client to GitHub’s endpoints for search/users and users/{username}
4. Zustand Store
- Favorite toggles update local state; persisted in-memory or localStorage
5. Browser ↔ Next.js API Routes
- (Optional) Could proxy through `/api/*`
6. CI/CD → Vercel
- Commits trigger GitHub Actions → build/test → deploy to Vercel

##### Architectural patterns and design principles
- Feature-based module structure (`src/modules/{search,users}`) grouping components, hooks, services, tests
- Clear separation of concerns:
- UI (components)
- Logic (hooks)
- Data access (services)
- State (Zustand store)
- Hybrid rendering: CSR for dynamic search, SSR for SEO-critical detail pages
- Serverless functions for lightweight APIs and edge optimizations
- Automated testing with Vitest and ESLint for code quality

##### Must-include elements
- Component labels (e.g., “SearchInput.tsx,” “useGitHubUsers()”)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Client Layer
    subgraph "Browser (Client)"
        direction TB
        CSRPage["Home/Search Page\n(index.tsx)"]:::frontend
        subgraph "Search Feature" 
            direction TB
            SearchInput["SearchInput.tsx"]:::frontend
            UseDebounce["useDebounce.ts"]:::data
            UseGitHubUsers["useGitHubUsers.ts"]:::data
            UserList["UserList.tsx"]:::frontend
            UserCard["UserCard.tsx"]:::frontend
        end
        CSRPage -->|"renders"| SearchInput
        SearchInput -->|"uses"| UseDebounce
        UseDebounce -->|"calls"| UseGitHubUsers
        UseGitHubUsers -->|"fetches"| GitHubAPIService
        GitHubAPIService -->|"calls"| GitHubAPI[("GitHub REST API")]:::external
        SearchInput -->|"updates"| FavoritesStore
        FavoritesStore["Favorites Store"]:::state
        subgraph "Users Feature (Client)"
            direction TB
            FavoriteIcon["FavoriteIcon.tsx"]:::frontend
            UseFavorite["useFavorite.ts"]:::state
        end
        FavoriteIcon -->|"toggles"| UseFavorite
        UseFavorite -->|"updates"| FavoritesStore
    end

    %% Next.js Serverless Layer
    subgraph "Next.js Serverless"
        direction TB
        SSRPage["UserDetail Page\n([username].tsx)"]:::server
        APIRoute["API Route\n(hello.ts)"]:::server
        SSRPage -->|"SSR data via"| UseGitHubUserDetails
        UseGitHubUserDetails["useGitHubUserDetails.ts"]:::data
        UseGitHubUserDetails -->|"fetches"| GitHubAPIService
    end

    %% Developer Tooling & Config
    subgraph "Developer Tooling & Config"
        direction TB
        ESLint["ESLint Config"]:::data
        Tailwind["Tailwind Config"]:::data
        VitestConfig["Vitest Config\n(vitest.config.mts)"]:::data
        VitestSetup["Vitest Setup\n(vitest.setup.mts)"]:::data
        NextConfig["Next.js Config\n(next.config.mjs)"]:::server
    end

    %% CI/CD & Hosting
    subgraph "CI/CD & Hosting"
        direction TB
        CIWorkflow["GitHub Actions CI"]:::cicd
        CDWorkflow["GitHub Actions CD"]:::cicd
        Vercel["Vercel Deployment"]:::cicd
        CIWorkflow -->|"triggers"| CDWorkflow
        CDWorkflow -->|"deploys"| Vercel
    end

    %% External Services
    GitHubAPIService["GitHub API Service\n(github-api.ts)"]:::data

    %% Connections between Browser and Server
    CSRPage -->|"optional proxy"| APIRoute
    SSRPage -->|"pre-renders"| SSRPage
    CSRPage -->|"client-side rendering"| CSRPage

    %% Click Events
    click SearchInput "https://github.com/davidskdevgithub/challenge-fravegatech/blob/main/src/modules/search/components/search-input.tsx"
    click UseDebounce "https://github.com/davidskdevgithub/challenge-fravegatech/blob/main/src/modules/search/hooks/useDebounce.ts"
    click GitHubAPIService "https://github.com/davidskdevgithub/challenge-fravegatech/blob/main/src/modules/users/services/github-api.ts"
    click UseGitHubUsers "https://github.com/davidskdevgithub/challenge-fravegatech/blob/main/src/modules/users/hooks/useGitHubUsers.ts"
    click UseGitHubUserDetails "https://github.com/davidskdevgithub/challenge-fravegatech/blob/main/src/modules/users/hooks/useGitHubUserDetails.ts"
    click UseFavorite "https://github.com/davidskdevgithub/challenge-fravegatech/blob/main/src/modules/users/hooks/useFavorite.ts"
    click FavoritesStore "https://github.com/davidskdevgithub/challenge-fravegatech/blob/main/src/modules/users/store/favoritesStore.ts"
    click UserList "https://github.com/davidskdevgithub/challenge-fravegatech/blob/main/src/modules/users/components/user-list.tsx"
    click UserCard "https://github.com/davidskdevgithub/challenge-fravegatech/blob/main/src/modules/users/components/user-card.tsx"
    click UserDetail "https://github.com/davidskdevgithub/challenge-fravegatech/blob/main/src/modules/users/components/user-detail.tsx"
    click FavoriteIcon "https://github.com/davidskdevgithub/challenge-fravegatech/blob/main/src/modules/users/components/user-favorite.tsx"
    click CSRPage "https://github.com/davidskdevgithub/challenge-fravegatech/blob/main/src/pages/index.tsx"
    click SSRPage "https://github.com/davidskdevgithub/challenge-fravegatech/blob/main/src/pages/users/[username].tsx"
    click APIRoute "https://github.com/davidskdevgithub/challenge-fravegatech/blob/main/src/pages/api/hello.ts"
    click CIWorkflow "https://github.com/davidskdevgithub/challenge-fravegatech/blob/main/.github/workflows/ci.yml"
    click CDWorkflow "https://github.com/davidskdevgithub/challenge-fravegatech/blob/main/.github/workflows/cd.yml"
    click NextConfig "https://github.com/davidskdevgithub/challenge-fravegatech/blob/main/next.config.mjs"
    click ESLint "https://github.com/davidskdevgithub/challenge-fravegatech/blob/main/.eslintrc.json"
    click Tailwind "https://github.com/davidskdevgithub/challenge-fravegatech/blob/main/tailwind.config.ts"
    click VitestConfig "https://github.com/davidskdevgithub/challenge-fravegatech/blob/main/vitest.config.mts"
    click VitestSetup "https://github.com/davidskdevgithub/challenge-fravegatech/blob/main/vitest.setup.mts"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#007bff,color:#004085
    classDef data fill:#d4edda,stroke:#28a745,color:#155724
    classDef server fill:#fff3cd,stroke:#ffc107,color:#856404
    classDef state fill:#d6d8db,stroke:#6c757d,color:#343a40
    classDef external fill:#e2e3e5,stroke:#adb5bd,color:#495057
    classDef cicd fill:#ffeeba,stroke:#fd7e14,color:#856404
```
