#Working on the panel
The panel is one FastAPI application with Jinja2 templates and a small ES-module front end. This page is the map: where a page, a component and a task action go, and what the surrounding conventions expect.
#Layout
app/modules/web_admin/├── app.py create_app: middleware, routers, exception pages├── cli.py aegis web-admin setup|start|stop|restart|status|passwd├── db.py the panel SQLite database and its migrations├── paths.py templates, assets, brand, logs├── templating.py Jinja environment, navigation, render()├── auth/ accounts, sessions, guard.require_user├── routes/ one module per section, HTML and JSON├── services/ what the routes read: views, settings, collectors└── templates/ layouts, sections, partialspublic/assets/web-admin/├── js/app.js registers every component and starts the app├── js/core/ component base, http, live feed, store, router├── js/components/ one file per behaviour├── css/app.css prebuilt stylesheet (shipped)└── src/app.css the same rules, for the build on a dev machine#A page
routes/<section>.py: router = APIRouter() @router.get("/ftp/users") def users_page(request: Request, user=Depends(guard.require_user)): """Every virtual user with its FTP root.""" config = request.app.state.config return templating.render( request, "ftp/users.html", title="FTP Manager · Users", user=user, active="ftp", section="users", page=_page(config), )app.py imports it (from .routes import ftp as ftp_routes) and includes it(app.include_router(ftp_routes.router)); a JSON router is included as ftp_routes.api. routes/__init__.py lists the package members, but the include list is explicit, so a new module is one import and one line there.
templates/<section>/<page>.html extends layout.html (ormanagement/layout.html) and fills {% block content %} / {% block section %}.
templating.render builds the shared context — request, user, title, active, asset, theme, sidebar — and passes the rest through. The environment uses StrictUndefined: a template that reads a key nobody passed is an error, not a blank spot, so every new page has to pass what it shows.
active matches a key in NAV (templating.py) and decides which sidebar item is highlighted; section is the key of the tab inside a section.
Partials worth knowing (templates/partials/section.html): section_header, section_tabs, flash. Every page shows message and error from the query string through flash.
#A write
A route never changes the host. It validates what it can, queues a task, and redirects:
from .queue import queue_taskfrom .web_common import back, back_to@router.post("/mail/aliases")async def alias_add(request: Request, user=Depends(guard.require_user)): form = dict(await request.form()) source = str(form.get("source") or "").strip() task_id = await queue_task( name=f"add alias {source or '(unnamed)'}", action="mail.alias.add", args={"source": source, "destination": str(form.get("destination") or "")}, actor=user.username, resource=f"mail:alias:{source}", group="mail", ) return back(back_to(form, "/mail/domains"), f"task {task_id} queued")queue_task creates the row in the tasker database and returns its id.group is the section (web, mail, dns, ftp, database, sys).resource says what is touched; two tasks on the same resource still run oneat a time because a worker owns one root, but it also makes the queue readable.
back(url, message, error=False) answers 303 with ?ok= or ?error=;back_to(form, default) keeps the operator on the page that opened the form, accepting only paths inside the same section.
The action itself lives in app/modules/tasker/actions/<area>.py and is registered with @registry.action("mail.alias.add"). It receives (context, args) and returns success, failure or partial from app/helpers/result.py. New action module → import it in app/modules/tasker/actions/__init__.py → restart the tasker.
A read-only button (Check, Preview) stays inline: it changes nothing, so it answers in the request with run_in_threadpool around the blocking call.
#A component
import { Component } from "../core/component.js";export class Thing extends Component { mount() { this.delegate("click", "[data-thing-action]", (event, button) => this.run(button), ); } async run(button) { button.disabled = true; try { const result = await this.http.post("/api/thing/apply", {}); this.app.toast(result.detail || "done"); } catch (error) { this.app.toast(error.body?.error || error.message, "error"); } }}Register it once in js/app.js with the selector it mounts on:
.component("thing", Thing, "[data-thing]")What the base class gives you: this.el, this.app, this.http (get, post, put, del), this.listen(...) and this.delegate(...) — both removed on unmount — this.bus, this.store, and this.app.liveFeed() for WebSocket topics.
Rules that keep the panel predictable:
<script> and no onclick; behaviour is a component, wired throughdata attributes;
textContent (or escape intasker.js) — logs, URIs and user agents are attacker-controlled;
data-confirm, data-confirm-title,data-confirm-action and optionally data-confirm-tone (the confirm component owns the dialog);
unmount().#Styles
css/app.css is compiled elsewhere and shipped: a utility class that is not already in that file does nothing. When a rule is missing, add plain CSS to both css/app.css and src/app.css — they are kept in step by hand — and prefer the existing variables (--ag-ink, --ag-muted, --ag-line, --ag-surface, --ag-panel, --ag-accent).
#The panel database
aegis.db holds accounts, sessions and preferences. Schema changes are .sql files under database/migrations/core/aegis, applied once and recorded in schema_migrations. db.ensure() runs at start-up; a service that needs a table calls it before its first query, exactly like the tasker does.
#Checklist
print — output goes through app/helpers/cli;aegis web-admin restart after a change; `Management → Tasker → Restarttasker` when an action was added or renamed.