Architecture Diagrams

These diagrams are the source-of-truth architecture views for docs. Keep them exact and update them with code changes. Flux-generated companion images can sit near these diagrams, but Mermaid should remain the precise reference.

Package Boot Lifecycle

flowchart TD
    Composer["Composer install/update"] --> ProviderDiscovery["Laravel provider discovery"]
    Composer --> Manifest["capell.json manifest"]
    Manifest --> PackageRegistry["CapellPackageRegistry"]
    PackageRegistry --> RuntimeContext["RuntimeContextResolver"]
    RuntimeContext --> Install["Install context"]
    RuntimeContext --> Runtime["Runtime context"]
    RuntimeContext --> Admin["Admin context"]
    RuntimeContext --> Frontend["Frontend context"]
    Install --> InstallWork["Migrations, setup Actions, install commands"]
    Runtime --> RuntimeWork["Settings, package metadata, subscribers, models"]
    Admin --> AdminWork["AdminBridge, Filament, extenders"]
    Frontend --> FrontendWork["Routes, hooks, assets, cache invalidation"]

Admin Extender Resolution

flowchart LR
    PackageProvider["Package provider"] --> AdminBridge["AdminBridge"]
    PackageProvider --> TaggedExtenders["Tagged extenders"]
    AdminBridge --> Registrar["AdminBridgeRegistrar"]
    Registrar --> SurfaceRegistry["AdminSurfaceContributionRegistry"]
    TaggedExtenders --> Resolvers["Schema/action/table resolvers"]
    SurfaceRegistry --> Panel["CapellAdminPlugin"]
    Resolvers --> Filament["Filament resources/pages/widgets"]
    Panel --> Filament

Frontend Public Render And Cache

flowchart TD
    Request["Public request"] --> Site["Site/domain resolution"]
    Site --> Language["Language resolution"]
    Language --> Page["Page URL resolution"]
    Page --> Hydration["Hydrated render payload"]
    Hydration --> Components["Components, hooks, media, assets"]
    Components --> Safety["Public HTML safety inspection"]
    Safety --> CacheDecision{"Safe to cache?"}
    CacheDecision -->|yes| Cache["Page/static/cache response"]
    CacheDecision -->|no| Bypass["Uncached response with bypass reason"]

Marketplace Trust Flow

sequenceDiagram
    participant Admin
    participant CMS as Capell CMS
    participant App as Capell App
    participant Public as Public Host

    Admin->>CMS: Start account connection
    CMS->>App: Create connection session
    App-->>Admin: Approval URL
    Admin->>App: Approve account/site
    App->>CMS: Callback with code and state
    CMS->>App: Exchange code
    App-->>CMS: Instance ID and signing secret
    Admin->>CMS: Start domain verification
    CMS->>Public: Write .well-known challenge
    CMS->>App: Verify registration session
    App->>Public: Fetch challenge URL
    App-->>CMS: Verified domain

Installer Browser Flow

flowchart TD
    Open["Open /install"] --> PageData["BuildInstallerPageDataAction"]
    PageData --> Form["Installer form"]
    Form --> Validate["InstallController validates input"]
    Validate --> Preflight["InstallerPreflight"]
    Preflight --> Decision{"Blocking failure?"}
    Decision -->|yes| Report["Show remediation and report"]
    Decision -->|no| Plan["Build install plan"]
    Plan --> Step["RunInstallStepAction"]
    Step --> Progress["Cache/File progress reporters"]
    Progress --> More{"More steps?"}
    More -->|yes| Step
    More -->|no| Success["Success page and optional installer removal"]

Public Output Safety Boundary

flowchart LR
    AdminPage["Filament admin"] --> Beacon["Authenticated authoring beacon"]
    PublicPage["Public HTML"] --> Visitor["Anonymous/non-admin visitor"]
    PublicPage --> Cache["HTML/static cache/CDN"]
    Beacon --> AdminOnly["Admin-only edit controls"]
    AdminOnly -. "never cached" .-> Cache

Flux Companion Asset Plan

The FLUX.2 connector is intended for visual companion diagrams, not exact API references. Generate assets under docs/images/diagrams/ when the FLUX connector is authenticated:

Asset	Use beside
package-boot-lifecycle.png	Package boot lifecycle
admin-extender-resolution.png	Admin debugging
frontend-public-render-cache.png	Frontend debugging
marketplace-trust-flow.png	Marketplace debugging
installer-browser-flow.png	Installer overview

Keep generated text minimal. Use the Mermaid diagrams for exact symbols.