Developer Guide

✅ All JS inside one IIFE with "use strict"
✅ All CSS classes prefixed with the app slug
✅ All colors use var(--bs-*) tokens
✅ querySelectorAll scoped to document.querySelector(".nr-app")
✅ No onclick="globalFunction()" — use data-action + event delegation
✅ No <script src="bootstrap…"> in the body
✅ Vendor libraries loaded from /assets/vendor/* — never from an external CDN

app_<your_name>/            ← dir name = URL segment = app_name in manifest
│
├── manifest.json    (R)   ← app identity, version, declared actions
├── main.py          (R)   ← Python backend — must export execute(data, conn=None)
│
├── index.html       (R*)  ← frontend page (Bootstrap, no build tools)
├── index.js               ← frontend logic — must be wrapped in an IIFE
├── style.css              ← component-scoped styles — all classes must be prefixed
│
└── libs/                  ← vendored Python packages (pip install --target)
    └── <package>/

app_<your_name>.zip
├── manifest.json
├── main.py
├── index.html
├── index.js
├── style.css
└── libs/
    └── …

# Pack with (PowerShell):
Compress-Archive -Path app_<your_name>\* -DestinationPath app_<your_name>.zip

import os, logging, psycopg2

log = logging.getLogger(__name__)

def _migrate() -> None:
    """
    Runs idempotent DDL on every app load / hot-reload.
    Called at module level — executes automatically on deploy.
    """
    dsn = os.getenv("DATABASE_URL", "")
    if not dsn:
        log.warning("[<slug>] DATABASE_URL not set — skipping migration")
        return
    with psycopg2.connect(dsn) as conn:
        with conn.cursor() as cur:
            cur.execute("""
                CREATE TABLE IF NOT EXISTS <slug>_items (
                    id         SERIAL PRIMARY KEY,
                    name       TEXT        NOT NULL,
                    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
                )
            """)
        conn.commit()
    log.info("[<slug>] migration ok")

# ── Runs on every deploy / hot-reload ─────────────────────────────────────
_migrate()

def execute(data: dict, conn=None) -> dict:
    action = str(data.get("action", "")).strip()

    if action == "list":
        return _list(conn=conn)
    if action == "create":
        return _create(data, conn=conn)
    if action == "run_report":     # long-running → send via async channel
        return _run_report(data)

    return {"message": "ok"}

import contextlib, os, psycopg2

@contextlib.contextmanager
def _get_conn(conn=None):
    if conn is not None:
        yield conn
    else:
        with psycopg2.connect(os.getenv("DATABASE_URL")) as own:
            yield own

def _list(conn=None) -> dict:
    with _get_conn(conn) as c:
        with c.cursor() as cur:
            cur.execute("SELECT id, name FROM <slug>_items ORDER BY id DESC")
            rows = cur.fetchall()
    return {"rows": [{"id": r[0], "name": r[1]} for r in rows]}

import os, time, psycopg2

def _run_report(data: dict) -> dict:
    job_id        = data.get("_job_id", "")   # injected by the runner
    dsn           = os.getenv("DATABASE_URL", "")
    total         = 100
    milestone     = 10
    last_reported = 0

    for i in range(total):
        # --- your heavy compute here ---
        time.sleep(0.1)

        progress = int(((i + 1) / total) * 100)

        if job_id and dsn and progress >= last_reported + milestone:
            last_reported = (progress // milestone) * milestone
            try:
                with psycopg2.connect(dsn) as c:
                    with c.cursor() as cur:
                        cur.execute(
                            "UPDATE noderouter_core.job_queue "
                            "SET progress = %s, updated_at = NOW() WHERE id = %s",
                            (last_reported, job_id),
                        )
                    c.commit()
            except Exception:
                pass   # never crash the job over a progress write

    return {"message": "done", "processed": total}

def execute(data: dict, conn=None) -> dict:
    deal = close_deal(data["deal_id"])
    return {
        "deal_id": deal.id,          # returned to the API caller as-is
        "amount":  deal.amount,
        "_actions": [             # stripped before the response is sent
            {
                "name":    "deal_closed",          # must match a slug declared in manifest actions[]
                "payload": {"deal_id": deal.id},  # what subscribers receive — not the full result
            }
        ]
    }

(function () {
  "use strict";
  var root  = document.querySelector(".nr-app") || document.body;
  var chart = echarts.init(root.querySelector("#<prefix>-chart"), null, {
    renderer: "canvas",
  });

  function renderChart(rows) {
    chart.setOption({
      tooltip: { trigger: "axis" },
      xAxis:   { type: "category", data: rows.map(function (r) { return r.label; }) },
      yAxis:   { type: "value" },
      series:  [{ type: "bar", data: rows.map(function (r) { return r.value; }) }],
    });
  }

  // Re-fit chart when sidebar collapses / window resizes.
  window.addEventListener("resize", function () { chart.resize(); });
})();

<!-- in <head>: -->
<link rel="stylesheet" href="/assets/vendor/tabulator.min.css" />
<!-- before index.js: -->
<script src="/assets/vendor/tabulator.min.js"></script>

// index.js
(function () {
  "use strict";
  var root  = document.querySelector(".nr-app") || document.body;
  var table = new Tabulator(root.querySelector("#<prefix>-grid"), {
    layout:           "fitColumns",
    responsiveLayout: "collapse",
    pagination:       "local",
    paginationSize:   20,
    columns: [
      { title: "ID",   field: "id",   width: 80 },
      { title: "Name", field: "name", widthGrow: 1 },
      { title: "Date", field: "created_at" },
    ],
  });

  function loadData(rows) { table.setData(rows); }
})();

(function () {
  "use strict";
  var root = document.querySelector(".nr-app") || document.body;
  var currentRows = [];

  function exportToExcel(rows, filename) {
    var ws = XLSX.utils.json_to_sheet(rows);
    var wb = XLSX.utils.book_new();
    XLSX.utils.book_append_sheet(wb, ws, "Sheet1");
    XLSX.writeFile(wb, (filename || "export") + ".xlsx");
  }

  // <button data-action="export-excel">Export</button>
  root.addEventListener("click", function (e) {
    if (e.target.dataset.action === "export-excel") {
      exportToExcel(currentRows, "<slug>-report");
    }
  });
})();

(function () {
  "use strict";
  var root = document.querySelector(".nr-app") || document.body;

  root.querySelector("#<prefix>-csv-input").addEventListener("change", function (e) {
    var file = e.target.files[0];
    if (!file) return;
    Papa.parse(file, {
      header:         true,
      skipEmptyLines: true,
      complete: function (result) {
        // result.data is an array of row objects keyed by header name.
        console.log(result.data);
      },
      error: function (err) {
        console.error("CSV parse error:", err.message);
      },
    });
  });
})();

(function () {
  "use strict";

  // Format an ISO timestamp from the server into a readable local string.
  function fmtDate(iso) {
    return dayjs(iso).format("DD/MM/YYYY HH:mm");
  }

  // Age in days
  function daysAgo(iso) {
    return dayjs().diff(dayjs(iso), "day");
  }
})();

<!-- In HTML: -->
<i data-lucide="download"></i>
<i data-lucide="refresh-cw"></i>
<i data-lucide="alert-triangle"></i>

// index.js
(function () {
  "use strict";
  var root = document.querySelector(".nr-app") || document.body;

  // Replace all data-lucide placeholders with inline SVGs.
  lucide.createIcons();

  function renderRows(rows) {
    root.querySelector("#<prefix>-list").innerHTML = rows
      .map(function (r) {
        return '<li><i data-lucide="circle-dot"></i> ' + esc(r.name) + "</li>";
      })
      .join("");
    lucide.createIcons(); // re-scan after injecting new HTML
  }
})();

# Install package into the libs/ folder
pip install <package> --target app_<your_name>/libs

# Then at the top of main.py:
import sys, os
sys.path.insert(0, os.path.join(os.path.dirname(__file__), "libs"))
import my_package

# Default action
curl -s -X POST http://localhost:8000/api/sync/app_<your_name> `
     -H "Content-Type: application/json" `
     -d '{}'

# Named action
curl -s -X POST http://localhost:8000/api/sync/app_<your_name> `
     -H "Content-Type: application/json" `
     -d '{"action":"list"}'

# Trigger an async job
curl -s -X POST http://localhost:8000/api/async/app_<your_name> `
     -H "Content-Type: application/json" `
     -d '{"action":"run_report"}'