Module management 

Management & health capability: the configuration view/edit surface, the Settings page, and a health check.

Follows the plan’s “symmetry contract”: one shared, serializable DTO renders as JSON for agents (GET /api/config) and as HTML for humans (GET /settings), and the write path (PUT /api/config, POST /settings) shares one merge-and-persist function. Handlers live here; the app is assembled in crate::frontend::server.

Structs

ApiIndexDto

Discovery index of the agent API: every mounted /api/* endpoint (method, path, handler name) in a single call, so an agent can enumerate CorTeX’s machine surface without out-of-band docs. Self-describing — built by introspecting the live route table, so it never drifts.

AuthDto

Masked view of the auth settings — secrets are summarized, never exposed.

ConfigDto

A masked, serializable view of CortexConfig safe to expose over the API and UI.

ConfigFile

Managed state: the path where the write path persists the configuration file.

DatabaseDto

Masked view of the database settings — the password is never exposed.

DbHealth

Health of the database dependency.

DispatcherHealth

Reachability of the ZeroMQ dispatcher, probed by a short TCP connect to its bound ports. The frontend doesn’t otherwise speak to the dispatcher (workers do), so this is a pure liveness probe of the co-located dispatcher (localhost) — informational, it does not flip the overall status (a read-only/report-only frontend deployment legitimately runs without a dispatcher).

HealthDto

Structured health report, identical for agents and human supervisors.

LivenessDto

Minimal, public liveness projection — the open GET /healthz. Just whether the service is up and its database reachable; deliberately omits the internal topology (corpus paths, pool sizing, dispatcher ports, remediations) that HealthDto exposes. The detailed report is admin-only: the /health screen and its token-gated agent twin GET /api/health (KNOWN_ISSUES X-1).

MaintenanceAckDto

Acknowledgement for a maintenance job: the background crate::jobs handle to poll.

MigrationsHealth

Health of the schema migrations.

PoolHealth

Utilization of the web frontend’s database connection pool — a key load / saturation signal (when in_use approaches max, requests start waiting on pool.get() and may 503).

RouteInfo

One row of the mounted route surface — an endpoint’s method, URI pattern, and handler name.

RouteTable

A snapshot of the mounted route table, captured at mount time so the discovery index can never drift from the routes actually served.

SettingsForm

The editable, non-secret fields of the Settings form (database/auth are edited out-of-band).

StorageHealth

Health of the shared document storage: every corpus’s path is stat-checked on disk. Document bytes live on a shared filesystem (tasks.entry are absolute paths under each corpus.path), so a moved/unmounted data mount makes the whole conversion pipeline fail — surfaced here instead of only as mysterious cascading task failures. Informational (the frontend still serves reports from the DB), so it does not flip the overall status. Corpora with an empty path are skipped.

UnreadableCorpus

A corpus whose configured source directory could not be read on disk (missing / unmounted / wrong permissions). Its conversions and re-imports will fail until the path is restored.

Functions

analyze

Triggers a planner-statistics refresh (ANALYZE over the high-churn tables) as a background job — keeps the planner’s row estimates current after bulk imports/reruns so it keeps choosing the right indexes (e.g. the TODO leasing index) instead of waiting for autovacuum (DB ongoing-maintenance; docs/DB_TUNING.md). Token-gated; returns 202 + the job handle, poll GET /api/jobs/<job> for per-table progress. Debounced.

analyze_human

The human twin of analyze: the health screen’s “Refresh planner statistics” button. Gated by the signed-in AdminSession cookie (anonymous → sign-in). Spawns the same debounced analyze job and redirects to /jobs.

api_config

The effective configuration, masked for safe exposure (the agent twin of the Settings screen). Token-gated via the Actor guard (clean 401 without a token), matching the human /settings (require_admin) and the write twin PUT /api/config — config is admin-only on every surface. Secrets are masked regardless (DB password → ***, only the token count is shown), but the operational config (DB host/user/name, ports, pool/queue tuning) is not for anonymous eyes.

api_health

Detailed health report for agents — the token-gated JSON twin of the admin health_page screen (sharing HealthDto). Gated by the Actor guard (clean 401 without a token) so the internal topology it exposes (corpus paths, pool sizing, dispatcher ports) isn’t world-readable like the open /healthz once was (KNOWN_ISSUES X-1).

api_index

GET /api — the agent-API discovery index (see ApiIndexDto).

health_page

The human health screen: the HTML twin of GET /api/health, sharing HealthDto — database reachability, migration currency, and live connection-pool utilization at a glance. Signed-in admins only (unauthenticated → sign-in page); the public /healthz JSON probe stays open for liveness, but the detailed view is admin/token-gated.

healthz

Public liveness probe — minimal by design (KNOWN_ISSUES X-1): {status, database.reachable} only, safe to expose unauthenticated at the edge for load balancers and agents. The detailed report (pool, dispatcher ports, corpus storage, remediations) is admin-only: the /health screen and its token-gated agent twin api_health (GET /api/health).

post_settings

Human write path: a native form POST from the Settings page; persists, then redirects back. Gated by the signed-in AdminSession cookie (the Settings screen is signed-in-only; anonymous → sign-in).

put_config

Agent write path: deep-merge a partial config patch, persist it, and return the masked result. Token-gated via the Actor guard — rewriting the running configuration (dispatcher ports, queue/result sizes, asset dirs, the job stall threshold) is a consequential mutation, so it requires a valid X-Cortex-Token exactly like every other agent write (the human twin post_settings is AdminSession-gated). 401 without a token.

reindex

Triggers an online index rebuild (REINDEX (CONCURRENTLY) over the high-churn tables) as a background job — index bloat slows scans over time, and this rebuilds without an exclusive lock (DB ongoing-maintenance; docs/DB_TUNING.md). Token-gated; returns 202 + the job handle, poll GET /api/jobs/<job> for per-table progress. Debounced.

reindex_human

The human twin of reindex: the health screen’s “Reindex database now” button. Gated by the signed-in AdminSession cookie (the health screen is itself signed-in-only; anonymous → sign-in). Spawns the same debounced reindex job and redirects to /jobs.

routes

The route set for the management/health/settings capability.

settings

The Settings page: the human (HTML) twin of GET /api/config. Signed-in admins only (unauthenticated → sign-in page); the agent twin keeps the token guard.