@brendanbank/create-atrium-host 0.15.0

package/template/backend/alembic.ini

@@ -0,0 +1,50 @@
+# Host-side alembic config. Atrium owns its own chain in the runtime
+# image (version table: alembic_version). The host owns this chain in
+# alembic_version_app — see env.py. Run with:
+#
+#   alembic -c /opt/host_app/alembic.ini upgrade head
+#
+# inside the api container after the atrium chain is up.
+
+[alembic]
+# %(here)s resolves to the directory of this ini file. Without it,
+# script_location is interpreted relative to the CWD, which means
+# `alembic -c /opt/host_app/alembic.ini ...` run from /app would load
+# /app/alembic (atrium's chain) instead of the host's.
+script_location = %(here)s/alembic
+prepend_sys_path = %(here)s/src
+sqlalchemy.url =
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

package/template/backend/pyproject.toml

@@ -0,0 +1,17 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "__HOST_NAME__-host"
+version = "0.1.0"
+description = "__BRAND_NAME__ host extension for Atrium"
+requires-python = ">=3.12"
+
+# All runtime deps come from the atrium image (FastAPI, SQLAlchemy,
+# Alembic, structlog). Listing them here would just shadow atrium's
+# pinned versions. The package is installed via `pip install ./backend`
+# inside the image so `__HOST_PKG__` is importable on PYTHONPATH.
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/__HOST_PKG__"]

package/template/backend/src/__HOST_PKG__/bootstrap.py

@@ -0,0 +1,52 @@
+"""Atrium host bootstrap entry points.
+
+The atrium image imports this module on startup when the operator sets
+``ATRIUM_HOST_MODULE=__HOST_PKG__.bootstrap``:
+
+- ``init_app(app)`` runs once during ``create_app()`` — after every
+  atrium router is included and before the ASGI app starts serving.
+  We use it to mount our router; permissions are seeded by the alembic
+  migration (``alembic/versions/0001_init.py``).
+- ``init_worker(host)`` runs on worker startup, after atrium's
+  built-in handlers register and before APScheduler starts. ``host``
+  is a :class:`~app.host_sdk.worker.HostWorkerCtx` that exposes the
+  APScheduler instance plus a typed ``register_job_handler`` for
+  ``scheduled_jobs`` dispatch.
+
+Both functions are optional — a module that defines neither is
+allowed (atrium logs ``host.init_app.absent`` and continues). Delete
+either when you don't need it.
+"""
+from __future__ import annotations
+
+from fastapi import FastAPI
+
+from app.host_sdk.worker import HostWorkerCtx
+
+
+def init_app(app: FastAPI) -> None:
+    from .router import router
+
+    app.include_router(router)
+
+
+def init_worker(host: HostWorkerCtx) -> None:
+    # Recurring APScheduler tick — fires inside the worker process,
+    # NOT the api process. Use this for stateless idempotent work.
+    #
+    # from .schedule import tick
+    # host.scheduler.add_job(
+    #     tick, "interval", seconds=30,
+    #     id="__HOST_PKG__-tick", coalesce=True, max_instances=1,
+    # )
+
+    # Durable scheduled_jobs handler — each row is claimed FOR UPDATE
+    # SKIP LOCKED by exactly one worker, retried on failure.
+    #
+    # from .handlers import handle_thing
+    # host.register_job_handler(
+    #     kind="__HOST_PKG__.thing",
+    #     handler=handle_thing,
+    #     description="Drain __HOST_PKG__.thing scheduled_jobs rows",
+    # )
+    _ = host  # marker so type-checkers don't warn about the unused arg

package/template/backend/src/__HOST_PKG__/models.py

