Skip to content

Commit 11d7475

Browse files
wechuliwechuli
committed
docs: Update README.md with comprehensive project overview and features
1 parent fa3ecce commit 11d7475

File tree

1 file changed

+187
-21
lines changed

1 file changed

+187
-21
lines changed

‎README.md‎

Lines changed: 187 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,202 @@
1-
This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
1+
# GitHub Reports Visualizer
22

3-
## Getting Started
3+
A powerful web application for visualizing and analyzing GitHub billing reports with interactive charts, advanced filtering, and comprehensive service breakdowns.
44

5-
First, run the development server:
5+
## 🎯 Overview
6+
7+
The GitHub Reports Visualizer transforms complex GitHub billing CSV data into intuitive, interactive visualizations. Built with Next.js 15 and TypeScript, it provides deep insights into GitHub Actions, Packages, Storage, Copilot, and Codespaces usage across organizations, repositories, and cost centers.
8+
9+
## ✨ Key Features
10+
11+
### 📊 Service-Based Analysis
12+
13+
- **Actions Minutes**: Track workflow execution time with repository-based breakdowns
14+
- **Actions Storage**: Monitor artifact and cache storage usage
15+
- **GitHub Packages**: Analyze package hosting costs and usage
16+
- **GitHub Copilot**: Visualize user engagement and costs
17+
- **Codespaces**: Monitor development environment usage
18+
19+
### 🔍 Advanced Filtering
20+
21+
- **Date Range**: Filter data by custom date ranges
22+
- **Organization**: Multi-organization support with breakdown views
23+
- **Cost Center**: Analyze costs by business units
24+
- **Repository**: Deep-dive into specific repository usage
25+
- **Cost vs Quantity**: Toggle between cost analysis ($) and usage volume
26+
27+
### 📈 Interactive Visualizations
28+
29+
- **Stacked Bar Charts**: Daily trends with repository/organization breakdowns
30+
- **Pie Charts**: Service distribution and repository analysis
31+
- **Area Charts**: Time-series cost and usage trends
32+
- **Summary Cards**: Key metrics and totals at a glance
33+
34+
### 🎨 Smart Chart Modes
35+
36+
- **Repository-Specific Views**: Focused analysis when filtering by repository
37+
- **Organization Breakdowns**: Stacked charts when multiple organizations are present
38+
- **Top 10 + Others**: Automatic grouping of less significant items
39+
- **Dynamic Breakdown**: Switch between cost and usage metrics instantly
40+
41+
## 🛠️ Technology Stack
42+
43+
- **Framework**: Next.js 15.5.2 with Turbopack
44+
- **Language**: TypeScript 5
45+
- **UI**: React 19.1.0 with Tailwind CSS 4
46+
- **Charts**: Recharts 3.1.2
47+
- **Icons**: Lucide React
48+
- **Styling**: Tailwind CSS with custom components
49+
50+
## 🚀 Getting Started
51+
52+
### Prerequisites
53+
54+
- Node.js 18+ installed on your machine
55+
- A GitHub billing report CSV file
56+
57+
### Installation
58+
59+
1. **Clone the repository**
60+
61+
```bash
62+
git clone https://github.com/wechuli/githubreportsvisualizer.git
63+
cd githubreportsvisualizer
64+
```
65+
66+
2. **Install dependencies**
67+
68+
```bash
69+
npm install
70+
# or
71+
yarn install
72+
# or
73+
pnpm install
74+
```
75+
76+
3. **Start the development server**
77+
78+
```bash
79+
npm run dev
80+
# or
81+
yarn dev
82+
# or
83+
pnpm dev
84+
```
85+
86+
4. **Open the application**
87+
88+
Navigate to [http://localhost:3000](http://localhost:3000) in your browser
89+
90+
### Building for Production
691

792
```bash
8-
npm run dev
9-
# or
10-
yarn dev
11-
# or
12-
pnpm dev
13-
# or
14-
bun dev
93+
# Build the application
94+
npm run build
95+
96+
# Start the production server
97+
npm run start
98+
```
99+
100+
## 📁 CSV File Format
101+
102+
The application expects GitHub billing CSV files with the following columns:
103+
104+
- `Date`: Usage date (YYYY-MM-DD format)
105+
- `Product`: GitHub service (Actions, Packages, etc.)
106+
- `SKU`: Specific service SKU
107+
- `Quantity`: Usage amount
108+
- `Unit Type`: Usage unit (minutes, GB-hours, etc.)
109+
- `Price Per Unit`: Cost per unit
110+
- `Multiplier`: Pricing multiplier
111+
- `Cost`: Total cost
112+
- `Repository Slug`: Repository identifier
113+
- `Organization`: GitHub organization
114+
- `Cost Center`: Business unit identifier
115+
116+
## 🎮 How to Use
117+
118+
1. **Upload Your Data**: Click "Choose File" and select your GitHub billing CSV
119+
2. **Explore Services**: Use the tabs to navigate between different GitHub services
120+
3. **Apply Filters**: Use the filter panel to narrow down your analysis
121+
4. **Toggle Breakdown**: Switch between Cost ($) and Usage Volume views
122+
5. **Repository Deep-Dive**: Filter by repository for focused analysis
123+
6. **Organization Analysis**: View organization breakdowns when multiple orgs are present
124+
125+
## 🏗️ Project Structure
126+
15127
```
128+
src/
129+
├── app/ # Next.js app directory
130+
│ ├── globals.css # Global styles
131+
│ ├── layout.tsx # Root layout
132+
│ └── page.tsx # Main application page
133+
├── components/
134+
│ ├── charts/ # Chart components
135+
│ │ └── ServiceChart.tsx
136+
│ └── ui/ # UI components
137+
│ ├── DataFilters.tsx
138+
│ ├── FileUpload.tsx
139+
│ ├── Navigation.tsx
140+
│ └── Tabs.tsx
141+
├── lib/
142+
│ ├── fileParser.ts # CSV parsing logic
143+
│ └── utils.ts # Utility functions
144+
└── types/
145+
└── billing.ts # TypeScript type definitions
146+
```
147+
148+
## 🎨 Features in Detail
149+
150+
### Service Categorization
151+
152+
- Automatically categorizes GitHub services from CSV data
153+
- Provides service-specific visualizations and metrics
154+
- Handles various GitHub product types and SKUs
155+
156+
### Smart Filtering
157+
158+
- Real-time data filtering without page reloads
159+
- Persistent filter state across service tabs
160+
- Visual indicators for active filters
161+
162+
### Responsive Design
163+
164+
- Mobile-friendly interface
165+
- Adaptive chart layouts
166+
- Touch-friendly controls
167+
168+
### Data Processing
169+
170+
- Client-side CSV parsing for privacy
171+
- Efficient data aggregation and grouping
172+
- Automatic date range detection
173+
174+
## 🤝 Contributing
16175

17-
Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
176+
1. Fork the repository
177+
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
178+
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
179+
4. Push to the branch (`git push origin feature/amazing-feature`)
180+
5. Open a Pull Request
18181

19-
You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
182+
## 📝 License
20183

21-
This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
184+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
22185

23-
## Learn More
186+
## 🐛 Known Issues
24187

25-
To learn more about Next.js, take a look at the following resources:
188+
- Large CSV files (>50MB) may cause performance issues
189+
- Browser compatibility tested on Chrome, Firefox, and Safari
190+
- Mobile responsiveness optimized for tablets and larger screens
26191

27-
- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
28-
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
192+
## 📧 Support
29193

30-
You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
194+
For issues, questions, or contributions, please:
31195

32-
## Deploy on Vercel
196+
- Open an issue on GitHub
197+
- Check existing documentation
198+
- Review the CSV format requirements
33199

34-
The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
200+
---
35201

36-
Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
202+
Built with ❤️ using Next.js and TypeScript

0 commit comments

Comments
 (0)