README - dev guide + Getting Started

Makefile

@@ -19,4 +19,7 @@ download:
 	node src/data/contributors.json.js > src/data/raw/contributions.json
 	node src/data/contributors.json.js > src/data/raw/contributions.json
 	node src/data/contributors.json.js > src/data/raw/contributions.json
-	node src/data/contributors.json.js > src/data/raw/contributions.json
+	node src/data/contributors.json.js > src/data/raw/contributions.json
+
+clean-cache:
+	rm -rf dist src/.observablehq

README.md

@@ -1,7 +1,80 @@
-# Dora The Explorer
+# Github Insights
 
-This is an [Observable Framework](https://observablehq.com/framework) app. To start the local preview server, run:
+This project aims to monitore the Github repository of your choice, 
+it looks for main activities, like Pull Requests, releases, commits and any kind of contribution.
+
+### Features
+- Time between 2 releases
+- Fixes vs PR rate
+- Mean time to Merge PR
+- PlusMinus lines of Code
+
+It find some inspiration in [DORA's key metrics](https://dora.dev/research/?view=detail) : 
+ - Lead time, 
+ - Change failure rate
+ - Deploy frequency
+ - Recovery time
+
+### Used at Decathlon Digital
+I use this project [@Decathlon](https://digital.decathlon.net/) to follow our distributed engineering organization. 
+We have internal shared repositories (OSS like)  and a lot of contributions to them each week. It helps me to **control the way** new things are added to the *Common Good*
+
+![dash](src/assets/example_dash.png)
+
+### dashboard 
+
+[Live demo]()
+
+## Getting Started
+### Run in Github action
+
+Just use the `.github/workflow.yml` in your project
+
+Provide the following environment variables : 
+
+    GITHUB_TOKEN=<GITHUB Personal Access Token>
+    GITHUB_ORG=<decathlon_a_fond_la_forme>
+    GITHUB_REPO=<my_dbt_repo>
+    GITHUB_PAGES=<url>
+
+
+Here is the doc for your Github's [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
+
+### Run in Local
+
+#### setup
+
+Tested requirements : NodeJS v22.8.0, Python 3.13.0
 
+    python -m venv venv
+    source venv/bin/activate
+    pip install dbt-duckdb==1.9.0
+    npm install
+
+#### Execute
+
+
+1. create your `.env` (an [example](.env.example) is provided)
+
+
+2. Run Extraction and prepare data with dbt 
+
+The extraction part is managed by Javascript script in `src/data/*.json.js`
+```
+make download
+make transform
+```
+
+3. run Webserver
+
+```
+make dev
+```
+
+## Development guide
+### Viz
+
+This is an [Observable Framework](https://observablehq.com/framework) app. To start the local preview server, run:
 ```
 npm run dev
 ```
@@ -10,22 +83,28 @@ Then visit <http://localhost:3000> to preview your app.
 
 For more, see <https://observablehq.com/framework/getting-started>.
 
-## Project structure
-
-A typical Framework project looks like this:
+The project looks like this:
 
 ```ini
 .
+├─ models
+│  ├─ mart
+│  │  └─ daily_activities.sql  # The main model : it records all counts and measures from pr contributions
+│  ├─ staging
+│  │  └─ stg_*.sql             # select * from read_json(downloaded_file_path)
 ├─ src
 │  ├─ components
-│  │  └─ timeline.js           # an importable module
+│  │  └─ dailyPlot.js          # an importable module
+│  │  └─ sparkbar.js           # an importable module
+│  │  └─ linkable.js           # an importable module
 │  ├─ data
-│  │  ├─ launches.csv.js       # a data loader
-│  │  └─ events.json           # a static data file
-│  ├─ example-dashboard.md     # a page
-│  ├─ example-report.md        # another page
+│  │  ├─ pull_requests.json.js # a data loader for pull requests
+│  │  ├─ releases.json.js      # a data loader for github releases
+│  │  ├─ contributors.json.js  # a data loader for github releases
 │  └─ index.md                 # the home page
 ├─ .gitignore
+├─ profiles.yml                # configure duckdb to read JSON from data loaders, and then write parquet files
+├─ dbt_project.yml                # configure duckdb to read JSON from data loaders, and then write parquet files
 ├─ observablehq.config.js      # the app config file
 ├─ package.json
 └─ README.md
@@ -41,7 +120,7 @@ A typical Framework project looks like this:
 
 **`observablehq.config.js`** - This is the [app configuration](https://observablehq.com/framework/config) file, such as the pages and sections in the sidebar navigation, and the app’s title.
 
-## Command reference
+### Command reference
 
 | Command           | Description                                              |
 | ----------------- | -------------------------------------------------------- |