@@ -0,0 +1,51 @@
+"""Host-side ORM models.
+
+The host owns its own ``DeclarativeBase`` (and therefore its own
+``MetaData``) so atrium's alembic chain never sees this table. The
+host's alembic chain manages it under a separate version table
+(``alembic_version_app``); see ``alembic/env.py``.
+
+Rules of engagement:
+
+- **Never** parent host tables on ``app.db.Base``. The next atrium
+  upgrade may collide with whatever you added.
+- Cross-base foreign keys (a host column referencing ``users.id`` or
+  any other atrium table) need ``HostForeignKey`` from
+  ``app.host_sdk.db`` plus ``emit_host_foreign_keys`` wired into
+  ``alembic/env.py`` — both already configured in the scaffolded
+  files. See ``docs/host-models.md`` in the atrium repo for the full
+  rationale.
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import BigInteger, Integer, String, text
+from sqlalchemy.dialects.mysql import DATETIME as MysqlDATETIME
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+
+class HostBase(DeclarativeBase):
+    """Host metadata, separate from atrium's ``app.db.Base``."""
+
+
+class __BRAND_PASCAL__State(HostBase):
+    """Singleton row (id=1) for the demo widget. Replace with your
+    real domain models — and remove the corresponding migration row
+    when you do."""
+
+    __tablename__ = "__HOST_PKG___state"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=False)
+    message: Mapped[str] = mapped_column(
+        String(255), nullable=False, default="Welcome to __BRAND_NAME__"
+    )
+    counter: Mapped[int] = mapped_column(
+        BigInteger, nullable=False, default=0
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        MysqlDATETIME(fsp=6),
+        nullable=False,
+        server_default=text("CURRENT_TIMESTAMP(6)"),
+        server_onupdate=text("CURRENT_TIMESTAMP(6)"),
+    )

package/template/backend/src/__HOST_PKG__/router.py

@@ -0,0 +1,73 @@
+"""Demo HTTP surface.
+
+- ``GET /__HOST_PKG__/state`` — read-only, auth required.
+- ``POST /__HOST_PKG__/bump`` — gated by ``__HOST_PKG__.write``,
+  increments the demo counter and writes an audit row.
+
+Replace these with your real routes. The auth dependencies and the
+audit/notify helpers (imported from ``app.*``) are the surface a
+host calls atrium through.
+"""
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends
+from pydantic import BaseModel
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.auth.rbac import require_perm
+from app.auth.users import current_user
+from app.db import get_session
+from app.models.auth import User
+from app.services.audit import record as record_audit
+
+from .models import __BRAND_PASCAL__State
+
+router = APIRouter(prefix="/__HOST_PKG__", tags=["__HOST_PKG__"])
+
+
+class StateOut(BaseModel):
+    message: str
+    counter: int
+
+
+async def _load_state(session: AsyncSession) -> __BRAND_PASCAL__State:
+    state = (
+        await session.execute(
+            select(__BRAND_PASCAL__State).where(__BRAND_PASCAL__State.id == 1)
+        )
+    ).scalar_one_or_none()
+    if state is None:
+        raise RuntimeError(
+            "__HOST_PKG___state row id=1 missing — run the host alembic upgrade",
+        )
+    return state
+
+
+@router.get("/state", response_model=StateOut)
+async def get_state(
+    _user: User = Depends(current_user),
+    session: AsyncSession = Depends(get_session),
+) -> StateOut:
+    state = await _load_state(session)
+    return StateOut(message=state.message, counter=state.counter)
+
+
+@router.post("/bump", response_model=StateOut)
+async def bump(
+    user: User = Depends(require_perm("__HOST_PKG__.write")),
+    session: AsyncSession = Depends(get_session),
+) -> StateOut:
+    state = await _load_state(session)
+    before = state.counter
+    state.counter += 1
+    await record_audit(
+        session,
+        actor_user_id=user.id,
+        entity="__HOST_PKG___state",
+        entity_id=state.id,
+        action="bump",
+        diff={"counter": {"before": before, "after": state.counter}},
+    )
+    await session.commit()
+    return StateOut(message=state.message, counter=state.counter)

package/template/backend/src/__HOST_PKG__/scripts/seed_host_bundle.py

