Development

Local setup

Requirements:

• Python 3.12+
• A Notion integration token and a parent page ID
• A GitHub Personal Access Token (read access)

Create .env from .env.example and populate:

• NOTION_TOKEN
• NOTION_PARENT_PAGE_ID
• GITHUB_TOKEN
• SYNC_WINDOW_DAYS (optional; default 90)

Repo layout

• scripts/: CLI entrypoints (sync.py, log_convo.py, log_convos.py, export_snapshot.py)
• src/dashboard/: core modules (clients, sync logic, export, logging)
• apps/dashboard/: React web app for roadmap/changelog visualization
• config/repos.yaml: repo allowlist
• DOCS/: VitePress documentation content

Running locally

• Sync GitHub -> Notion: python scripts/sync.py
• Log a conversation: python scripts/log_convo.py --provider Codex --repo owner/name --title "..." --summary "..."
• Batch log conversations: python scripts/log_convos.py --input input/conversations_today.csv --ensure-projects
• Export snapshot: python scripts/export_snapshot.py
• Publish dashboard data for hosting: python scripts/publish_dashboard_data.py
• Run React dashboard locally: npm --prefix apps/dashboard install && npm --prefix apps/dashboard run dev
• Build React dashboard into docs public path: npm --prefix apps/dashboard run build:embed
• Build docs + embedded dashboard: npm --prefix docs-site run build

Common flags for sync:

• --repo owner/name (repeatable, overrides allowlist)
• --projects-only (skip activity)
• --window-days N and --cap-* limits

Tests

Run the unit tests with: python -m unittest discover -s tests -p "test_*.py"

Debugging tips

• Missing Notion parent page: ensure the integration has access to NOTION_PARENT_PAGE_ID.
• Rate limits: if you hit 429s, reduce caps or narrow SYNC_WINDOW_DAYS.
• Repo not found: check config/repos.yaml or pass --repo explicitly.