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. Start
cd app && pnpm dev:all

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)
│   ├── home.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
├── app/                    # Next.js app (UI shell)
│   ├── app/                # Pages (App Router)
│   └── components/         # Sidebar, MarimoIframe
├── serve_notebooks.py      # Marimo ASGI server (port 8000)
└── pyproject.toml

How it works

• Marimo server (localhost:8000) — runs notebook kernels via serve_notebooks.py
• Next.js app (localhost:3000) — navigation shell that embeds notebooks in iframes

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

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.

Running servers separately

# Terminal 1 — Marimo
uv run python serve_notebooks.py

# Terminal 2 — Next.js
cd app && pnpm dev

Notebooks are served at http://localhost:8000/notebooks/<name> — Marimo must be running for iframes to render.

Configuration

Variable	Description
OSO_API_KEY	Required. OSO data warehouse access key.

The Marimo port defaults to 8000. To change it, update serve_notebooks.py and the marimoPort prop on MarimoIframe in any relevant pages.