# abdullah-cse/contribution_heatmap architecture

> Architecture diagram of the GitHub repository abdullah-cse/contribution_heatmap, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abdullah-cse/contribution_heatmap
- Repository: https://github.com/abdullah-cse/contribution_heatmap

## Overview

1. This repository is a Flutter package, not a standalone app. The primary deliverable is the `contribution_heatmap` library under `lib/`, which is published to pub.dev and exercised by a multi-platform example app plus a separate web playground.

2. The public API is thin and centered around `lib/contribution_heatmap.dart` and `lib/src/widgets/contribution_heatmap.dart`. This widget is the integration boundary for consumers: they pass contribution data, styling, date-range options, locale/weekday preferences, and an optional tap callback.

3. The core domain model is `ContributionEntry` in `lib/src/models/contribution_entry.dart`. It represents day-level contribution counts and is the input to the whole rendering pipeline. The package is designed around a date-to-count mapping rather than live state or network data.

4. Rendering is handled by a custom `RenderBox` in `lib/src/rendering/render_contribution_heatmap.dart`. This is the main architectural choice in the repo: instead of composing many Flutter widgets, the heatmap is painted directly for performance, with custom layout, drawing, and hit testing.

5. Data flow is: input entries are normalized and indexed into fast lookup structures, the date span is derived from `minDate`/`maxDate` or the data itself, and the renderer converts that timeline into a grid of cells. Each cell is painted according to contribution intensity, with optional month separators, weekday labels, and date numbers inside cells.

6. Utility code is split by concern. `heatmap_utils.dart` appears to handle date/grid calculations and month-splitting logic, `heatmap_color_utils.dart` maps counts to `HeatmapColor` palettes, and `heatmap_localizations.dart` handles locale-aware labels and translations. These utilities are the main computation layer beneath the render object.

7. The package exposes a small set of enums in `lib/src/enum/`, mainly `HeatmapColor` and `WeekdayLabel`. These control visual palette selection and weekday-label behavior, including the migration path from the older `showWeekdayLabels` boolean to the newer enum-based API.

8. Interaction is built into the rendering layer rather than added externally. Tap handling flows from hit testing in the custom render object to the `onCellTap(DateTime, int)` callback, so consumers can respond to user interaction without needing to wire up separate gesture widgets around the heatmap.

9. The repository includes a full `example/` Flutter application scaffolded for Android, iOS, web, macOS, Linux, and Windows. That example is the integration reference for package users and demonstrates the widget in a real app shell across platforms.

10. There is also a separate `contribution_heatmap_playground/` app, which is a web-focused interactive playground. Its role is product/demo infrastructure: users can experiment with settings, preview generated code, and visually inspect the widget without writing their own app first.

11. Testing is organized around the same subsystem boundaries as the library: model tests, utility tests, and widget/rendering tests under `test/`. That suggests the package’s risk areas are date math, color mapping, localization, and custom rendering behavior rather than business logic or backend integration.

12. CI/CD is lightweight and package-oriented. GitHub Actions workflows build and publish the package, while coverage is reported through Codecov. The repo’s lifecycle is therefore “library development → test/build → publish,” with no server-side runtime or persistent storage layer.

