Research Software Innovation team prototypes

Small Flask demo that hosts multiple "prototypes" (mini apps). Each prototype lives under prototypes/<kebab-name>/ and its templates are namespaced under templates/<kebab-name>/. The main app.py file discovers and registers blueprints for each prototype automatically.

Initial local setup

1. Install just

# macOS
brew install just

# Linux
# Install from https://github.com/casey/just/releases

# Add completion for your shell. E.g. for bash:
source <(just --completions bash)

2. Install uv for your system

3. Create a virtual environment and install dependencies

just devenv

4. Activate the virtual environment

source .venv/bin/activate

Running the app locally

# Run on default port 5000
just run

# To run on a different port, e.g. 5001:
PORT=5001 just run

Starts on port 5000 by default. Open http://127.0.0.1:5000 to see the prototype list. Individual prototypes are available at /<kebab-name>/.

Shared static files and API

This app exposes a shared static folder and a small API that all prototypes can use:

• Shared static files are served from /static/. Place assets in the /static/ folder in the repo root. Prototypes can reference them directly, for example: /static/shared.css. This is automatically done by Flask.
• A simple API is available under /api. A health endpoint is at /api/ping which returns JSON { "ok": true, "source": "shared-api" }.

Debugging the app

Use the provided VSCode launch configuration Debug webapp to run and debug the app.

Create a new prototype

Use the provided scaffold script to create a new prototype and its namespaced template:

Interactive

just create

Non-interactive

./scripts/scaffold_prototype.py --name "Hello World" --description "Short description"

The scaffold creates:

• prototypes/<kebab-name>/info.json — metadata (display name, description)
• prototypes/<kebab-name>/routes.py — blueprint that renders "<kebab-name>/index.html"
• templates/<kebab-name>/index.html — placeholder template

Running Tests

# Starts the server (port 5001), runs tests, then stops the server
just test

# To specify a different port for the server
PORT=5002 just test

This automatically starts the Flask server, runs the tests, and stops the server when done.

Deployment

• Pushes to the main branch trigger a deployment to DigitalOcean App Platform.
• The live site is available at https://dolphin-app-z2vdi.ondigitalocean.app/.
• DigitalOcean automatically detects uv.lock and installs production dependencies only.