Amvionlie CMS
Advanced
Where the Future Begins

Admin Addon View Developer Contract

This page defines how addon Admin routes mount into the protected Admin surface.

Related pages: Addon Development/Admin Routes, Admin UI/Admin Cleanup Implementation Contract, Admin UI/Admin Form Actions Permissions and CSRF Rules.

Purpose

This document defines what third-party and first-party addon developers must provide when building Admin-side views for Amvionlie.

It exists so addon developers can build Admin views that mount into the shared Admin surface without inventing a separate admin application.

Core Rule

Addon Admin views are managed inner views.

They are not standalone Admin shells.

admin/ owns:

  • shell frame
  • header
  • sidebar/navigation frame
  • footer when present
  • shared asset loading rules
  • shared page panel structure
  • shared list behavior
  • shared form rhythm
  • shared notices
  • shared modal frame
  • shared fragment rendering rules

Addons own:

  • route-specific data loading
  • permission declarations
  • permission checks for their workflow
  • columns
  • fields
  • validation
  • mutations
  • domain actions
  • advanced/developer details when needed

An addon may not replace the Admin shell because its workflow is unique.

Admin Route Types

Addon Admin routes should fall into one of these route types:

  • list route
  • create route
  • edit route
  • detail route
  • action route
  • fragment route
  • modal route
  • developer/diagnostic route

Normal list, create, edit, and detail routes must render into the shared Admin template.

Action routes should process a mutation and redirect back to an owning list, create, edit, or detail route.

Fragment and modal routes must return content intended for the shared Admin fragment/modal frame, not a full page shell.

Developer/diagnostic routes may show technical data, but must be clearly separated from normal user workflows.

Full Page Response Contract

A normal addon Admin full-page route should provide:

  • page title
  • breadcrumb data
  • task panel eyebrow
  • task panel title
  • notice data
  • primary content
  • optional Advanced/developer content

It must not emit:

  • a second Admin shell
  • duplicate header/navigation/footer markup
  • full document markup such as <!doctype html>, <html>, <head>, or <body>
  • global Admin asset tags
  • local copies of shared toolbar, pagination, notice, modal, or state badge behavior when a shared pattern exists

Fragment Response Contract

A fragment route returns only the content fragment requested by the Admin shell or shared component.

Fragments must not include:

  • Admin shell wrapper
  • global navigation
  • global header
  • full page panel unless the fragment specifically represents a panel body
  • unrelated scripts or styles

Fragment routes must still enforce permissions and CSRF rules when they read protected data or mutate state.

Modal Response Contract

A modal route supplies modal body content and required modal metadata.

The shared Admin modal frame owns:

  • overlay
  • panel surface
  • title placement
  • close behavior
  • theme colors
  • contrast
  • spacing rhythm

Addon modal content may vary by workflow, but it must not create a local modal shell when the shared Admin modal frame can support the workflow.

List Route Contract

A list route must:

  • render records only
  • use the shared list layout
  • use the shared toolbar order
  • use the shared query keys
  • preserve list state
  • use shared pagination
  • use shared sort indicators
  • use shared state markers when lifecycle state exists
  • keep developer identifiers out of normal row titles

The normal query keys are:

  • q
  • page
  • per_page
  • sort
  • dir

Filter keys must be stable lowercase snake_case names.

Create Route Contract

A create route must:

  • create one new record
  • use the shared form panel structure
  • include CSRF protection
  • validate input before mutation
  • show validation errors in the shared notice/error pattern
  • redirect after successful POST
  • preserve the owning list return state when possible

Create routes must not be embedded inside normal list pages.

Edit Route Contract

An edit route must:

  • edit one existing record
  • load by the governed identifier expected by the addon
  • verify permission before showing the form
  • include CSRF protection
  • validate input before mutation
  • redirect after successful POST
  • preserve the owning list return state when possible

Edit routes must not expose raw database identifiers, UUIDs, slugs, manifests, or filesystem paths unless the view is explicitly a developer surface.

Action Route Contract

An action route performs a mutation such as:

  • delete
  • archive
  • activate
  • disable
  • show
  • hide
  • publish
  • unpublish
  • reorder

Action routes must:

  • require POST unless the action is explicitly safe and read-only
  • validate CSRF
  • recheck permission server-side
  • validate selected rows or target identifiers
  • reject unsupported actions
  • redirect after completion
  • write a notice for success, warning, or error

Action labels must match the real lifecycle meaning.

Do not use Publish as a generic synonym for enable, activate, show, or make available.

Permission Contract

Addon Admin routes must enforce permissions before protected data or actions are exposed.

UI disabling is not security.

Every mutation handler must recheck permission server-side.

Normal permission behavior:

  • list route checks view permission
  • create route checks create permission
  • edit route checks update permission
  • delete route checks delete permission
  • lifecycle action route checks the matching declared permission
  • developer/diagnostic route checks developer/admin permission

Current Drift and Intended Rule

The final intended rule is that addon Admin routes use central Admin helpers or templates for shell mounting, list rendering, forms, notices, state markers, pagination, modals, and fragments.

If the helper does not exist yet, implementers must still match the documented visible and behavioral contract.

When two or more addons need the same helper, the shared Admin layer should be improved instead of copying local implementations between addons.

Review Checklist

Before an addon Admin view is accepted:

  • the route type is clear
  • full-page routes do not include a duplicate Admin shell
  • fragment routes return fragments only
  • modal routes use the shared modal frame
  • list routes use shared query keys
  • create and edit are separate from list
  • POST routes validate CSRF
  • mutation routes recheck permission server-side
  • successful mutations redirect after POST
  • notices use the shared placement
  • normal views do not expose developer data by default
  • action labels match actual lifecycle behavior

Final Rule

Addon developers supply the Admin work.

The Admin layer supplies the governed Admin shape.

Updated: 2026-05-03 17:36:20

Backlinks