Main entry points: [`lib/src/rendering/render_contribution_heatmap.dart`](https://github.com/abdullah-cse/contribution_heatmap/blob/main/lib/src/rendering/render_contribution_heatmap.dart) (Render heatmap), [`lib/src/widgets/contribution_heatmap.dart`](https://github.com/abdullah-cse/contribution_heatmap/blob/main/lib/src/widgets/contribution_heatmap.dart) (Heatmap widget), [`test/contribution_heatmap_test.dart`](https://github.com/abdullah-cse/contribution_heatmap/blob/main/test/contribution_heatmap_test.dart) (Library tests), [`example/lib/main.dart`](https://github.com/abdullah-cse/contribution_heatmap/blob/main/example/lib/main.dart) (Example app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_lib["Library"]
  node_node_pub_api["Public API<br/>library entrypoint"]
  node_node_widget["Heatmap widget<br/>widget boundary"]
  node_node_model["Contribution entry<br/>data model"]
  node_node_render["Render heatmap<br/>custom renderbox"]
  node_node_utils["Heatmap utils<br/>date/grid logic<br/>[heatmap_utils.dart]"]
  node_node_colors["Color utils<br/>palette mapping"]
  node_node_locale["Localizations<br/>locale labels"]
  node_node_heatmap_color{{"Heatmap color<br/>enum<br/>[heatmap_color.dart]"}}
  node_node_weekday_label{{"Weekday label<br/>enum<br/>[weekday_label.dart]"}}
end

subgraph group_group_example["Example app"]
  node_node_example_main["Example app<br/>flutter app<br/>[main.dart]"]
  node_node_example_android["Android host<br/>platform host<br/>[MainActivity.kt]"]
  node_node_example_ios["iOS host<br/>platform host<br/>[AppDelegate.swift]"]
  node_node_example_desktop["Desktop hosts<br/>platform hosts<br/>[main.cc]"]
end

subgraph group_group_playground["Playground"]
  node_node_play_main["Playground app<br/>web app<br/>[main.dart]"]
  node_node_play_screen["Playground screen<br/>ui screen"]
  node_node_play_preview["Code preview<br/>demo utility<br/>[code_preview.dart]"]
  node_node_play_data["Random entries<br/>demo data"]
end

subgraph group_group_quality["Quality and release"]
  node_node_tests["Library tests<br/>test suite"]
  node_node_ci_build["Build workflow<br/>ci workflow<br/>[build.yml]"]
  node_node_ci_publish["Publish workflow<br/>release workflow<br/>[publish.yml]"]
end

node_node_pub_api -->|"exports"| node_node_widget
node_node_widget -->|"consumes"| node_node_model
node_node_widget -->|"derives layout"| node_node_utils
node_node_widget -->|"selects palette"| node_node_colors
node_node_widget -->|"localizes"| node_node_locale
node_node_widget -->|"builds"| node_node_render
node_node_render -->|"lays out"| node_node_utils
node_node_render -->|"paints"| node_node_colors
node_node_render -->|"labels"| node_node_locale
node_node_render -->|"indexes"| node_node_model
node_node_render -->|"configures"| node_node_heatmap_color
node_node_render -->|"configures"| node_node_weekday_label
node_node_render -->|"callbacks"| node_node_widget
node_node_example_main -->|"demonstrates"| node_node_widget
node_node_example_main -.->|"runs on"| node_node_example_android
node_node_example_main -.->|"runs on"| node_node_example_ios
node_node_example_main -.->|"runs on"| node_node_example_desktop
node_node_play_main -->|"hosts"| node_node_play_screen
node_node_play_screen -->|"embeds"| node_node_widget
node_node_play_screen -->|"shows code"| node_node_play_preview
node_node_play_screen -->|"generates data"| node_node_play_data
node_node_tests -->|"covers"| node_node_model
node_node_tests -->|"covers"| node_node_utils
node_node_tests -->|"covers"| node_node_colors
node_node_tests -->|"covers"| node_node_locale
node_node_tests -->|"covers"| node_node_render
node_node_ci_build -->|"runs"| node_node_tests
node_node_ci_publish -->|"releases"| node_node_pub_api

click node_node_pub_api "https://github.com/abdullah-cse/contribution_heatmap/blob/main/lib/contribution_heatmap.dart"
click node_node_widget "https://github.com/abdullah-cse/contribution_heatmap/blob/main/lib/src/widgets/contribution_heatmap.dart"
click node_node_model "https://github.com/abdullah-cse/contribution_heatmap/blob/main/lib/src/models/contribution_entry.dart"
click node_node_render "https://github.com/abdullah-cse/contribution_heatmap/blob/main/lib/src/rendering/render_contribution_heatmap.dart"
click node_node_utils "https://github.com/abdullah-cse/contribution_heatmap/blob/main/lib/src/utils/heatmap_utils.dart"
click node_node_colors "https://github.com/abdullah-cse/contribution_heatmap/blob/main/lib/src/utils/heatmap_color_utils.dart"
click node_node_locale "https://github.com/abdullah-cse/contribution_heatmap/blob/main/lib/src/utils/heatmap_localizations.dart"
click node_node_heatmap_color "https://github.com/abdullah-cse/contribution_heatmap/blob/main/lib/src/enum/heatmap_color.dart"
click node_node_weekday_label "https://github.com/abdullah-cse/contribution_heatmap/blob/main/lib/src/enum/weekday_label.dart"
click node_node_example_main "https://github.com/abdullah-cse/contribution_heatmap/blob/main/example/lib/main.dart"
click node_node_example_android "https://github.com/abdullah-cse/contribution_heatmap/blob/main/example/android/app/src/main/kotlin/com/example/example/MainActivity.kt"
click node_node_example_ios "https://github.com/abdullah-cse/contribution_heatmap/blob/main/example/ios/Runner/AppDelegate.swift"
click node_node_example_desktop "https://github.com/abdullah-cse/contribution_heatmap/blob/main/example/linux/runner/main.cc"
click node_node_play_main "https://github.com/abdullah-cse/contribution_heatmap/blob/main/contribution_heatmap_playground/lib/main.dart"
click node_node_play_screen "https://github.com/abdullah-cse/contribution_heatmap/blob/main/contribution_heatmap_playground/lib/playground_screen.dart"
click node_node_play_preview "https://github.com/abdullah-cse/contribution_heatmap/blob/main/contribution_heatmap_playground/lib/code_preview.dart"
click node_node_play_data "https://github.com/abdullah-cse/contribution_heatmap/blob/main/contribution_heatmap_playground/lib/random_entries.dart"
click node_node_tests "https://github.com/abdullah-cse/contribution_heatmap/blob/main/test/contribution_heatmap_test.dart"
click node_node_ci_build "https://github.com/abdullah-cse/contribution_heatmap/blob/main/.github/workflows/build.yml"
click node_node_ci_publish "https://github.com/abdullah-cse/contribution_heatmap/blob/main/.github/workflows/publish.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_pub_api,node_node_widget,node_node_model,node_node_render,node_node_utils,node_node_colors,node_node_locale,node_node_heatmap_color,node_node_weekday_label toneBlue
class node_node_example_main,node_node_example_android,node_node_example_ios,node_node_example_desktop toneAmber
class node_node_play_main,node_node_play_screen,node_node_play_preview,node_node_play_data toneMint
class node_node_tests,node_node_ci_build,node_node_ci_publish toneRose
```

## Components

### Library

Published Flutter package and its core rendering pipeline

- [Public API](https://github.com/abdullah-cse/contribution_heatmap/blob/main/lib/contribution_heatmap.dart): library entrypoint · Package export surface for consumers · `lib/contribution_heatmap.dart`
- [Heatmap widget](https://github.com/abdullah-cse/contribution_heatmap/blob/main/lib/src/widgets/contribution_heatmap.dart): widget boundary · Consumer-facing widget API and configuration boundary · `lib/src/widgets/contribution_heatmap.dart`
- [Contribution entry](https://github.com/abdullah-cse/contribution_heatmap/blob/main/lib/src/models/contribution_entry.dart): data model · Day-level contribution count input model · `lib/src/models/contribution_entry.dart`
- [Render heatmap](https://github.com/abdullah-cse/contribution_heatmap/blob/main/lib/src/rendering/render_contribution_heatmap.dart): custom renderbox · Custom layout, painting, and hit testing for the heatmap · `lib/src/rendering/render_contribution_heatmap.dart`
- [Heatmap utils](https://github.com/abdullah-cse/contribution_heatmap/blob/main/lib/src/utils/heatmap_utils.dart): date/grid logic · Timeline, grid, and month-splitting calculations · `lib/src/utils/heatmap_utils.dart`
- [Color utils](https://github.com/abdullah-cse/contribution_heatmap/blob/main/lib/src/utils/heatmap_color_utils.dart): palette mapping · Maps contribution counts to heatmap colors · `lib/src/utils/heatmap_color_utils.dart`
- [Localizations](https://github.com/abdullah-cse/contribution_heatmap/blob/main/lib/src/utils/heatmap_localizations.dart): locale labels · Locale-aware labels and weekday text · `lib/src/utils/heatmap_localizations.dart`
- [Heatmap color](https://github.com/abdullah-cse/contribution_heatmap/blob/main/lib/src/enum/heatmap_color.dart): enum · Palette selection enum · `lib/src/enum/heatmap_color.dart`
- [Weekday label](https://github.com/abdullah-cse/contribution_heatmap/blob/main/lib/src/enum/weekday_label.dart): enum · Weekday-label behavior enum · `lib/src/enum/weekday_label.dart`

### Example app

Multi-platform Flutter example used to demonstrate the package

- [Example app](https://github.com/abdullah-cse/contribution_heatmap/blob/main/example/lib/main.dart): flutter app · Multi-platform package demonstration shell · `example/lib/main.dart`
- [Android host](https://github.com/abdullah-cse/contribution_heatmap/blob/main/example/android/app/src/main/kotlin/com/example/example/MainActivity.kt): platform host · Android runner for the example app · `example/android/app/src/main/kotlin/com/example/example/MainActivity.kt`
- [iOS host](https://github.com/abdullah-cse/contribution_heatmap/blob/main/example/ios/Runner/AppDelegate.swift): platform host · iOS runner for the example app · `example/ios/Runner/AppDelegate.swift`
- [Desktop hosts](https://github.com/abdullah-cse/contribution_heatmap/blob/main/example/linux/runner/main.cc): platform hosts · Linux, macOS, and Windows runner shells for the example app · `example/linux/runner/main.cc`

### Playground

Web-focused interactive demo and code preview app

- [Playground app](https://github.com/abdullah-cse/contribution_heatmap/blob/main/contribution_heatmap_playground/lib/main.dart): web app · Interactive web-focused playground shell · `contribution_heatmap_playground/lib/main.dart`
- [Playground screen](https://github.com/abdullah-cse/contribution_heatmap/blob/main/contribution_heatmap_playground/lib/playground_screen.dart): ui screen · Interactive settings and preview screen · `contribution_heatmap_playground/lib/playground_screen.dart`
- [Code preview](https://github.com/abdullah-cse/contribution_heatmap/blob/main/contribution_heatmap_playground/lib/code_preview.dart): demo utility · Generates or displays sample code for the playground · `contribution_heatmap_playground/lib/code_preview.dart`
- [Random entries](https://github.com/abdullah-cse/contribution_heatmap/blob/main/contribution_heatmap_playground/lib/random_entries.dart): demo data · Synthetic contribution data for playground exploration · `contribution_heatmap_playground/lib/random_entries.dart`

### Quality and release

Tests, CI, and publication workflow

- [Library tests](https://github.com/abdullah-cse/contribution_heatmap/blob/main/test/contribution_heatmap_test.dart): test suite · Model, utility, widget, and render coverage · `test/contribution_heatmap_test.dart`
- [Build workflow](https://github.com/abdullah-cse/contribution_heatmap/blob/main/.github/workflows/build.yml): ci workflow · Continuous integration build and validation · `.github/workflows/build.yml`
- [Publish workflow](https://github.com/abdullah-cse/contribution_heatmap/blob/main/.github/workflows/publish.yml): release workflow · Package publication workflow · `.github/workflows/publish.yml`

## Connections

- Public API → Heatmap widget: exports · Public library surface exposes the widget API
- Heatmap widget → Contribution entry: consumes · Widget accepts contribution data as input
- Heatmap widget → Heatmap utils: derives layout · Widget delegates date-span and grid calculations
- Heatmap widget → Color utils: selects palette · Widget configuration flows into color mapping
- Heatmap widget → Localizations: localizes · Widget uses locale and weekday labeling helpers
- Heatmap widget → Render heatmap: builds · Widget instantiates the custom render object
- Render heatmap → Heatmap utils: lays out · Render object uses timeline and cell-grid calculations
- Render heatmap → Color utils: paints · Render object maps counts to painted cells
- Render heatmap → Localizations: labels · Render object draws locale-aware labels inside and around cells
- Render heatmap → Contribution entry: indexes · Render object reads normalized contribution entries for hit testing and painting
- Render heatmap → Heatmap color: configures · Palette selection is driven by the enum API
- Render heatmap → Weekday label: configures · Weekday label behavior is driven by the enum API
- Render heatmap → Heatmap widget: callbacks · Hit testing feeds tap events back through the widget boundary
- Example app → Heatmap widget: demonstrates · Example app uses the package widget in a real app shell
- Example app → Android host: runs on · Android platform host for the example
- Example app → iOS host: runs on · iOS platform host for the example
- Example app → Desktop hosts: runs on · Desktop platform hosts for the example
- Playground app → Playground screen: hosts · Playground entrypoint opens the interactive screen
- Playground screen → Heatmap widget: embeds · Playground previews the heatmap widget interactively
- Playground screen → Code preview: shows code · Screen presents generated or editable code snippets
- Playground screen → Random entries: generates data · Screen uses synthetic entries for experimentation
- Library tests → Contribution entry: covers · Tests verify model behavior
- Library tests → Heatmap utils: covers · Tests verify date and grid utilities
- Library tests → Color utils: covers · Tests verify color mapping behavior
- Library tests → Localizations: covers · Tests verify localization behavior
- Library tests → Render heatmap: covers · Tests exercise custom rendering behavior
- Build workflow → Library tests: runs · CI build validates the package through tests
- Publish workflow → Public API: releases · Publish workflow publishes the library package