Files
devplacepy/devplacepy/routers/admin/CLAUDE.md
T
retoorandClaude Sonnet 5.5 1a9201cb91 Admin pages: one shared specification, builders, fragments, caps and live refresh
Adds admin_sections registry, shared admin partials, WorkspaceList, admin CLAUDE.md spec,
capped node/flag listings, and api/unit tests enforcing the spec.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-15 01:50:50 +01:00

8.2 KiB

CLAUDE.md

The specification every /admin page follows. Claude Code loads it whenever a file under routers/admin/ is touched; the root, routers/, templates/, static/js/ and static/css/ CLAUDE.md files point here. A page that breaks a rule below is a defect, not a style choice. tests/unit/admin_spec.py enforces the mechanical rules (A1, A2, A5, A6, A7, A9, A10) against the real templates and routers, so a violation fails the suite.

Code references: the section registry is devplacepy/admin_sections.py; the caps and floors are ADMIN_LIST_CAP and ADMIN_POLL_FLOOR_SECONDS in routers/admin/_shared.py; the cap note is templates/_admin_cap_note.html.

A1. Backend rendered, always

A GET of an admin page returns the complete content in the HTML: every table, card, key figure, tab label and empty state is rendered by Jinja from data the handler computed. A placeholder such as "Loading..." in a template is forbidden. The page must be readable and correct with JavaScript off.

JavaScript only enhances: live refresh, charts drawn on a <canvas>, sorting, modals. The numbers and tables around a chart are server rendered; the chart is drawn from JSON embedded in the page.

The only permitted live-first surface is a page whose whole purpose is a live channel (WebSocket) such as the Bot Monitor and the container terminal, and even those render their initial frame on the server.

A2. One handler, one builder, one model

  • The HTML route calls respond(request, "<template>.html", ctx, model=XOut) with base_seo_context(..., robots="noindex,nofollow") and a breadcrumb trail Home > Admin > <Page>. Never templates.TemplateResponse directly: that drops the JSON face and the *Out schema.
  • The data the page shows is produced by ONE builder function. The HTML route and the refresh endpoint (GET /admin/<page>/data, require_admin, JSONResponse) both call it. The two must never compute the same figures twice with different code.
  • Context keys never collide with a Jinja global (root rule: viewer_is_admin, not is_admin).
  • Every admin page sets "admin_section": "<key>" where the key exists in ADMIN_SECTIONS.

A3. Page anatomy

Every page extends admin_base.html and, in this order, renders:

  1. <div class="admin-toolbar"> holding the page title as <h2> (never <h1>; the layout owns the document heading), then admin-count spans, filters and the primary action.
  2. Optional <nav class="admin-tabs" data-overflow-tabs> for page tabs. A tab is a real link (?tab=), rendered on the server.
  3. The content: admin-table-wrap > table.admin-table, or cards, or a form admin-settings-form.
  4. The empty state: <p class="admin-empty">, never empty-state, never an empty table.
  5. Pagination via _pagination.html when the list is paged (A6).

Tables carry <caption class="sr-only">, every <th> has scope="col", every icon-only or repeated row button has an aria-label. Page CSS goes in {% block extra_head %} after {{ super() }} (never re-link admin.css or sidebar.css; admin_base.html already loads them). No inline <style>, no style= attributes, no inline event handlers.

A4. Class vocabulary

Buttons are admin-btn with admin-btn-primary, admin-btn-danger, admin-btn-sm. Fields are admin-field, selects admin-select, forms admin-settings-form or admin-inline-form, hints admin-hint. Status chips reuse the page family badge (service-status, cm-badge, workspace-badge). The public-site classes btn, btn-primary, btn-danger, hint-text, empty-state, admin-header are forbidden in admin templates. A missing admin class is added to admin.css, never worked around with a public class. Destructive buttons carry data-confirm (and data-confirm-danger for role/quota style changes).

A5. Time

