Data & storage

What the software stores

Where data comes from, where it goes, and what it means to the application.

Database state (evidenced)

Table	Role	Creation evidenced in-repo?
users	Accounts, credits, plan/admin columns	Partial (base in auth_lib; alters elsewhere; some columns missing CREATE)
credit_transactions	Purchase ledger	Yes in auth_lib (may mismatch stripe_lib inserts)
arcana_settings	Maintenance flags	Yes
arcana_renders	Finished images	Yes in helpers/generators
job_queue	Legacy/alternate queue	Yes in helpers
arcana_queue	Active generation queue	No full CREATE found
arcana_styles	Style library	No CREATE found
access_codes	Invite codes	No CREATE found
user_notifications	In-app notes	No CREATE found
stripe_products / stripe_checkout_sessions / user_subscriptions / stripe_webhook_events	Commerce	No CREATE found
admin_logs	Admin audit	Yes in admin_check
arcana_gen_sessions / attempts / events	Admin diagnostics	No CREATE found

Filesystem state

uploads/dble — full images + thumbs (+ refs/ portraits)
sample_images, backgrounds — marketing/featured assets
logs/ — referenced for Stripe webhook logs (may be runtime-created)
vendor/ — Composer dependencies when installed

Environment configuration

See .env.example for key names. Never commit real secret values.

External provider state

Stripe customers/subscriptions/sessions; B2 object versions; Gemini ephemeral model responses.

Data flow

Generation data path

``Form fields + portrait files → arcana_queue columns (band, song, lyrics, aspect_ratio, image_style, portrait URLs, watermark) → Gemini analysis JSON (ephemeral in worker; persisted on render as analysis_json) → prompt string (persisted on arcana_renders.prompt) → image bytes → uploads/dble + B2 → arcana_renders row → users.image_credits decrement → arcana_queue.status=completed + result URL``

Payment data path

``stripe_products → Checkout Session → stripe_checkout_sessions → webhook/success → credit_transactions + users.*_credits → subscriptions → user_subscriptions (+ plan_type updates where implemented)``

Which functionality touches each store

Store	Written by	Read by
`access_codes`	Account registration Administrator exceptions	Account registration Administrator exceptions
`admin_logs`	Administrator exceptions	Administrator exceptions
`arcana_queue`	Aspect-ratio selection Background render processing Image-generation form Parallel worker execution Portrait reference uploads Queue submission	Background render processing Cinematic prompt creation Dynamic band-style analysis Gemini image generation Image-generation form Parallel worker execution Queue submission Song and lyric analysis Watermark application
`arcana_renders`	Aspect-ratio selection Background render processing Gemini image generation Portrait reference uploads Render deletion Song and lyric analysis User render gallery	Administrator exceptions Gallery search, sorting, and pagination Image-generation form Image lightbox and viewer Render deletion User render gallery
`arcana_settings`	Administrator exceptions Maintenance mode	Maintenance mode
`arcana_styles`	Static visual styles	Background render processing Cinematic prompt creation Image-generation form Static visual styles
`credit_transactions`	Credit-pack purchases Stripe webhook processing	Administrator exceptions Credit-pack purchases Stripe webhook processing
`external:B2`	Background render processing Gemini image generation Render deletion Local and Backblaze B2 storage User render gallery	—
`filesystem:backgrounds`	—	Public landing page
`filesystem:sample_images`	—	Public landing page
`filesystem:uploads/dble`	Background render processing Gemini image generation Render deletion Local and Backblaze B2 storage User render gallery	—
`filesystem:uploads/dble/refs`	Portrait reference uploads	—
`stripe_checkout_sessions`	Stripe checkout	Credit-pack purchases Stripe checkout Stripe webhook processing
`stripe_products`	—	Stripe checkout Subscription plans
`user_notifications`	In-app notifications	In-app notifications
`user_subscriptions`	Stripe webhook processing Subscription plans	Subscription plans
`users`	Account profile management Account registration Administrator exceptions Background render processing Credit balances Credit-pack purchases Email verification Login and logout Password reset Stripe webhook processing User plans and feature access	Account profile management Account registration Administrator exceptions Background render processing Credit balances Email verification Image-generation form Login and logout Password reset Stripe checkout User plans and feature access