Forgejo-Timetracking-Dashboard/README.md

# Time Tracking Dashboard

A real-time dashboard built with [Astro](https://astro.build) that visualizes time tracking data from a Bitfreedom code API. Displays time worked across issues, pull requests, and date ranges using interactive ApexCharts.

## Features

- **Summary stats**: Time worked today, this week, and this month
- **Weekly area chart**: Hours tracked over the last 14 days
- **Monthly area chart**: Hours tracked over the last 30 days
- **Issue breakdown**: Horizontal bar chart of time spent by issue
- **PR breakdown**: Horizontal bar chart of time spent by pull request
- **Distribution donut**: Ratio of time on issues vs. pull requests
- **Dark theme**: Purple-accented responsive UI

## Tech Stack

- [Astro](https://astro.build) — static site framework
- [ApexCharts](https://apexcharts.com) — interactive charts
- [Node.js](https://nodejs.org) ≥ 22.12.0
- [Bun](https://bun.sh) — package manager

## Getting Started

### Prerequisites

- Node.js ≥ 22.12.0
- Bun
- An `ACCESS_TOKEN` for the Bitfreedom API

### Install

```sh
bun install
```

### Environment

Copy the access token into the environment. Create a `.env` file at the project root:

```
PUBLIC_ACCESS_TOKEN=your_token_here
```

The token is injected at build time via Vite's `define` config in `astro.config.mjs`.

### Development

```sh
bun dev
```

Starts the local dev server at `localhost:4321`.

### Build

```sh
bun build
```

Produces a static site in `./dist/`.

### Preview

```sh
bun preview
```

Serves the built output locally for a pre-deployment check.

## Project Structure

```
├── astro.config.mjs      # Astro + Vite config (injects ACCESS_TOKEN)
├── package.json          # Dependencies: astro, apexcharts
├── tsconfig.json
├── .env                  # Environment variables (not committed)
├── public/               # Static assets
├── src/
│   ├── assets/           # SVG backgrounds, icons
│   ├── components/
│   │   └── Welcome.astro # Astro starter component (unused by dashboard)
│   ├── layouts/
│   │   └── Layout.astro  # Base layout template
│   └── pages/
│       └── index.astro   # Dashboard page (self-contained app)
└── dist/                 # Built output
```

## API

The dashboard fetches time tracking data from:

```
https://bitfreedom.net/code/api/v1/user/times?access_token=<token>&since=<ISO-date>
```

The `since` parameter defaults to the start of the current week (Monday). The API returns time entries with `created`, `time` (in seconds), and optional `issue` objects containing `id`, `number`, `title`, and `pull_request` flags.

## Deployment

Since `bun build` outputs a static site to `./dist/`, the dashboard can be deployed to any static hosting service (Netlify, Vercel, GitHub Pages, etc.). Make sure the `PUBLIC_ACCESS_TOKEN` environment variable is configured in your hosting platform.