Every instant shown to a viewer is local_dt(iso, mode) or dt_ago(iso); never format_date/time_ago for an instant (those stay for JSON and non-timestamp date fields). When client JS re-renders a row it emits the same <time data-dt="..."> markup, and LocalTime localizes it through its MutationObserver; JS never formats an instant itself with toLocaleString/toLocaleTimeString.

A6. Everything is capped

No list is unbounded.

  • A list that can grow with users or content is paginated: build_pagination(page, total) plus _limit/_offset in the query and _pagination.html. Sorting is in SQL (order_by), never rows.sort() over the whole table.
  • A list that is naturally small (services, gateway providers) still reads with _limit=ADMIN_LIST_CAP and renders _admin_cap_note.html (_shown, _total) so truncation is visible, never silent.
  • Per-row work (queries, awaits, service calls) is done for the visible page only, in batch (get_users_by_uids and friends), never per row of the whole table.
  • Query parameters that size a computation (hours, top_n, limit) are clamped on the server to a declared constant.

A7. Heavy and remote work

A GET handler must not wait on a remote service. Gitea, providers and any network call go through a cache with a fixed TTL and a hard item cap; the handler renders the cached value at once and keeps the page's explicit error state (*_error) when the source is down. A computation costing more than one page of plain queries (statistics, usage analytics) is computed once per request: the HTML route embeds its result, and a tab or window change either navigates (server render) or fetches /data, never both.

A8. Live refresh

  • The shared Poller only: new Poller(fn, ms, { pauseHidden: true, immediate: false }). immediate: false because the first paint is already on the page (A1). Raw setInterval is forbidden.
  • Interval floor is ADMIN_POLL_FLOOR_SECONDS (15 s); a page that needs faster is a live channel.
  • Fetch through Http.getJson; never a bare fetch.
  • The refresh response is the /data JSON of A2, or, for a page made of server-rendered sections, HTML fetched with Http.getHtml (the page itself, or a /fragment route returning the same partial) and swapped into the [data-live] regions (Backups, Community pages, AI usage, Gateway stats). The markup then lives only in Jinja and the one builder feeds the page, the fragment and /data. The client re-renders only the regions that changed and preserves open modals, focus, scroll position and input values.
  • Initial data for charts is embedded as <script type="application/json" id="<root>-initial">{{ initial | tojson }}</script> and read synchronously; the client does not issue a second request to learn what the server already knew.

A9. Assets

  • One copy of each vendored library. Chart.js is /static/vendor/chartjs/chart.umd.min.js, loaded with defer through static_url(...) from {% block extra_js %} only on pages that draw charts.
  • Page JS is one ES6 module per class in static/js/, started from a three-line module block in extra_js. No page logic inline.

A10. Navigation is one registry

The admin sections are declared once in devplacepy/admin_sections.py (ADMIN_SECTIONS, exposed as the admin_sections Jinja global). admin_base.html (desktop sidebar) and the admin block of base.html (the phone menu, because the sidebar is hidden at 1024 px and below) both loop over it. A new admin page adds one registry entry and nothing else; hand-writing a nav link in either template is forbidden. Every admin_section value passed by a route must exist in the registry.

A11. Responsive

Everything works at 360 px. Tables sit in admin-table-wrap (horizontal scroll inside the wrap, never the page). A toolbar with more than three controls wraps; a button group of more than three becomes a <select> or a dp-action-menu. Touch targets are at least 44 px (admin.css already enforces it for admin-btn/admin-select).

Checklist for a new or changed admin page

  1. Registry entry in ADMIN_SECTIONS, admin_section matches.
  2. Builder function, respond(... model=XOut), /data endpoint if it refreshes, audit event for every mutation.
  3. Template follows A3, A4, A5; no placeholder text; caps and pagination per A6.
  4. JS (only if needed) per A8 and A9.
  5. tests/api/admin/... asserts the first response already contains the data (not "Loading"), and tests/unit/admin_spec.py still passes.