# devanup/devtective architecture

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

- Interactive diagram: https://gitdiagram.com/devanup/devtective
- Repository: https://github.com/devanup/devtective

## Overview

##### Main Components
- Frontend (UI & Client-Side Rendering):
- The primary UI is implemented using Next.js (see the src/app directory and the multiple React components spread across src/components). This includes layout, pages, and specialized components such as Header, Footer, and various cards for user profiles and repository stats.
- Within the UI, there are grouped components for charts (e.g., CommitActivity, TopLanguages, MostStarredChart) that render visual analytics.
- A theming mechanism is provided (refer to src/components/theme-provider.tsx) and several custom UI components under src/components/ui (like buttons, cards, inputs) that help in building a unified interface.

- Data Fetching & Business Logic Layer:
- The data access layer is clearly separated within the src/lib directory, where individual modules handle GitHub API calls (fetchUser, fetchRepoStats, etc.) and parse analytics (getContributions, getTopContributingRepos, etc.).
- There are also custom hooks (in src/hooks) such as useLocalStorage that help manage state and enhance reusability.

- External Service Integration:
- The external GitHub API (including use of GitHub GraphQL API as mentioned in the README) is central to the data sourcing, where the libraries in src/lib act as a bridge between the external data source and the internal components.

##### Relationships and Interactions
- The client-side components request data indirectly by invoking the functions found in the src/lib directory.
- Data flows from external APIs (GitHub API) → library functions (data fetching/parsing, e.g., fetchUser, getLangData) → custom hooks (e.g., useLocalStorage to manage client state) → presentation components (charts, UI cards).
- Layout components (in src/app and layout.tsx) act as the orchestrators that include Header, Footer, and main content components (like ProfileOverview and RepoOverview) which in turn use the more granular UI and chart components.

##### Architectural Patterns and Design Principles
- Separation of concerns: The project clearly separates UI components, data fetching logic, and utility functions. This modular setup makes it easier to manage and extend functionality.
- Component-driven architecture: By structuring the project into reusable components (especially in folders like ui, charts, skeletons, repository, user), the design supports maintainability and scalability.
- Use of TypeScript for type safety ensures robustness throughout the project.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        NXUI["Next.js UI (Layout & Pages)"]
        GenUI["General UI Components (Header, Footer, ProfileOverview, RepoOverview)"]
        Charts["Chart Components (CommitActivity, MostStarred, TopContributing, TopLanguages, TotalContributed)"]
        Theme["Theming Mechanism"]
        UIWidgets["UI Library/Widgets (Buttons, Cards, Inputs)"]
        RepoComponents["Repository Components (ReposTabs, StatisticsTab, Tabs, TopContributed)"]
        UserComponents["User Components (UserCard, UserAvatarCard, ProfileStatCard, UserDetailsCard, PinnedRepos)"]
        Skeletons["Skeleton/Placeholder Components"]
    end

    %% Data Access & Business Logic Layer
    subgraph "Data Access & Business Logic"
        DataLib["Data Fetching & Processing Modules"]
        Hooks["Custom Hooks (State Management)"]
        Types["Type Definitions (TypeScript Types)"]
    end

    %% External Services Layer
    subgraph "External Services"
        GitHubAPI["GitHub API & GraphQL"]
    end

    %% Interactions within Frontend
    NXUI -->|"renders"| GenUI
    NXUI -->|"renders"| Charts
    NXUI -->|"applies"| Theme
    NXUI -->|"integrates"| UIWidgets
    NXUI -->|"includes"| RepoComponents
    NXUI -->|"includes"| UserComponents
    NXUI -->|"uses for loading"| Skeletons

    %% Interaction between Frontend and Data Layer
    NXUI -->|"fetches data via"| DataLib
    DataLib -->|"processes API calls from"| GitHubAPI
    DataLib -->|"updates state using"| Hooks
    Hooks -->|"provides state to"| NXUI
    DataLib -->|"references"| Types

    %% Styling
    class NXUI,GenUI,Charts,Theme,UIWidgets,RepoComponents,UserComponents,Skeletons frontend
    class DataLib,Hooks,Types data
    class GitHubAPI external

    %% Class Definitions
    classDef frontend fill:#B3D7FF,stroke:#333,stroke-width:1px;
    classDef data fill:#C3E6CB,stroke:#333,stroke-width:1px;
    classDef external fill:#F8D7DA,stroke:#333,stroke-width:1px;

    %% Click Events for Component Mappings
    click NXUI "https://github.com/devanup/devtective/tree/main/src/app"
    click GenUI "https://github.com/devanup/devtective/blob/main/src/components/Header.tsx"
    click Charts "https://github.com/devanup/devtective/tree/main/src/components/charts"
    click Theme "https://github.com/devanup/devtective/blob/main/src/components/theme-provider.tsx"
    click UIWidgets "https://github.com/devanup/devtective/tree/main/src/components/ui"
    click RepoComponents "https://github.com/devanup/devtective/tree/main/src/components/repository"
    click UserComponents "https://github.com/devanup/devtective/tree/main/src/components/user"
    click Skeletons "https://github.com/devanup/devtective/tree/main/src/components/skeletons"
    click DataLib "https://github.com/devanup/devtective/tree/main/src/lib"
    click Hooks "https://github.com/devanup/devtective/tree/main/src/hooks"
    click Types "https://github.com/devanup/devtective/tree/main/src/types"
```
