# Gemini CLI Project Context

## Project Overview

This project is the **Claude Conversation Analyzer**, a tool designed to aggregate, visualize, search, and estimate costs across Claude Code conversations. It processes conversation data, calculates model-specific pricing, evaluates conversation quality, and provides an interactive dashboard to explore the results.

The repository is structured into two main components:
1.  **Backend (Python):** Reads raw conversation data from a SQLite database generated by the `claude-code-log` tool, computes costs and quality scores, and augments the database with these metrics.
2.  **Frontend (Next.js):** An interactive web dashboard that reads directly from the augmented SQLite database via API routes to display metrics, token progression charts, and message transcripts.

## Technology Stack

### Backend
*   **Language:** Python 3.13+
*   **Package Manager:** `uv`
*   **Build System:** `hatchling`
*   **Linting & Formatting:** `ruff`
*   **Type Checking:** `mypy` (strict mode)

### Frontend
*   **Framework:** Next.js 16 (App Router), React 19
*   **Language:** TypeScript (strict mode)
*   **Package Manager:** `pnpm`
*   **Styling:** Tailwind CSS v4 (with CSS variables for dark/light themes)
*   **Linting & Formatting:** Biome 2.1.2
*   **Database Access:** `better-sqlite3`
*   **Charting:** `recharts` (dynamically imported to avoid SSR issues)

## Building and Running

### Full Pipeline (Automated)

The easiest way to run the entire data generation and analysis pipeline is from the `backend` directory:

```bash
cd backend
make all
```
*Note: On the first run, `make all` will prompt you to configure a local clone of the `claude-code-log` repository.*

### Frontend Development Server

To view the interactive dashboard:

```bash
cd frontend
pnpm install
pnpm dev
```
The dashboard will be available at [http://localhost:3000](http://localhost:3000).

## Development Commands & Conventions

**IMPORTANT:** When proposing commands to the user, provide the exact commands for them to run, but do not execute `make` commands that run the full data pipeline automatically unless requested.

### Backend Commands
All backend commands should be run from the `backend/` directory:

*   **Setup:** `make install-dev` (installs dependencies using `uv`)
*   **Formatting:** `make fmt` (uses `ruff`)
*   **Linting:** `make lint` or `make lint-fix` (uses `ruff`)
*   **Type Checking:** `make type-check` (uses `mypy`)
*   **All Checks:** `make check` (runs lint and type-check)

**Backend Conventions:**
*   Use single quotes (`'`) for strings.
*   Maximum line length is 200 characters.
*   Strict typing is required (`mypy` strict mode).
*   Always run formatting before committing changes.

### Frontend Commands
All frontend commands should be run from the `frontend/` directory:

*   **Install Dependencies:** `pnpm install`
*   **Development Server:** `pnpm dev`
*   **Production Build:** `pnpm build`
*   **Linting:** `pnpm lint` or `pnpm lint:fix` (uses Biome)
*   **Formatting:** `pnpm format` (uses Biome)

**Frontend Conventions:**
*   Use 4-space indentation and 80-character line width (enforced by Biome).
*   Global state (data, search, sort, theme) is managed via a single `AppContext`.
*   Path aliases (`@/*` mapping to `./src/*`) are configured.
*   Ensure Recharts components are dynamically imported to prevent SSR hydration mismatches (see `TokenChart.tsx` for reference).