# Gitlytics — Full Technical Context

> Complete technical documentation for Gitlytics, an open-source GitHub Traffic Analytics and Profile customization platform. This file is intended for LLM consumption.

## 1. System Overview

Gitlytics captures, deduplicates, and persists GitHub repository traffic data beyond the default 14-day window. It also features a dynamic widget engine to render real-time developer statistics, contribution streaks, and customized technology logos inside GitHub README profiles.

## 2. Core CLI & Python Library

The core library (`gitlytics`) can be installed from PyPI:
```bash
pip install gitlytics
pip install "gitlytics[dashboard]" # includes local web server
```

### CLI Subcommands

- `gitlytics fetch --repo-name owner/repo` : Fetch live 14-day views and clones. Supports `--return-format timeseries|summary`, `--save-file`, and `--metrics`.
- `gitlytics sync --repo-name owner/repo --data-dir ./data` : Query the latest traffic and merge it into monthly CSV files (`traffic_YYYY-MM.csv`) with automatic duplicate detection.
- `gitlytics stars owner/repo` : Sample a repository's lifetime star growth curve using a 10-point pagination algorithm.
- `gitlytics dashboard` : Launches the local FastAPI server hosting the React dashboard on port 8000.

### Python API Usage

```python
import gitlytics

# Fetch views and clones as pandas DataFrame
df = gitlytics.fetch_traffic(token="ghp_xxx", repo_name="owner/repo")

# Sync traffic to monthly CSV folder
gitlytics.sync(token="ghp_xxx", repo_name="owner/repo", data_dir="./data")

# Sample cumulative star timeline
history = gitlytics.fetch_star_history(owner="owner", repo="repo")
```

---

## 3. GitHub Action — Traffic Sync Automation

The composite GitHub Action `ameyac11/gitlytics-github-traffic-automation` schedules regular backups to defeat GitHub's 14-day data retention limit.

### Configuration (`.github/workflows/traffic.yml`)

```yaml
name: Gitlytics Traffic Sync
on:
  schedule:
    - cron: '0 17 */13 * *'  # Runs 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: ameyac11/gitlytics-github-traffic-automation@v1
        with:
          traffic_token: ${{ secrets.TRAFFIC_TOKEN }}
          data_dir: "data/"
```

*Required: Create a GitHub PAT with `Administration: Read-only` permissions and register it as `TRAFFIC_TOKEN`.*

---

## 4. Dynamic Widgets & Profile Customization

The platform provides several dynamic SVG generator endpoints for profile customizability:

### Developer Profile Cards
Renders beautiful summary stats, commit heatmaps, or contribution streaks.
- **Pattern**: `/api/cards/{card_type}/{username}.svg`
- **Supported card types**: `profile-details`, `contribution-streak`, `most-commit-language`, `productive-time`, `repos-per-language`, `stats`
- **Query parameters**:
  - `theme` : Visual style (e.g. `dracula`, `tokyonight`, `github-dark`)
  - `hide_border` : Hide border frame (`true`/`false`)
  - `border_radius` : Border corner radius in pixels
  - `locale` : Output language
  - `streak_mode` : Streak tracking style (`daily` | `weekly`)
  - `exclude_days` : Weekday indices (0-6) to exclude from streak tracking
  - `cache` : Bypass backend database cache if set to `false` (`&cache=false`)
  - **Custom Colors**: `bg`, `bg_gradient_start`, `bg_gradient_end`, `border`, `title`, `text`, `text_secondary`, `accent_secondary`, `highlight`, `chart`

### Repository Metric Charts
Visualizes clones, views, forks, and star history inside READMEs.
- **Pattern**: `/api/chart/{owner}/{repo}/{metric}.svg`
- **Supported metrics**: `views`, `clones`, `stars`, `forks`
- **Query parameters**: `color` (hex value), `style` (`line` | `area`), `fill` (fill opacity), `milestones` (labels)

### Technology Logos
Generates developer tech stack badges and colored pills.
- **Pattern**: `/api/logos/{slug}.svg`
- **Supported styles**:
  - `logo` : Flat colored SVG tech brand icon
  - `logo_text` : Filled capsule badge containing the icon and uppercase text (shields.io "for-the-badge" style), dynamically adjusting icon/text colors for contrast.

---

## 5. Official Resources

- Landing Page: https://gitlytics.dev
- Documentation: https://docs.gitlytics.dev
- Application: https://dashboard.gitlytics.dev
- Main Repo: https://github.com/ameyac11/gitlytics
- Action Repo: https://github.com/ameyac11/gitlytics-github-traffic-automation