0.2.x-AdminInterfaceSetupUi.md

Admin interface and setup UI (Feature Draft)

Status: Draft
Updated: 2026-06-05 Owner: Core
Purpose: Draft for the first usable admin interface, graphical setup routine, login flow, and core management screens.

Overview

• Defines the first web UI that makes the CMS installable, configurable, and usable by administrators.
• Covers setup, login, dashboard, navigation, content management, settings, user/account basics, and system states.
• Depends on setup automation, error handling, system theme/design system, content model, and security/ACL baseline.
• Provides the product shell that later schema, editor, package, API, backup, import/export, and update features plug into.

Outline

A functional CMS release needs a web interface, not just console commands and data models. The first admin interface should provide the minimum complete product shell: setup wizard, login/logout, protected admin layout, dashboard, content overview, package and theme management entry points, settings entry points, account controls, and clear system-state pages.

The graphical setup routine should share validation and service behavior with bin/setup. It should not be a separate installer logic path. The web setup should guide the user through environment checks, dependency state, database configuration, site metadata, admin user creation, hash-salt generation, and final lock/complete state.

The admin shell should be built in vertical slices. Each screen should be useful on its own, use shared system UI components, and respect permissions from the beginning. Empty states and recovery flows are part of the first usable experience, not polish for later.

Admin settings should stay consolidated. The first settings navigation should use focused sections such as General, Dashboard, Users, Mail, Security, Packages, Scheduler, and later Maintenance. Active packages with simple setting definitions should add package sections under Settings > Packages instead of filling the top-level admin navigation. Security may include captcha, logging/security diagnostics, GeoIP settings, and other abuse-control settings. User-owned settings such as scoped API tokens belong in the profile/account area, not global settings.

The first admin shell should expose administrative placeholders before content-management views are filled in. Dashboard, Package Management, Theme Management, User Management, Scheduler, Backups, Logs, and Settings belong to the Admin area. Content lists, schemas, media editing, import/export, and other authoring workflows belong to the Editor area unless a later draft explicitly promotes a system-level administrative slice.

Technical Specifications

• Provide a graphical setup wizard that uses the same validation and configuration services as CLI setup.
• Setup wizard steps should cover:
  • Environment/dependency checks.
  • Database configuration and connection validation.
  • Application/site metadata.
  • First admin account creation.
  • Hash-salt/APP_SECRET generation and persistence.
  • Migration/setup execution status.
  • Completion and setup lock state.
• Provide login, logout, password reset/recovery entry points where supported by the security draft.
• Provide an admin shell with global navigation, breadcrumbs or page context, user menu, status/flash area, and permission-aware navigation items.
• Provide a dashboard with system status, content summary, recent activity, and actionable setup warnings.
• Provide admin settings sections for General, Dashboard, Users, Mail, Security, Packages, and Scheduler, with Maintenance added when operational maintenance settings are implemented.
• Build core settings and package settings through shared typed form definitions and submission handling: field name, label key, default value, value type, input type, option list, validation metadata, optional help metadata, CSRF protection, typed casting, and translated validation feedback.
• Provide package settings sections under Admin Settings for active packages that expose simple typed setting definitions.
• Render simple package settings through the native settings form layer. Packages that need more than typed key/default/option metadata should provide dedicated admin/editor views outside Settings.
• Keep user-specific API token management in user profile/account settings rather than global admin settings.
• Provide first management screens:
  • Content list and content detail entry point.
  • Schema/preset overview entry point once schema features exist.
  • Package overview entry point with discovered inactive packages, scopes, active state, explicit activation, and rebuild-assets action.
  • Theme management entry point for theme selection, activation, previews, and variants.
  • User/account and ACL entry points.
  • Scheduler overview entry point for scheduled administrative jobs.
  • Backup and restore entry point for operational recovery workflows.
  • Logs/audit entry point for operational and security-relevant diagnostics.
  • Settings entry point.
• Provide safe system-state pages for setup required, setup complete, setup locked, maintenance/update, access denied, not found, and server error states.
• Use the shared operational action-log shell for setup execution, migration application, dependency checks, asset rebuilds, and other long-running setup/admin actions.
• Provide a manual rebuild-assets admin action that runs assets:rebuild, the same ActionLog-backed package asset mirror, registry rewrite, Tailwind, production-only AssetMapper compilation, and final cache-clear sequence used by package lifecycle workflows.
• Use Symfony Forms, Validator, CSRF protection, voters, translations, Twig, AssetMapper, Tailwind, and Stimulus.
• Preserve form input and show actionable validation feedback.
• Keep destructive actions behind confirmation and, where needed, dry-run/review screens.
• Keep the admin interface extensible through documented navigation, dashboard, action, and form-section extension points.

