# puravparab/claude-stats architecture

> Architecture diagram of the GitHub repository puravparab/claude-stats, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/puravparab/claude-stats
- Repository: https://github.com/puravparab/claude-stats

## Overview

##### Project Type and Purpose
- The project is a full-stack web application.
- The README focuses on importing conversation data and running the app locally, emphasizing data processing and visualization.

##### File Structure
- The repository has a top-level Next.js application inside the ‘claude-stats’ directory.
- The “app/” directory contains the Next.js pages and layout files (layout.tsx, page.tsx), as well as the API endpoint in “app/api/conversations/route.ts”.
- The “components” directory (with subdirectories such as “heatmap” and “status”) holds the React components used to render heatmaps and status messages.
- The “lib” directory includes helper scripts for data manipulation (e.g., dates, prepare_data, process_json, tokenizer).
- Configuration files and styling (globals.css, Tailwind config, Next.js config) indicate that this is a modern React/Next.js project.
- The “data” directory (outside of “claude-stats”) is explicitly meant for storing the exported ‘conversations.json’ file.
- Additionally, the “scripts” directory contains Python scripts (e.g., process_json.py) that might be used for preprocessing or post-processing data, indicating external data processing support.

##### README for Additional Insights
- The README clearly describes the setup process, from exporting data from Claude to running the Next.js app with npm commands.
- The instructions suggest that users interact with a client-side interface (rendering the heatmaps) while backend API routes pull or process data.

a. Main Components:
- Client/Browser: The React/Next.js frontend that renders the UI (pages, layout, heatmap components, loading/error status).
- Web Application Server: The Next.js application serving both the frontend and API endpoints:
- API Server: The Next.js API route (at app/api/conversations/route.ts) that handles requests, possibly reading or processing conversation data.
- Shared Libraries: The “lib” directory components that provide data transformation and parsing (process_json, tokenizer, dates, etc.).
- Data Store/Source: The ‘data/conversations.json’ file that contains the raw conversation data.
- Auxiliary Data Processing: Python scripts (in the “scripts” directory) which can be used to preprocess or further analyze JSON data.

b. Relationships and Interactions:
- The Browser sends requests to the API endpoint, which then processes or fetches conversation data.
- The API layer utilizes functions from the “lib” directory to transform and prepare data.
- The processed data is returned to the frontend, where various React components (e.g., heatmap container, heatmap, tooltip) render visualizations.
- Optionally, the Python scripts might be used as a standalone process for additional data preprocessing outside of the main application flow.

c. Important Architectural Patterns:
- Separation of concerns: There is a clear distinction between UI components (in “components”), API handling (in the “app/api”), and data processing utilities (in “lib” and “scripts”).
- Modular design: Each component (such as heatmap presentation and status feedback) is encapsulated in separate files to enhance reusability and maintenance.
- Client-server communication: The use of an API route underlines a REST-style or serverless architecture provided by Next.js.

d. Relevant Technologies/Frameworks:
- Next.js for the overall architecture and routing.
- React for the component-based UI.
- Tailwind CSS for styling.
- Node.js environment (implied by package.json, npm scripts).
- Python for supplementary data processing (in “scripts”).
- TypeScript for type-safety (presence of .ts and .tsx files).

- Clear labels for each component:
- Client (Browser / React Application)
- Next.js Application (with subcomponents: page layout, API routes, etc.)
- Data Processing (lib functions, Python script processor)
- Data Source (conversations.json)
- User interactions on the browser trigger API calls.
- API calls invoke library functions and optionally the Python script, then return data.
- Processed data flows from the backend to the frontend for rendering.
- Web components (e.g., rectangles for UI components)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client"
        A1["UI: Pages & Layout"]:::frontend
        A2["UI Components: React"]:::frontend
    end

    subgraph "Next.js Application"
        B["API Server"]:::api
    end

    subgraph "Shared Data Processing"
        C["Lib Functions"]:::lib
    end

    subgraph "Data Store"
        D["Conversations JSON"]:::data
    end

    subgraph "Auxiliary Data Processing"
        E["Python Script"]:::script
    end

    A1 -->|"APICall"| B
    A2 -->|"APICall"| B
    B -->|"Calls_Lib"| C
    C -->|"Fetch_Data"| D
    B -->|"Return_Data"| A1
    B -->|"Return_Data"| A2
    B ---|"optional"| E
    E ---|"Preprocess"| C

    click A1 "https://github.com/puravparab/claude-stats/tree/main/claude-stats/app"
    click A2 "https://github.com/puravparab/claude-stats/tree/main/claude-stats/components"
    click B "https://github.com/puravparab/claude-stats/blob/main/claude-stats/app/api/conversations/route.ts"
    click C "https://github.com/puravparab/claude-stats/tree/main/claude-stats/lib"
    click D "https://github.com/puravparab/claude-stats/tree/main/data"
    click E "https://github.com/puravparab/claude-stats/blob/main/scripts/process_json.py"

    classDef frontend fill:#a3d5ff,stroke:#1f78b4,stroke-width:2px;
    classDef api fill:#ffcc80,stroke:#e65100,stroke-width:2px;
    classDef lib fill:#c1e1c1,stroke:#388e3c,stroke-width:2px;
    classDef data fill:#fff59d,stroke:#fbc02d,stroke-width:2px;
    classDef script fill:#ffab91,stroke:#d84315,stroke-width:2px;
```
