Skip to content

Commit b970d35

Browse files
TimLFletcherTimLFletcher
committed
Initial commit
0 parents  commit b970d35

26 files changed

Lines changed: 4941 additions & 0 deletions

‎.github/workflows/fetch-and-deploy.yml‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
name: Fetch Data and Deploy
2+
3+
on:
4+
# Run on schedule (every 6 hours)
5+
schedule:
6+
- cron: '0 */6 * * *'
7+
# Allow manual trigger
8+
workflow_dispatch:
9+
# Run on push to main (for initial setup)
10+
push:
11+
branches: [main]
12+
13+
permissions:
14+
contents: write
15+
pages: write
16+
id-token: write
17+
18+
jobs:
19+
fetch-and-deploy:
20+
runs-on: ubuntu-latest
21+
22+
steps:
23+
- name: Checkout repository
24+
uses: actions/checkout@v4
25+
26+
- name: Setup Node.js
27+
uses: actions/setup-node@v4
28+
with:
29+
node-version: '20'
30+
cache: 'npm'
31+
32+
- name: Install dependencies
33+
run: npm ci
34+
35+
- name: Fetch data from GA and Jira
36+
env:
37+
# Google Analytics
38+
GA_PROPERTY_ID: ${{ secrets.GA_PROPERTY_ID }}
39+
GOOGLE_SERVICE_ACCOUNT_KEY: ${{ secrets.GOOGLE_SERVICE_ACCOUNT_KEY }}
40+
# Jira
41+
JIRA_BASE_URL: ${{ secrets.JIRA_BASE_URL }}
42+
JIRA_EMAIL: ${{ secrets.JIRA_EMAIL }}
43+
JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}
44+
JIRA_PROJECT_KEY: ${{ secrets.JIRA_PROJECT_KEY }}
45+
run: npm run fetch-data
46+
47+
- name: Build dashboard
48+
run: npm run build
49+
50+
- name: Deploy to GitHub Pages
51+
uses: peaceiris/actions-gh-pages@v3
52+
with:
53+
github_token: ${{ secrets.GITHUB_TOKEN }}
54+
publish_dir: ./dist
55+
cname: # Add your custom domain here if you have one

‎.gitignore‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Dependencies
2+
node_modules/
3+
4+
# Build output
5+
dist/
6+
7+
# Environment files
8+
.env
9+
.env.local
10+
.env.*.local
11+
12+
# IDE
13+
.vscode/
14+
.idea/
15+
*.swp
16+
*.swo
17+
18+
# OS files
19+
.DS_Store
20+
Thumbs.db
21+
22+
# Logs
23+
*.log
24+
npm-debug.log*
25+
26+
# Generated data (keep sample, ignore live data)
27+
src/data/dashboard-data.json
28+
public/data/dashboard-data.json

‎README.md‎