Testing & Validation

• Functional-test setup wizard steps, validation failures, completion, and lock behavior.
• Test CLI setup and web setup share validation behavior.
• Test login/logout and protected admin access.
• Test permission-aware navigation hides or disables forbidden actions.
• Test admin shell renders translated navigation, empty states, flashes, and validation errors.
• Test settings navigation exposes only the first consolidated settings sections.
• Test active package settings appear below Admin Settings and are not exposed when the package is inactive.
• Test user-specific API token management is not exposed as a global admin setting.
• Test package overview screens show discovered packages as inactive until explicitly activated.
• Test manual rebuild-assets action is permission-protected and uses the shared action-log shell.
• Test setup and admin routes with php bin/console render:route /<route> once available.
• Run .codex/compare_translations.php after UI copy changes.

Implementation Notes

• Decision recorded: Web setup is a graphical wrapper around shared setup services, not a separate installer implementation.
• Decision recorded: The setup UI should now become a multi-step wizard: landing/language, preflight, site metadata, database connection, first OWNER account, review, execution log, and failure/success states.
• Decision recorded: The wizard must keep all submitted values available across step navigation. Completed steps remain editable, future steps stay locked until required earlier input is present and locally valid, and changing an earlier step can invalidate later readiness without discarding the user's typed values.
• Decision recorded: The setup UI must not touch Doctrine/ORM before the final runner step. Preflight and wizard forms should use filesystem, environment, PHP extension, webroot, and process checks only.
• Decision recorded: Database configuration is driver-aware. SQLite should favor the generated project-local URL and show a caution for custom URLs; server databases should expose structured connection fields and optional table prefix support through APP_DATABASE_PREFIX, which is applied centrally by Doctrine/DBAL during setup and runtime.
• Decision recorded: The site-information step should render modular DB-free setup field definitions so seed-backed settings, starting with registration mode and access-statistics policy, can be extended later without turning the wizard into a monolithic controller/template.
• Decision recorded: Setup execution should render structured ActionLog progress with individual runner steps and route recoverable errors back to the relevant wizard step. Successful setup redirects or offers a start-page action after APP_SETUP_COMPLETED is written.
• Decision recorded: The first admin release needs a minimal but complete product shell before advanced features can be considered usable.
• Decision recorded: Admin navigation and dashboard contributions are extension points only when documented.
• Decision recorded: Graphical setup and admin operations should show structured action logs for larger actions instead of relying only on loading indicators.
• Decision recorded: Package discovery screens show new packages as inactive by default and require explicit activation.
• Decision recorded: Admin UI includes a manual rebuild-assets action for recovery and diagnostics.
• Decision recorded: First admin settings sections are General, Dashboard, Users, Mail, Security, Packages, and Scheduler. User-specific API tokens belong in profile/account settings.
• Decision recorded: Simple package settings live below Admin Settings through a core-rendered settings layer. More complex package workflows should use dedicated package views outside Settings.
• Decision recorded: The package settings branch uses /admin/settings/packages as an overview and /admin/settings/packages/{package-slug} for package-specific pages. Package labels come from package metadata, but route paths use package slugs to avoid collisions with core settings sections.
• Decision recorded: Admin Settings forms are generated and submitted through shared form definitions so core settings and package settings use the same renderer-neutral field model, typed casting, validation feedback, and persistence adapters. Captcha fields render through the provider namespace for future captcha-provider packages.
• Decision recorded: The Admin area gets placeholders for package management, theme management, user/ACL management, scheduler, backups, logs, and settings; content, schema, media, and import/export workflows remain Editor concerns.
• Decision recorded: Admin controllers should stay thin HTTP adapters. Workflow logic belongs in application services, while read-heavy screens should use separate query/filter/read-model/view-factory layers.
• Decision recorded: Package lifecycle and other admin action services should be separated from admin read-model composition so future API endpoints and Admin UI screens do not depend on template-specific array contracts.
• Decision recorded: Admin diagnostics may include detailed exports for administrators or owners only when strongly redacted. Raw secrets, full environment dumps, cookies, request payloads, and protected configuration values remain excluded.
• Open: Decide the first dashboard widgets and the minimum account/password recovery flow during the security baseline implementation.