The files worth understanding

Core auth, PDO, schema helpers, credits, settings, CSRF/session utilities.

Runs when

Included by nearly all authenticated flows.

Implements

Login and logout Account registration Credit balances Maintenance mode

Depends on

config/load_env.php

Depended on by

auth_check.php; Most arcana.*.php pages

Test after change

Login, register, credit check/consume, maintenance flag.

Require login and honor maintenance mode.

Runs when

Included by protected pages.

Implements

Login and logout Maintenance mode

Depends on

auth_lib.php

Depended on by

Generator, gallery, dashboard, queue submit

Test after change

Hit a protected page logged out and in maintenance.

Primary user-facing generation UI and queue enqueue.

Runs when

User opens/submits generator.

Implements

Image-generation form Queue submission Portrait reference uploads Aspect-ratio selection

Depends on

auth_check.php arcana.plan_tiers.php

Depended on by

End-user generation experience

Test after change

Enqueue a job with and without portraits/styles; confirm JSON + queue row.

Best-evidence current worker: parallel Gemini, styles, retries, credits, notifications.

Runs when

Cron/CLI execution.

Implements

Background render processing Song and lyric analysis Gemini image generation Retry and fallback behavior Dynamic band-style analysis

Depends on

auth_lib.php includes/b2_helpers.php

Depended on by

Completed renders

Test after change

Process a pending queue row end-to-end; verify credit and gallery.

User gallery browse/search/sort/paginate/email/delete.

Runs when

User visits gallery.

Implements

User render gallery Gallery search, sorting, and pagination Render deletion Image lightbox and viewer

Depends on

auth_check.php includes/b2_helpers.php

Depended on by

Post-generation UX

Test after change

List, search, delete, email a render.

Normalize plan_type into capability flags.

Runs when

Generator and other gated UIs.

Implements

User plans and feature access

Depended on by

arcana.image.generator.php

Test after change

Check flags for apprentice/starter/creator users.

Stripe SDK helpers for products, checkout, webhooks, credit grants.

Runs when

Pricing, webhooks, subscription pages.

Implements

Stripe checkout Stripe webhook processing Credit-pack purchases Subscription plans

Depends on

vendor/autoload.php .env

Depended on by

arcana.pricing.php; arcana.stripe.endpoint.php

Test after change

Create checkout session in test mode; process a test webhook.

Lightweight Stripe webhook for checkout session credit grants.

Runs when

Stripe POSTs to this URL if configured.

Implements

Stripe webhook processing Credit-pack purchases

Depends on

auth_lib.php

Depended on by

Credit pack fulfillment (if this endpoint is live)

Test after change

Signed test event grants credits once.

Backblaze B2 upload/delete/public URL helpers.

Runs when

Worker save and gallery/admin URL/delete paths.

Implements

Local and Backblaze B2 storage

Depends on

config/backblaze.php

Depended on by

Workers; Gallery

Test after change

Upload and delete a test object; resolve a public URL.

Admin gate and admin schema/logging bootstrap.

Runs when

Any admin page.

Implements

Administrator exceptions

Depends on

auth_lib.php

Depended on by

arcana.admin/*

Test after change

Non-admin denied; admin allowed.

Load .env key/value pairs into environment.

Runs when

Included by pages that need config.

Depends on

.env

Depended on by

Auth DB connect paths; integrations

Test after change

Confirm keys present without exposing values.

Public marketing landing with mobile redirect.

Runs when

Anonymous visitors hit site root.

Implements

Public landing page

Depended on by

Marketing acquisition

Test after change

Load desktop and mobile UA.

Documents required environment key names without secrets.

Runs when

Operator setup.

Depended on by

Deployment

Test after change

Ensure no real secrets were added.

Sequential/manual queue processor variant.

Runs when

Manual or legacy cron.

Implements

Background render processing Retry and fallback behavior

Depends on

auth_lib.php

Depended on by

Legacy ops paths

Test after change

Process one pending job.

Alternate/duplicate login entry point used by auth_check default redirect.

Runs when

Redirect from auth_check or direct visit.

Implements

Login and logout

Depends on

auth_lib.php

Depended on by

auth_check.php

Test after change

Login via both login.php and arcana.login.php.