# Gitlytics - Full Platform Documentation & Dashboard Guide

> Complete documentation for Gitlytics: persistent GitHub repository traffic analytics, developer profile customization cards, dynamic SVG badges, and interactive dashboards. Optimized for user reference and LLM AI consumption.

---

## 1. System Overview

GitHub's native Traffic API retains repository views, unique visitors, clones, cloners, traffic referrers, and popular paths for a rolling window of **14 days only**. Older traffic metrics are permanently lost.

**Gitlytics** solves this data retention problem by automatically capturing, deduplicating, and archiving traffic data into long-term CSV data stores. It also provides a suite of dynamic SVG widgets to showcase developer statistics, contribution streaks, repository metrics, and technology logos inside GitHub README profiles and portfolios.

---

## 2. Dashboard Access Modes & Features

The hosted application at `dashboard.gitlytics.dev` offers three access modes:

- **Cloud OAuth Mode** : Log in via GitHub OAuth to automatically sync and track public or private repositories.
- **Personal Access Token (PAT) Mode** : Supply a read-only Personal Access Token to monitor target repositories without full account linking.
- **CSV Backup & Offline Mode** : Upload existing Gitlytics CSV backup files or connect to local FastAPI instances for offline visualization.

### Dashboard Workspace Capabilities

- **Traffic Analytics** : Interactive area and bar charts tracking daily/weekly views, unique visitors, clones, and cloners.
- **Referrer Source Analysis** : Detailed breakdown of top sites directing developers to your repository.
- **Popular Content Paths** : Analytics on which directories, documentation pages, or files receive the most traffic.
- **Star Trajectory Timelines** : Lifetime cumulative stargazer growth curves.
- **PNG & PDF Export** : Export high-resolution report cards and dashboard summaries for portfolios, social media, and READMEs.

---

## 3. Core CLI & Python Package (`gitlytics`)

Install the official package from PyPI:

```bash
# Basic CLI and library
pip install gitlytics

# Include web dashboard support
pip install "gitlytics[dashboard]"
```

### CLI Commands

- `gitlytics fetch --repo-name owner/repo` : Fetch live 14-day traffic metrics (views, clones, referrers, paths).
- `gitlytics sync --repo-name owner/repo --data-dir ./data` : Fetch current traffic and merge it into monthly CSV files (`traffic_YYYY-MM.csv`) with automatic duplicate detection.
- `gitlytics stars owner/repo` : Retrieve cumulative star growth history over the repository's lifetime.
- `gitlytics dashboard` : Launch the local web dashboard for visual exploration of traffic metrics.

### Python Library Usage

```python
import gitlytics

# Fetch 14-day traffic data as a pandas DataFrame
df = gitlytics.fetch_traffic(token="YOUR_GITHUB_TOKEN", repo_name="owner/repo")

# Sync traffic metrics into long-term CSV archive
gitlytics.sync(token="YOUR_GITHUB_TOKEN", repo_name="owner/repo", data_dir="./data")

# Retrieve star growth timeline history
history = gitlytics.fetch_star_history(owner="owner", repo="repo")
```

---

## 4. GitHub Action - Traffic Sync Automation

Automate regular traffic backups using the official GitHub Action `ameyachopade/gitlytics-github-traffic-automation@v1`.

```yaml
name: Gitlytics Traffic Sync
on:
  schedule:
    - cron: '0 17 */13 * *'  # Runs automatically every 13 days
  workflow_dispatch:

jobs:
  backup:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4

      - name: Sync Traffic Data
        uses: ameyachopade/gitlytics-github-traffic-automation@v1
        with:
          traffic_token: ${{ secrets.TRAFFIC_TOKEN }}
          data_dir: "data/"
```

---

## 5. SVG README Badges & Developer Cards

Embed dynamic SVG widgets directly into your GitHub README or website:

### Developer Profile Cards
- **URL Pattern**: `https://api.gitlytics.dev/api/cards/{card_type}/{username}.svg`
- **Card Types**: `profile-details`, `contribution-streak`, `most-commit-language`, `productive-time`, `repos-per-language`, `stats`
- **Options**: `theme` (e.g. `dracula`, `tokyonight`, `solarized_dark`, `github-dark`), `hide_border`, `border_radius`, `streak_mode` (`daily`|`weekly`), `exclude_days`
- **Custom Colors**: `bg`, `border`, `title`, `text`, `text_secondary`, `accent_secondary`, `highlight`, `chart`

### Repository Metric Charts
- **URL Pattern**: `https://api.gitlytics.dev/api/chart/{owner}/{repo}/{metric}.svg`
- **Supported Metrics**: `views`, `clones`, `stars`, `forks`

### Technology Logos & Stack Capsules
- **URL Pattern**: `https://api.gitlytics.dev/api/logos/{slug}.svg`
- **Styles**: `logo` (flat icon), `logo_text` (filled capsule badge)

---

## 6. Official Resources

- Landing Page: https://gitlytics.dev
- Documentation: https://docs.gitlytics.dev
- Blog: https://blog.gitlytics.dev
- Dashboard: https://dashboard.gitlytics.dev
- Core Repository: https://github.com/ameyachopade/gitlytics
- GitHub Action: https://github.com/ameyachopade/gitlytics-github-traffic-automation