Lines changed: 255 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,255 @@
1+
# DocsDash
2+
3+
A modern, extensible dashboard for technical documentation metrics. Pulls data from Google Analytics and Jira, visualizes key metrics, and provides AI-powered insights.
4+
5+
![Dashboard Preview](https://via.placeholder.com/800x400?text=DocsDash+Preview)
6+
7+
## Features
8+
9+
- **Google Analytics Integration**: Page views, top pages, search terms, traffic sources
10+
- **Jira Integration**: Open issues, priority breakdown, sprint velocity
11+
- **AI Assistant**: ChatGPT-powered insights and recommendations
12+
- **Content Gap Detection**: Identifies searches with no results
13+
- **Fully Static Deployment**: Runs on GitHub Pages with zero server costs
14+
- **Extensible**: Easy to add new charts and data sources
15+
16+
## Quick Start
17+
18+
### Local Development
19+
20+
```bash
21+
# Install dependencies
22+
npm install
23+
24+
# Start dev server
25+
npm run dev
26+
```
27+
28+
The dashboard will run at `http://localhost:5173` with sample data.
29+
30+
### Deploy to GitHub Pages
31+
32+
1. **Create a new GitHub repository**
33+
34+
2. **Push this code to the repository**
35+
```bash
36+
git init
37+
git add .
38+
git commit -m "Initial commit"
39+
git branch -M main
40+
git remote add origin https://github.com/YOUR_USERNAME/YOUR_REPO.git
41+
git push -u origin main
42+
```
43+
44+
3. **Configure GitHub Pages**
45+
- Go to Settings → Pages
46+
- Source: "GitHub Actions"
47+
48+
4. **Add secrets** (Settings → Secrets → Actions):
49+
- See [Configuration](#configuration) section below
50+
51+
5. **Update `vite.config.js`**
52+
- Change `base` to match your repository name:
53+
```js
54+
base: process.env.NODE_ENV === 'production' ? '/YOUR_REPO_NAME/' : '/',
55+
```
56+
57+
6. **Trigger the workflow**
58+
- Push a commit or manually trigger via Actions tab
59+
60+
## Configuration
61+
62+
### Required GitHub Secrets
63+
64+
#### Google Analytics
65+
66+
| Secret | Description |
67+
|--------|-------------|
68+
| `GA_PROPERTY_ID` | Your GA4 property ID (e.g., `123456789`) |
69+
| `GOOGLE_SERVICE_ACCOUNT_KEY` | Service account JSON key (entire JSON content) |
70+
71+
**Setting up Google Analytics:**
72+
73+
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
74+
2. Create a new project (or use existing)
75+
3. Enable the "Google Analytics Data API"
76+
4. Create a Service Account:
77+
- Go to IAM & Admin → Service Accounts
78+
- Create a new service account
79+
- Download the JSON key
80+
5. Add the service account email to your GA4 property:
81+
- GA4 Admin → Property Access Management
82+
- Add the service account email with "Viewer" role
83+
6. Add the entire JSON key content as `GOOGLE_SERVICE_ACCOUNT_KEY` secret
84+
7. Add your property ID as `GA_PROPERTY_ID` secret
85+
86+
#### Jira
87+
88+
| Secret | Description |
89+
|--------|-------------|
90+
| `JIRA_BASE_URL` | Your Jira instance (e.g., `https://your-org.atlassian.net`) |
91+
| `JIRA_EMAIL` | Your Atlassian account email |
92+
| `JIRA_API_TOKEN` | Jira API token |
93+
| `JIRA_PROJECT_KEY` | Project key (e.g., `DOC`) |
94+
95+
**Setting up Jira:**
96+
97+
1. Go to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
98+
2. Create a new API token
99+
3. Add secrets to GitHub
100+
101+
### Custom JQL Queries
102+
103+
Edit `scripts/fetch-data.js` to customize the JQL queries. The default queries are:
104+
105+
```javascript
106+
// Open issues
107+
`project=${projectKey} AND status != Done ORDER BY priority DESC`
108+
109+
// Recent issues
110+
`project=${projectKey} ORDER BY created DESC`
111+
112+
// Created this week
113+
`project=${projectKey} AND created >= -7d`
114+
```
115+
116+
## Adding New Charts
117+
118+
The dashboard is built with modular, reusable components. Here's how to add a new chart:
119+
120+
### 1. Create the Chart Component
121+
122+
```jsx
123+
// src/components/charts/MyNewChart.jsx
124+
import React from 'react'
125+
import { BarChart, Bar, XAxis, YAxis, ResponsiveContainer } from 'recharts'
126+
import { ChartCard } from '../ChartCard'
127+
128+
export function MyNewChart({ data }) {
129+
return (
130+
<ChartCard title="My New Chart" subtitle="Description here">
131+
<div className="h-64">
132+
<ResponsiveContainer width="100%" height="100%">
133+
<BarChart data={data}>
134+
<XAxis dataKey="name" />
135+
<YAxis />
136+
<Bar dataKey="value" fill="#3b82f6" />
137+
</BarChart>
138+
</ResponsiveContainer>
139+
</div>
140+
</ChartCard>
141+
)
142+
}
143+
```
144+
145+
### 2. Add to App.jsx
146+
147+
```jsx
148+
import { MyNewChart } from './components/charts/MyNewChart'
149+
150+
// In the render:
151+
<MyNewChart data={data.myNewData} />
152+
```
153+
154+
### 3. Update Data Structure
155+
156+
Add the new data to `src/data/sample-data.json` and update `scripts/fetch-data.js` to fetch the real data.
157+
158+
## Available Chart Components
159+
160+
| Component | Description |
161+
|-----------|-------------|
162+
| `MetricCard` | Single metric with trend indicator |
163+
| `ChartCard` | Wrapper with title/subtitle for any chart |
164+
| `PageViewsChart` | Area chart for time-series data |
165+
| `TopPagesTable` | Table with progress bars |
166+
| `SearchTermsChart` | Horizontal bar chart with color coding |
167+
| `JiraPriorityChart` | Donut chart |
168+
| `VelocityChart` | Grouped bar chart |
169+
| `RecentIssuesTable` | Table with status badges |
170+
| `TrafficSourcesChart` | Pie chart |
171+
172+
## AI Assistant
173+
174+
The AI assistant uses OpenAI's API to provide insights. Users provide their own API key, which is stored in their browser's localStorage (never sent to your servers).
175+
176+
### Customizing the AI Context
177+
178+
Edit the `buildContext()` function in `src/components/AIAssistant.jsx` to change what data is sent to the AI.
179+
180+
### Using a Different LLM
181+
182+
Replace the OpenAI API call with any other provider (Anthropic, Google, etc.) by modifying the `sendMessage()` function.
183+
184+
## Data Refresh Schedule
185+
186+
The GitHub Action runs every 6 hours by default. To change this, edit `.github/workflows/fetch-and-deploy.yml`:
187+
188+
```yaml
189+
schedule:
190+
- cron: '0 */6 * * *' # Every 6 hours
191+
# - cron: '0 0 * * *' # Daily at midnight
192+
# - cron: '0 * * * *' # Every hour
193+
```
194+
195+
## Project Structure
196+
197+
```
198+
docsdash/
199+
├── .github/
200+
│ └── workflows/
201+
│ └── fetch-and-deploy.yml # CI/CD pipeline
202+
├── public/
203+
│ └── favicon.svg
204+
├── scripts/
205+
│ └── fetch-data.js # Data fetching script
206+
├── src/
207+
│ ├── components/
208+
│ │ ├── charts/ # Chart components
209+
│ │ ├── AIAssistant.jsx # LLM integration
210+
│ │ ├── ChartCard.jsx # Chart wrapper
211+
│ │ └── MetricCard.jsx # Metric display
212+
│ ├── data/
213+
│ │ └── sample-data.json # Sample/fallback data
214+
│ ├── App.jsx # Main app
215+
│ ├── index.css # Tailwind imports
216+
│ └── main.jsx # Entry point
217+
├── index.html
218+
├── package.json
219+
├── tailwind.config.js
220+
└── vite.config.js
221+
```
222+
223+
## Tech Stack
224+
225+
- **React 18** - UI framework
226+
- **Vite** - Build tool
227+
- **Tailwind CSS** - Styling
228+
- **Recharts** - Charts
229+
- **Lucide React** - Icons
230+
- **GitHub Actions** - CI/CD and data fetching
231+
232+
## Troubleshooting
233+
234+
### Data not updating
235+
236+
1. Check GitHub Actions logs for errors
237+
2. Verify all secrets are correctly set
238+
3. Ensure GA service account has access to the property
239+
4. Check Jira API token hasn't expired
240+
241+
### Charts not rendering
242+
243+
1. Check browser console for errors
244+
2. Verify data structure matches expected format
245+
3. Ensure Recharts is properly imported
246+
247+
### AI Assistant not working
248+
249+
1. Verify OpenAI API key is correct
250+
2. Check browser console for CORS or API errors
251+
3. Ensure you have API credits remaining
252+
253+
## License
254+
255+
MIT

‎index.html‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8" />
5+
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
6+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
7+
<title>DocsDash - Documentation Metrics Dashboard</title>
8+
<meta name="description" content="Analytics dashboard for technical documentation with GA, Jira, and AI-powered insights" />
9+
</head>
10+
<body>
11+
<div id="root"></div>
12+
<script type="module" src="/src/main.jsx"></script>
13+
</body>
14+
</html>

0 commit comments

Comments
 (0)