Project Docs

Appearance

Features ​

Overview ​

This project keeps Notion as the canonical source of truth, syncs GitHub activity into Notion, and exports a snapshot for two visual surfaces (Observable and hosted React app). The core flow is:

  • GitHub -> Notion (Projects + Activity)
  • Manual logging -> Notion (Conversations + Tasks)
  • Notion -> snapshot.json (Observable FileAttachment + web app data source)

Data model ​

The Notion bootstrap creates four databases under the "Project Dashboard" page:

  • Projects: one row per repo (name, repo URL, stars, forks, last push, etc.)
  • GitHub Activity: issues, PRs, commits, releases, workflow runs linked to a Project
  • Conversations: manual summaries linked to a Project
  • Tasks: optional tasks linked to a Conversation and Project

GitHub sync behavior ​

Sync is scoped by an allowlist in config/repos.yaml and a rolling time window from SYNC_WINDOW_DAYS. Default caps are intentionally small to respect Notion rate limits:

  • issues: 30
  • prs: 30
  • commits: 30
  • releases: 10
  • workflow_runs: 30

Projects are upserted using a stable Key field (the repo full name), so re-running the sync is idempotent.

Snapshot export ​

python scripts/export_snapshot.py writes:

  • output/observable/snapshot.json
  • output/observable/snapshot.csv (denormalized activity view)
  • output/observable/codex_wrapped_stats.json (if local Codex Wrapped skill is available)

python scripts/publish_dashboard_data.py then copies those files to:

  • DOCS/public/dashboard/data/snapshot.json
  • DOCS/public/dashboard/data/snapshot.csv
  • DOCS/public/dashboard/data/codex_wrapped_stats.json

The JSON payload includes:

  • generated_at
  • window_days
  • projects, activity, conversations, tasks
  • codex_wrapped (optional; rolling Codex usage windows + rendered wrapped text)

Conversation logging ​

python scripts/log_convo.py creates a Conversation in Notion and optionally creates Tasks. Each conversation links to an existing Project (run sync.py first).

Known limitations ​

  • Observable refresh is manual (replace the FileAttachment).
  • Notion API rate limits make large repos slower; keep caps modest.
  • The hosted React dashboard is snapshot-driven (not real-time live API queries).