Statistics Dashboard
Relevant source files
The following files were used as context for generating this wiki page:
The Statistics Dashboard is a high-level monitoring system within the PCSTYLE ecosystem designed to provide real-time visibility into developer productivity and open-source contributions. It aggregates data from two primary external providers: GitHub and WakaTime. The dashboard serves as a central hub for "SYSTEM_METRICS," displaying a mix of historical aggregates and live coding activity.
The dashboard is structured into two main architectural sections: the GitHub Profile section, focusing on repository health and contribution frequency, and the WakaTime Metrics section, focusing on specific coding behaviors such as language distribution, editor usage, and daily time investments.
Sources: pages/Stats.tsx:112-140, components/ui/WakaTimeDashboard.tsx:64-122
System Architecture and Data Flow
The dashboard follows a decoupled architecture where a Hono-based Edge API acts as a proxy and cache layer between the frontend and external providers. React hooks (useGitHubStats, useWakaTimeSummary) consume these API endpoints to provide reactive state to UI components.
Data Acquisition Flow
The following diagram illustrates how coding statistics are retrieved, cached, and rendered:
The Edge API implements a robust fetch mechanism with a DEFAULT_CACHE_TTL of 60 seconds for WakaTime data and a GH_CACHE_TTL of 5 minutes for GitHub data to prevent rate-limiting.
Sources: api/index.ts:47-90, api/index.ts:139-150, hooks/useWakaTime.ts:15-46
Component Breakdown
GitHub Metrics
The GitHub section provides high-level metrics via the GitHubMainStats and GitHubExtraStats components. It utilizes a 3D Voxel Grid (VisualContributionHeatmap) to visualize the intensity of contributions over the last 14 weeks.
| Component | Description | Data Source |
|---|---|---|
GitHubMainStats | Displays Repos, Stars, Followers, and Following counts. | GitHubStats |
VisualContributionHeatmap | A 3D parallax-enabled heatmap using Framer Motion to show contribution levels. | GitHubContributions |
GitHubExtraStats | Displays total commit counts and the most active recent repository. | GitHubStats |
Sources: pages/Stats.tsx:9-85, components/ui/VisualContributionHeatmap.tsx:42-60
WakaTime Metrics
The WakaTime implementation focuses on detailed coding environment analysis, broken down into time, tools, and technology.
- Primary Stats: Includes Total Time, Daily Average, Best Day, and Language Count.
- Neural Language Map: A specialized component that visualizes language frequency as a "neural flow" with pulse animations and digital fragments for languages exceeding a 20% usage threshold.
- Project Matrix: Maps coding time across specific projects using a bit-matrix style progress bar.
Sources: components/ui/WakaTimeDashboard.tsx:88-100, components/ui/NeuralLanguageMap.tsx:45-100, components/ui/ProjectMatrix.tsx:35-70
Data Models
The system relies on strongly typed interfaces to ensure consistency between the Edge API and the React components.
// From lib/types.ts
export interface WakaTimeSummary {
totalSeconds: number;
totalHours: number;
dailyAverage: number;
languages: WakaTimeLanguage[];
editors: WakaTimeEditor[];
projects: WakaTimeProject[];
bestDay: { date: string; seconds: number } | null;
range: { start: string; end: string };
}
export interface GitHubStats {
publicRepos: number;
followers: number;
following: number;
totalStars: number;
totalCommits?: number;
mostActiveRepo?: {
name: string;
url: string;
commits: number;
};
}
Sources: lib/types.ts:44-53, lib/types.ts:74-89
API Endpoints
The backend implementation uses Hono and is optimized for the Vercel Edge Runtime. It includes middleware to validate environment variables (WAKATIME_API_KEY, GITHUB_TOKEN) before processing requests.
| Endpoint | Method | Description | Cache TTL |
|---|---|---|---|
/api/wakatime/summary | GET | Aggregates 7-day WakaTime statistics for languages, editors, and projects. | 60s |
/api/wakatime/status | GET | Retrieves current "live" coding status (heartbeat). | 60s |
/api/github/contributions | GET | Fetches GraphQL contribution calendar data. | 300s |
/api/github/stats | GET | Aggregates user profile, star counts, and recent push events. | 300s |
Sources: api/index.ts:114-130, api/index.ts:139-145, api/index.ts:245-255
UI/UX Features
The Statistics Dashboard utilizes several advanced UI techniques to maintain a "Cyberpunk/System" aesthetic:
- Motion Parallax: The
VisualContributionHeatmapusesuseSpringanduseTransformto rotate the 3D grid based on user mouse movement. - Scanline Animations: Components like
ProjectMatrixfeature moving scanlines and pulse effects. - Real-time Feedback: Loading states use pulse animations and specific "System Loading" text (e.g., "MAPPING_PROJECT_SPACE").
Sources: components/ui/VisualContributionHeatmap.tsx:18-36, components/ui/ProjectMatrix.tsx:28-33, pages/Stats.tsx:15-22
Summary
The Statistics Dashboard provides a comprehensive view of developer activity by bridging external API data with a high-fidelity visual interface. Through the use of Edge caching and reactive hooks, it delivers performant, real-time metrics while maintaining a cohesive aesthetic aligned with the PCSTYLE project requirements.