How ximepaparella/challenge-xp works
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