Merge pull request #1 from opensource-observer/carl/oso-1926-create-a-standalone-ddp-public-repo-and-ensure-it-works

initial commit

Author: ccerv1

.env.example

@@ -0,0 +1,3 @@
+# OSO API Key
+# Get your API key from https://www.oso.xyz/start
+OSO_API_KEY=your_api_key_here

.gitignore

@@ -0,0 +1,22 @@
+# Local cache
+__marimo__
+
+# Python
+.venv/
+__pycache__/
+*.py[cod]
+
+# Environment variables
+.env
+.env.local
+
+# Next.js
+app/.next/
+app/out/
+app/node_modules/
+
+# OS
+.DS_Store
+
+# Claude Code local settings
+.claude/

README.md

@@ -0,0 +1,109 @@
+# Developer Data Portal
+
+A data portal that serves Marimo notebooks through a Next.js interface. Built on [OSO](https://www.oso.xyz).
+
+## Quickstart
+
+```bash
+# 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](https://www.oso.xyz/start))
+- [uv](https://docs.astral.sh/uv/) — Python package manager
+- Node.js 20+ and [pnpm](https://pnpm.io/)
+
+## 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:
+
+```tsx
+<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
+
+```python
+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`](notebooks/claude.md).
+
+## Running servers separately
+
+```bash
+# 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.

app/app/agent-guide/page.tsx

@@ -0,0 +1,9 @@
+import MarimoIframe from '@/components/MarimoIframe';
+
+export default function AgentGuide() {
+  return (
+    <div className="h-full w-full">
+      <MarimoIframe notebookName="notebooks/agent-guide" />
+    </div>
+  );
+}

app/app/data/metric-definitions/activity/page.tsx

@@ -0,0 +1,9 @@
+import MarimoIframe from '@/components/MarimoIframe';
+
+export default function Activity() {
+  return (
+    <div className="h-full w-full">
+      <MarimoIframe notebookName="notebooks/data/metric-definitions/activity" />
+    </div>
+  );
+}

app/app/data/metric-definitions/alignment/page.tsx

@@ -0,0 +1,9 @@
+import MarimoIframe from '@/components/MarimoIframe';
+
+export default function Alignment() {
+  return (
+    <div className="h-full w-full">
+      <MarimoIframe notebookName="notebooks/data/metric-definitions/alignment" />
+    </div>
+  );
+}

app/app/data/metric-definitions/lifecycle/page.tsx

@@ -0,0 +1,9 @@
+import MarimoIframe from '@/components/MarimoIframe';
+
+export default function Lifecycle() {
+  return (
+    <div className="h-full w-full">
+      <MarimoIframe notebookName="notebooks/data/metric-definitions/lifecycle" />
+    </div>
+  );
+}

app/app/data/metric-definitions/retention/page.tsx

@@ -0,0 +1,9 @@
+import MarimoIframe from '@/components/MarimoIframe';
+
+export default function Retention() {
+  return (
+    <div className="h-full w-full">
+      <MarimoIframe notebookName="notebooks/data/metric-definitions/retention" />
+    </div>
+  );
+}

app/app/data/models/commits/page.tsx

@@ -0,0 +1,9 @@
+import MarimoIframe from '@/components/MarimoIframe';
+
+export default function Commits() {
+  return (
+    <div className="h-full w-full">
+      <MarimoIframe notebookName="notebooks/data/models/commits" />
+    </div>
+  );
+}

app/app/data/models/developers/page.tsx

@@ -0,0 +1,9 @@
+import MarimoIframe from '@/components/MarimoIframe';
+
+export default function Developers() {
+  return (
+    <div className="h-full w-full">
+      <MarimoIframe notebookName="notebooks/data/models/developers" />
+    </div>
+  );
+}