@@ -0,0 +1,48 @@
+"""One-shot CLI: write ``system.host_bundle_url`` so atrium picks up
+the host frontend bundle on the next page load.
+
+Run inside the api container after migrations + admin seeding:
+
+    python -m __HOST_PKG__.scripts.seed_host_bundle /host/main.js
+
+Idempotent. Preserves other ``system`` fields by JSON-merging onto
+whatever's already there.
+"""
+from __future__ import annotations
+
+import asyncio
+import sys
+
+from sqlalchemy import select
+from sqlalchemy.dialects.mysql import insert
+
+from app.db import get_session_factory
+from app.models.ops import AppSetting
+
+
+async def _seed(url: str) -> None:
+    factory = get_session_factory()
+    async with factory() as session:
+        existing = (
+            await session.execute(
+                select(AppSetting).where(AppSetting.key == "system")
+            )
+        ).scalar_one_or_none()
+        merged = {**(existing.value if existing else {}), "host_bundle_url": url}
+
+        stmt = insert(AppSetting).values(key="system", value=merged)
+        stmt = stmt.on_duplicate_key_update(value=merged)
+        await session.execute(stmt)
+        await session.commit()
+        print(f"system.host_bundle_url set to {url!r}")
+
+
+def main() -> None:
+    if len(sys.argv) != 2:
+        print("usage: seed_host_bundle <url>", file=sys.stderr)
+        sys.exit(2)
+    asyncio.run(_seed(sys.argv[1]))
+
+
+if __name__ == "__main__":
+    main()

package/template/backend/tests/test_smoke.py

@@ -0,0 +1,47 @@
+"""Smoke tests that don't need a running database.
+
+The atrium runtime image strips ``pytest`` to keep the prod image
+small; install it on demand with the ``test-backend`` Make target.
+Tests here verify the package imports cleanly and the bootstrap
+entry points have the right signatures — enough for CI to catch a
+broken extension before it hits the api container.
+"""
+from __future__ import annotations
+
+import inspect
+
+
+def test_package_imports() -> None:
+    import __HOST_PKG__  # noqa: F401
+
+
+def test_bootstrap_signatures() -> None:
+    from __HOST_PKG__.bootstrap import init_app, init_worker
+
+    # Shape match against what atrium calls. The signatures are part
+    # of the contract; if they drift, fail loudly here rather than on
+    # api boot.
+    assert list(inspect.signature(init_app).parameters) == ["app"]
+    assert list(inspect.signature(init_worker).parameters) == ["host"]
+
+
+def test_router_mounted() -> None:
+    from __HOST_PKG__.router import router
+
+    paths = {route.path for route in router.routes}
+    assert "/__HOST_PKG__/state" in paths
+    assert "/__HOST_PKG__/bump" in paths
+
+
+def test_models_isolated_from_atrium_base() -> None:
+    """HostBase must not share metadata with atrium's app.db.Base.
+
+    Sharing would mean autogenerate sees atrium tables and proposes
+    drop_table ops on every revision — the most painful failure
+    mode of the host-extension model. Catch it here.
+    """
+    from app.db import Base as AtriumBase
+
+    from __HOST_PKG__.models import HostBase
+
+    assert HostBase.metadata is not AtriumBase.metadata

package/template/compose.yaml

