Developer Data Portal

A data portal that serves Marimo notebooks through a Next.js interface. Built on OSO.

Quickstart

# 1. Get an OSO API key at https://www.oso.xyz/start
cp .env.example .env
# Add your key: OSO_API_KEY=your_key_here

# 2. Install dependencies
uv sync
cd app && pnpm install && cd ..

# 3. Export notebooks to static HTML
cd app && pnpm export:notebooks && cd ..

# 4. Start the dev server
cd app && pnpm dev

Open http://localhost:3000.

Prerequisites

• OSO API key (get one here)
• uv — Python package manager
• Node.js 20+ and pnpm

Structure

ddp/
├── notebooks/              # Marimo notebooks (.py)
│   ├── quick-start.py
│   ├── publications.py
│   ├── agent-guide.py
│   ├── data/
│   │   ├── sources/        # Open Dev Data, GitHub Archive, OSS Directory
│   │   ├── models/         # Ecosystems, Repositories, Developers, Commits, Events, Timeseries Metrics
│   │   └── metric-definitions/  # Activity, Alignment, Lifecycle, Retention
│   └── insights/           # 2025 Developer Trends, Lifecycle, Speedrun Ethereum, DeFi Journeys, Retention
├── scripts/
│   └── export_notebooks.py # Exports notebooks to static HTML
├── app/                    # Next.js app (UI shell)
│   ├── app/                # Pages (App Router)
│   ├── components/         # Sidebar, MarimoIframe
│   └── public/notebooks/   # Exported HTML (generated, gitignored)
└── pyproject.toml

How it works

• Export step — scripts/export_notebooks.py runs marimo export html on each notebook, writing static HTML to app/public/notebooks/
• Next.js app (localhost:3000) — navigation shell that serves the exported HTML via MarimoIframe
• CI — the deploy workflow exports notebooks and builds the site on push to main. A weekly refresh re-exports to pick up fresh data.

Each page in the Next.js app is a thin wrapper around a MarimoIframe component:

<MarimoIframe notebookName="notebooks/insights/developer-lifecycle" />

Adding a notebook

1. Create notebooks/<category>/<name>.py using the standard template below
2. Add a page at app/app/<category>/<name>/page.tsx
3. Add a nav entry to app/components/Sidebar.tsx
4. Run cd app && pnpm export:notebooks to generate the HTML

Notebook template

import marimo

__generated_with = "unknown"
app = marimo.App(width="full")

@app.cell(hide_code=True)
def setup_pyoso():
    # This code sets up pyoso to be used as a database provider for this notebook
    # This code is autogenerated. Modification could lead to unexpected results :)
    import pyoso
    import marimo as mo
    pyoso_db_conn = pyoso.Client().dbapi_connection()
    return mo, pyoso_db_conn

# Add cells here

if __name__ == "__main__":
    app.run()

For detailed notebook conventions, see notebooks/claude.md.

Configuration

Variable	Description
OSO_API_KEY	Required. OSO data warehouse access key.