@@ -0,0 +1,96 @@
+# __BRAND_NAME__ — self-contained prod compose.
+#
+# Pulls atrium from GHCR, builds the host extension on top, brings up
+# api + worker + mysql. No proxy, no TLS — atrium speaks plain HTTP on
+# :8000 by design. Put your own TLS terminator (Caddy, nginx, the load
+# balancer at your edge) in front for production.
+#
+# Usage (from this directory):
+#
+#   cp .env.example .env  # fill in JWT_SECRET, DB password
+#   docker compose up -d --build
+#   make migrate
+#   make seed-admin EMAIL=you@example.com PASSWORD=...
+#
+# Environment variables come from .env via ${VAR} interpolation.
+
+services:
+  api:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      args:
+        ATRIUM_IMAGE: ${ATRIUM_IMAGE:-ghcr.io/brendanbank/atrium:__ATRIUM_VERSION__}
+    image: __HOST_NAME__:latest
+    pull_policy: never
+    restart: unless-stopped
+    environment:
+      ENVIRONMENT: ${ENVIRONMENT:-prod}
+      APP_TIMEZONE: ${APP_TIMEZONE:-UTC}
+      APP_SECRET_KEY: ${APP_SECRET_KEY}
+      APP_BASE_URL: ${APP_BASE_URL:-http://localhost:8000}
+      DATABASE_URL: ${DATABASE_URL}
+      JWT_SECRET: ${JWT_SECRET}
+      JWT_ACCESS_TOKEN_EXPIRE_MINUTES: ${JWT_ACCESS_TOKEN_EXPIRE_MINUTES:-10080}
+      WEBAUTHN_RP_ID: ${WEBAUTHN_RP_ID:-localhost}
+      WEBAUTHN_RP_NAME: ${WEBAUTHN_RP_NAME:-__BRAND_NAME__}
+      WEBAUTHN_ORIGIN: ${WEBAUTHN_ORIGIN:-http://localhost:8000}
+      MAIL_BACKEND: ${MAIL_BACKEND:-console}
+      MAIL_FROM: ${MAIL_FROM:-no-reply@example.com}
+      ATRIUM_HOST_MODULE: __HOST_PKG__.bootstrap
+      # Host alembic runs with cwd=/opt/host_app (via -c
+      # /opt/host_app/alembic.ini) and its env.py imports from
+      # atrium's `app` package. Atrium's source lives at /app — put
+      # it on PYTHONPATH so the import resolves no matter where the
+      # caller's cwd is.
+      PYTHONPATH: /app
+    ports:
+      - "8000:8000"
+    depends_on:
+      mysql:
+        condition: service_healthy
+
+  worker:
+    image: __HOST_NAME__:latest
+    pull_policy: never
+    restart: unless-stopped
+    environment:
+      ENVIRONMENT: ${ENVIRONMENT:-prod}
+      APP_TIMEZONE: ${APP_TIMEZONE:-UTC}
+      APP_SECRET_KEY: ${APP_SECRET_KEY}
+      APP_BASE_URL: ${APP_BASE_URL:-http://localhost:8000}
+      DATABASE_URL: ${DATABASE_URL}
+      JWT_SECRET: ${JWT_SECRET}
+      MAIL_BACKEND: ${MAIL_BACKEND:-console}
+      MAIL_FROM: ${MAIL_FROM:-no-reply@example.com}
+      ATRIUM_HOST_MODULE: __HOST_PKG__.bootstrap
+      PYTHONPATH: /app
+    command: ["python", "-m", "app.worker"]
+    depends_on:
+      mysql:
+        condition: service_healthy
+      api:
+        condition: service_started
+    healthcheck:
+      disable: true
+
+  mysql:
+    image: mysql:8.0
+    restart: unless-stopped
+    command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci --default-time-zone=+00:00
+    environment:
+      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
+      MYSQL_DATABASE: ${MYSQL_DATABASE}
+      MYSQL_USER: ${MYSQL_USER}
+      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
+    volumes:
+      - mysql_data:/var/lib/mysql
+    healthcheck:
+      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-p${MYSQL_ROOT_PASSWORD}"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+
+volumes:
+  mysql_data:
+    name: __HOST_PKG___mysql_data

package/template/frontend/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "__HOST_NAME__-frontend",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Host extension bundle for atrium — registers a home widget, route, nav item, admin tab, and profile slot.",
+  "scripts": {
+    "build": "vite build",
+    "build:watch": "vite build --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@brendanbank/atrium-host-bundle-utils": "^__ATRIUM_VERSION__",
+    "@brendanbank/atrium-host-types": "^__ATRIUM_VERSION__",
+    "@mantine/core": "^9.1.0",
+    "@mantine/hooks": "^9.1.0",
+    "@tabler/icons-react": "^3.41.1",
+    "@tanstack/react-query": "^5.100.1",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5"
+  },
+  "devDependencies": {
+    "@brendanbank/atrium-test-utils": "^__ATRIUM_VERSION__",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "jsdom": "^29.0.2",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.10",
+    "vite-plugin-css-injected-by-js": "^3.5.2",
+    "vitest": "^4.1.5"
+  }
+}

package/template/frontend/src/__BRAND_PASCAL__AdminTab.tsx

@@ -0,0 +1,32 @@
+import { MantineProvider, Stack, Text, Title } from '@mantine/core';
+import { QueryClientProvider } from '@tanstack/react-query';
+import { AtriumProvider } from '@brendanbank/atrium-host-bundle-utils/react';
+
+import { __BRAND_PASCAL__Widget } from './__BRAND_PASCAL__Widget';
+import { queryClient } from './queryClient';
+
+function __BRAND_PASCAL__AdminTabInner() {
+  return (
+    <Stack gap="md">
+      <Title order={3}>__BRAND_NAME__ admin</Title>
+      <Text c="dimmed" size="sm">
+        Permission-gated tab in the admin shell. Atrium hides this tab
+        for users without ``__HOST_PKG__.write``; the API enforces the
+        same on every write.
+      </Text>
+      <__BRAND_PASCAL__Widget />
+    </Stack>
+  );
+}
+
+export function __BRAND_PASCAL__AdminTab() {
+  return (
+    <MantineProvider>
+      <QueryClientProvider client={queryClient}>
+        <AtriumProvider>
+          <__BRAND_PASCAL__AdminTabInner />
+        </AtriumProvider>
+      </QueryClientProvider>
+    </MantineProvider>
+  );
+}

package/template/frontend/src/__BRAND_PASCAL__Page.tsx

@@ -0,0 +1,34 @@
+import { Container, Stack, Text, Title } from '@mantine/core';
+import { MantineProvider } from '@mantine/core';
+import { QueryClientProvider } from '@tanstack/react-query';
+import { AtriumProvider } from '@brendanbank/atrium-host-bundle-utils/react';
+
+import { __BRAND_PASCAL__Widget } from './__BRAND_PASCAL__Widget';
+import { queryClient } from './queryClient';
+
+function __BRAND_PASCAL__PageInner() {
+  return (
+    <Container size="md" py="xl">
+      <Stack gap="md">
+        <Title order={2}>__BRAND_NAME__</Title>
+        <Text c="dimmed">
+          Dedicated route registered by the host bundle. Replace this
+          page with your real domain UI.
+        </Text>
+        <__BRAND_PASCAL__Widget />
+      </Stack>
+    </Container>
+  );
+}
+
+export function __BRAND_PASCAL__Page() {
+  return (
+    <MantineProvider>
+      <QueryClientProvider client={queryClient}>
+        <AtriumProvider>
+          <__BRAND_PASCAL__PageInner />
+        </AtriumProvider>
+      </QueryClientProvider>
+    </MantineProvider>
+  );
+}

package/template/frontend/src/__BRAND_PASCAL__ProfileItem.tsx

@@ -0,0 +1,38 @@
+import { Card, MantineProvider, Stack, Text, Title } from '@mantine/core';
+import { QueryClientProvider } from '@tanstack/react-query';
+import { AtriumProvider, useMe } from '@brendanbank/atrium-host-bundle-utils/react';
+
+import { queryClient } from './queryClient';
+
+function __BRAND_PASCAL__ProfileItemInner() {
+  const { data: me } = useMe();
+  return (
+    <Card withBorder padding="lg" radius="md">
+      <Stack gap="xs">
+        <Title order={4}>__BRAND_NAME__</Title>
+        <Text size="sm" c="dimmed">
+          Per-user host extension card slotted after the role list.
+          Use this slot for app-specific identity bits — preferred
+          location, notification preferences, opt-in features.
+        </Text>
+        {me && (
+          <Text size="sm">
+            Signed in as <strong>{me.email}</strong>.
+          </Text>
+        )}
+      </Stack>
+    </Card>
+  );
+}
+
+export function __BRAND_PASCAL__ProfileItem() {
+  return (
+    <MantineProvider>
+      <QueryClientProvider client={queryClient}>
+        <AtriumProvider>
+          <__BRAND_PASCAL__ProfileItemInner />
+        </AtriumProvider>
+      </QueryClientProvider>
+    </MantineProvider>
+  );
+}