VibeKB AI Saga Arcana

Generated output — this is a static snapshot rendered from .vibekb/. The .vibekb/ content is the source of truth. See Reference for provenance.

Diagrams

Diagrams

Source-grounded visual maps of what the software is doing. Each diagram explains what you are seeing, how it was verified, and what remains uncertain — and links back to the functionality and warnings it relates to.

Diagrams never claim behaviour that has not been traced to source. Inferred or unverified paths are labelled in the diagram itself.

Understand the whole app

The fastest visual entry points before reading records.

AI Saga Arcana application overview

How visitors become signed-in generators, how jobs move through the queue and worker into the gallery, and how Stripe credits and B2 storage fit the picture.

AI Saga Arcana application overview Visitors land on marketing pages, register and verify, then use the generator. Jobs enter the queue, a cron worker calls Gemini and stores results on B2 and MySQL, and the gallery shows completed renders. Stripe grants credits. Solid edges are verified from source; dashed edges are inferred. Application overview Solid = verified from source · Dashed = inferred. Select any box or arrow for its explanation. Visitor — open explanation Visitor browser Landing — open explanation Landing index.php Auth gate — open explanation Auth gate register / login Generator — open explanation Generator band · song · style Queue — open explanation Queue arcana_queue Cron worker — open explanation Cron worker Gemini pipeline Gallery — open explanation Gallery arcana_renders Stripe — open explanation Stripe checkout · webhooks Credits — open explanation Credits users.image_credits Backblaze B2 — open explanation Backblaze B2 image objects opens opens routes to routes to allows allows writes writes claims claims creates creates stores in stores in grants grants gates gates retrieves retrieves
What am I looking at? How visitors become signed-in generators, how jobs move through the queue and worker into the gallery, and how Stripe credits and B2 storage fit the picture.
How to read this Solid line — verified from source Dashed line — inferred from source Select any box or arrow in the diagram to jump to its explanation.

Parts — what each one is

Each part explains why it appears, where it lives in the repository, and which files to read.

Visitor
Verified from source

A person in a browser opening Arcana's public and signed-in pages.

Related functionality: Public landing page

Landing
Verified from source

The marketing home page presents the product, sample imagery, and CTAs to register or log in.

Related functionality: Public landing page

Where it lives External to this repository.
  • index.php
Files that implement or support it
  • Entry pointindex.php

    Canonical desktop landing; may redirect mobile UAs to index.mobile.php.

    Canonical purpose: Public marketing landing with mobile redirect.

    Open entry point

Auth gate
Verified from source

Invite-gated registration, email verification, and session login before protected features.

Related functionality: Account registration Login and logout Email verification

Where it lives External to this repository.
  • auth_lib.php
  • arcana.register.php
  • arcana.login.php
Files that implement or support it
  • Primary implementationauth_lib.php

    Session, PDO users table, CSRF, login/register helpers.

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

    Open implementation

  • Entry pointarcana.register.php

    Invite + Turnstile registration page.

    Open entry point

  • Entry pointarcana.login.php

    Canonical login page.

    Open entry point

Generator
Verified from source

Signed-in form that collects band/song/lyrics/style/portraits and enqueues a render job.

Related functionality: Image-generation form Queue submission

Where it lives External to this repository.
  • arcana.image.generator.php
Files that implement or support it
  • Primary implementationarcana.image.generator.php

    Main UI and AJAX enqueue into arcana_queue.

    Canonical purpose: Primary user-facing generation UI and queue enqueue.

    Open implementation

Queue
Verified from source

Pending/processing/completed job rows that workers claim.

Related functionality: Queue submission Background render processing

Where it lives MySQL/
  • arcana.image.generator.php
Files that implement or support it
  • Storagearcana.image.generator.php

    Inserts pending rows with style, aspect, portraits, watermark.

    Canonical purpose: Primary user-facing generation UI and queue enqueue.

    View source on GitHub

Uncertain: CREATE TABLE for arcana_queue is not in-repo.

Cron worker
Inferred from source

Background PHP script that analyzes lyrics, builds prompts, calls Gemini image models, and persists results.

Related functionality: Background render processing Song and lyric analysis Gemini image generation

Where it lives External to this repository.
  • arcana.queue.processor.cron.parallel.v3.dynamicstyle.php
Files that implement or support it
  • Primary implementationarcana.queue.processor.cron.parallel.v3.dynamicstyle.php

    Best-evidence production worker with parallel Gemini, styles, retries, credits, B2.

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

    Open implementation

Uncertain: Which worker is scheduled on the host is not confirmed in-repo.

Stripe
Verified from source

Checkout sessions and webhooks that sell credit packs and subscriptions.

Related functionality: Stripe checkout Stripe webhook processing

Where it lives External to this repository.
  • stripe_lib.php
  • arcana.stripe.endpoint.php
Files that implement or support it
  • Primary implementationstripe_lib.php

    Checkout creation and webhook handlers.

    Canonical purpose: Stripe SDK helpers for products, checkout, webhooks, credit grants.

    Open implementation

  • Entry pointarcana.stripe.endpoint.php

    Modern Stripe webhook endpoint.

    Open entry point

Credits
Verified from source

Image credit balances on users that gate enqueue and are consumed after successful renders.

Related functionality: Credit balances

Where it lives MySQL users/
  • auth_lib.php
Files that implement or support it
  • Primary implementationauth_lib.php

    auth_user_has_credits / consume / add_credits with row locks.

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

    Open implementation

Backblaze B2
Verified from source

Object storage for full images and thumbnails, with optional local backup under uploads/dble.

Related functionality: Local and Backblaze B2 storage

Where it lives includes/
  • includes/
    • b2_helpers.php
Files that implement or support it
  • Integration adapterincludes/b2_helpers.php

    Upload, delete, and public URL helpers for B2.

    Canonical purpose: Backblaze B2 upload/delete/public URL helpers.

    View source on GitHub

Connections — why they connect

Each connection names the concrete mechanism linking its two parts. The mechanism is the proof the relationship passed the explainability gate.

Visitor routes to Landing
Verified from source Solid line

The visitor's browser requests the site document root, which serves index.php as the marketing landing.

Related functionality: Public landing page

Files behind this connection
  • Entry pointindex.php

    Default landing entry.

    Canonical purpose: Public marketing landing with mobile redirect.

    Open entry point

Landing routes to Auth gate
Verified from source Solid line

Landing CTAs link to arcana.register.php and arcana.login.php for account creation and sign-in.

Related functionality: Public landing page Account registration Login and logout

Files behind this connection
  • Callerindex.php

    Links to register and login pages.

    Canonical purpose: Public marketing landing with mobile redirect.

    View caller

Auth gate validates Generator
Verified from source Solid line

Protected pages include auth_check.php, which requires a logged-in session before the generator runs.

Related functionality: Login and logout Image-generation form

Files behind this connection
  • Validationauth_check.php

    Login + maintenance gate used by the generator.

    Canonical purpose: Require login and honor maintenance mode.

    View source on GitHub

Generator writes Queue
Verified from source Solid line

On generate, the form inserts a pending row into arcana_queue with inputs and flags.

Related functionality: Queue submission

Files behind this connection
  • Primary implementationarcana.image.generator.php

    Performs the INSERT into arcana_queue.

    Canonical purpose: Primary user-facing generation UI and queue enqueue.

    Open implementation

Queue retrieves from Cron worker
Inferred from source Dashed line

The worker SELECTs pending rows FOR UPDATE, marks them processing, then runs the Gemini pipeline.

Basis for the inference: Claim/lock pattern is present in the v3 worker source; which script cron invokes is unconfirmed.

Related functionality: Background render processing

Files behind this connection
  • Primary implementationarcana.queue.processor.cron.parallel.v3.dynamicstyle.php

    Claims and processes queue rows.

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

    Open implementation

Uncertain: Host crontab not in repo.

Cron worker creates Gallery
Inferred from source Dashed line

After a successful image save, the worker inserts an arcana_renders row that the gallery lists.

Basis for the inference: v3 worker contains the INSERT and gallery reads the same table; end-to-end runtime not executed.

Related functionality: Gemini image generation User render gallery

Files behind this connection
  • Primary implementationarcana.queue.processor.cron.parallel.v3.dynamicstyle.php

    INSERT into arcana_renders after save.

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

    Open implementation

Cron worker stores in Backblaze B2
Verified from source Solid line

The worker encodes WebP/thumb and uploads them through b2_helpers.

Related functionality: Local and Backblaze B2 storage

Files behind this connection
  • Integration adapterincludes/b2_helpers.php

    b2_upload_file used by workers.

    Canonical purpose: Backblaze B2 upload/delete/public URL helpers.

    View source on GitHub

Stripe updates Credits
Verified from source Solid line

Stripe checkout/invoice handlers call stripe_grant_credits / auth_user_add_credits to increase image_credits.

Related functionality: Stripe webhook processing Credit balances

Files behind this connection
  • Primary implementationstripe_lib.php

    Webhook handlers grant credits.

    Canonical purpose: Stripe SDK helpers for products, checkout, webhooks, credit grants.

    Open implementation

Credits validates Generator
Verified from source Solid line

Before enqueue, the generator checks auth_user_has_credits for at least one image credit.

Related functionality: Credit balances Queue submission

Files behind this connection
  • Validationauth_lib.php

    Credit balance helpers.

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

    View source on GitHub

Gallery retrieves from Backblaze B2
Verified from source Solid line

Gallery helpers prefer B2 public URLs (or the viewimage proxy) when presenting thumbnails and full images.

Related functionality: User render gallery Local and Backblaze B2 storage

Files behind this connection
  • Primary implementationarcana.image.gallery.php

    Builds image/thumbnail src from B2 helpers.

    Canonical purpose: User gallery browse/search/sort/paginate/email/delete.

    Open implementation

Diagram type
Application overview
Verification
Inferred from source
Source evidence
Overview assembled by tracing landing, auth_check, generator enqueue, v3 worker, gallery, stripe_lib, and b2_helpers against source at commit 3d7f6a0.
Last verified against source
2026-07-21
Uncertainty
Which cron worker is scheduled and which Stripe webhook URL is live remain host-level unknowns.

Related functionality: Public landing page Account registration Login and logout Image-generation form Queue submission Background render processing User render gallery Stripe checkout Credit balances Local and Backblaze B2 storage

Related warnings: arcana_queue schema missing in-repo Dual Stripe webhook implementations

Related diagrams: Generation pipeline from form to gallery Authentication and access flow

Understand the main product flow

How generation jobs move from the form through the queue to the gallery.

Generation pipeline from form to gallery

Credit-checked enqueue, worker claim, Gemini analysis and image generation, B2 persistence, and post-success credit consumption.

Generation pipeline from form to gallery The generator writes a pending queue row after a credit check. The cron worker claims the row, analyzes lyrics with Gemini text, builds a cinematic prompt, generates an image with Gemini, uploads WebP to B2, inserts arcana_renders, and consumes a credit. Solid edges are verified; dashed edges are inferred. Generation pipeline Solid = verified from source · Dashed = inferred. Select any box or arrow for its explanation. Generator form — open explanation Generator form AJAX generate Credit check — open explanation Credit check image_credits Queue row — open explanation Queue row status=pending Claim job — open explanation Claim job FOR UPDATE Song DNA — open explanation Song DNA Gemini text Cinematic — open explanation Cinematic prompt build Image gen — open explanation Image gen Gemini image Persist — open explanation Persist B2 + renders Consume credit — open explanation Consume credit deduct 1 validates validates writes writes retrieves retrieves calls calls returns to returns to sends to sends to stores in stores in updates updates
What am I looking at? Credit-checked enqueue, worker claim, Gemini analysis and image generation, B2 persistence, and post-success credit consumption.
How to read this Solid line — verified from source Dashed line — inferred from source Select any box or arrow in the diagram to jump to its explanation.

Parts — what each one is

Each part explains why it appears, where it lives in the repository, and which files to read.

Generator form
Verified from source

Collects band, song, lyrics, style, aspect, and portraits then POSTs action=generate.

Related functionality: Image-generation form

Where it lives External to this repository.
  • arcana.image.generator.php
Files that implement or support it
  • Entry pointarcana.image.generator.php

    User-facing generation UI and AJAX handler.

    Canonical purpose: Primary user-facing generation UI and queue enqueue.

    Open entry point

Credit check
Verified from source

Ensures the user has at least one image credit before a job is accepted.

Related functionality: Credit balances Queue submission

Where it lives External to this repository.
  • auth_lib.php
Files that implement or support it
  • Validationauth_lib.php

    auth_user_has_credits gates enqueue.

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

    View source on GitHub

Queue row
Verified from source

A pending arcana_queue record holding all generation inputs and flags.

Related functionality: Queue submission

Where it lives MySQL/
  • arcana.image.generator.php
Files that implement or support it
  • Primary implementationarcana.image.generator.php

    INSERT pending queue row.

    Canonical purpose: Primary user-facing generation UI and queue enqueue.

    Open implementation

Uncertain: Table DDL not in repository.

Claim job
Verified from source

Worker transactionally selects pending rows and marks them processing.

Related functionality: Background render processing Parallel worker execution

Where it lives External to this repository.
  • arcana.queue.processor.cron.parallel.v3.dynamicstyle.php
Files that implement or support it
  • Primary implementationarcana.queue.processor.cron.parallel.v3.dynamicstyle.php

    SELECT ... FOR UPDATE then status=processing.

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

    Open implementation

Song DNA
Verified from source

Gemini text model returns structured mood/theme/visual DNA for the song.

Related functionality: Song and lyric analysis

Where it lives External to this repository.
  • arcana.queue.processor.cron.parallel.v3.dynamicstyle.php
Files that implement or support it
  • Primary implementationarcana.queue.processor.cron.parallel.v3.dynamicstyle.php

    Parallel Gemini text analysis phase.

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

    Open implementation

Cinematic prompt
Verified from source

Assembles the image prompt from DNA, optional style directive, portraits, and watermark branding.

Related functionality: Cinematic prompt creation Static visual styles Dynamic band-style analysis Watermark application

Where it lives External to this repository.
  • arcana.queue.processor.cron.parallel.v3.dynamicstyle.php
Files that implement or support it
  • Primary implementationarcana.queue.processor.cron.parallel.v3.dynamicstyle.php

    Prompt construction and style branching.

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

    Open implementation

Image gen
Verified from source

Gemini image model produces the cinematic still, with multi-attempt fallbacks on safety failures.

Related functionality: Gemini image generation Retry and fallback behavior

Where it lives External to this repository.
  • arcana.queue.processor.cron.parallel.v3.dynamicstyle.php
Files that implement or support it
  • Primary implementationarcana.queue.processor.cron.parallel.v3.dynamicstyle.php

    Image generation and retry loop.

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

    Open implementation

Persist
Inferred from source

Writes WebP + thumb to B2 (and local backup) and inserts arcana_renders metadata.

Related functionality: Local and Backblaze B2 storage User render gallery

Where it lives External to this repository.
  • includes/
    • b2_helpers.php
  • arcana.queue.processor.cron.parallel.v3.dynamicstyle.php
Files that implement or support it
  • Integration adapterincludes/b2_helpers.php

    Object upload helpers.

    Canonical purpose: Backblaze B2 upload/delete/public URL helpers.

    View source on GitHub

  • Primary implementationarcana.queue.processor.cron.parallel.v3.dynamicstyle.php

    Save + INSERT arcana_renders.

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

    Open implementation

Uncertain: End-to-end save not executed in this environment.

Consume credit
Verified from source

After success, deducts one image credit and marks the queue row completed.

Related functionality: Credit balances Background render processing

Where it lives External to this repository.
  • auth_lib.php
Files that implement or support it
  • Primary implementationauth_lib.php

    auth_user_consume_credit.

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

    Open implementation

Connections — why they connect

Each connection names the concrete mechanism linking its two parts. The mechanism is the proof the relationship passed the explainability gate.

Generator form validates Credit check
Verified from source Solid line

The generate action calls auth_user_has_credits before writing a queue row.

Related functionality: Credit balances Queue submission

Files behind this connection
  • Validationauth_lib.php

    Balance check API.

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

    View source on GitHub

Credit check writes Queue row
Verified from source Solid line

When credits pass, the generator inserts a pending arcana_queue row with the request payload.

Related functionality: Queue submission

Files behind this connection
  • Primary implementationarcana.image.generator.php

    Queue INSERT.

    Canonical purpose: Primary user-facing generation UI and queue enqueue.

    Open implementation

Queue row retrieves from Claim job
Verified from source Solid line

The cron worker retrieves pending rows under a transaction lock and marks them processing.

Related functionality: Background render processing

Files behind this connection
  • Primary implementationarcana.queue.processor.cron.parallel.v3.dynamicstyle.php

    Claim loop.

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

    Open implementation

Claim job calls Song DNA
Verified from source Solid line

After claim, the worker calls Gemini text models to produce Song DNA JSON from band/song/lyrics.

Related functionality: Song and lyric analysis

Files behind this connection
  • Callerarcana.queue.processor.cron.parallel.v3.dynamicstyle.php

    Text analysis phase.

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

    View caller

Song DNA returns to Cinematic prompt
Verified from source Solid line

Analysis JSON is folded into the cinematic prompt builder along with style and watermark rules.

Related functionality: Cinematic prompt creation

Files behind this connection
  • Primary implementationarcana.queue.processor.cron.parallel.v3.dynamicstyle.php

    Prompt assembly uses analysis output.

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

    Open implementation

Cinematic prompt sends to Image gen
Verified from source Solid line

The finished prompt (and optional portraits) are sent to the Gemini image model.

Related functionality: Gemini image generation

Files behind this connection
  • Callerarcana.queue.processor.cron.parallel.v3.dynamicstyle.php

    Image generation request.

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

    View caller

Image gen stores in Persist
Inferred from source Dashed line

Successful image bytes are encoded to WebP, uploaded to B2, and recorded in arcana_renders.

Basis for the inference: Save/upload/insert code paths exist in the worker; runtime upload not executed here.

Related functionality: Local and Backblaze B2 storage

Files behind this connection
  • Integration adapterincludes/b2_helpers.php

    Upload path.

    Canonical purpose: Backblaze B2 upload/delete/public URL helpers.

    View source on GitHub

Persist updates Consume credit
Verified from source Solid line

After a successful persist, the worker consumes one image credit and marks the queue job completed.

Related functionality: Credit balances

Files behind this connection
  • Calleeauth_lib.php

    Credit consumption helper.

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

    View callee

Diagram type
Request flow
Verification
Inferred from source
Source evidence
Traced enqueue in arcana.image.generator.php and processing phases in the v3 parallel worker.
Last verified against source
2026-07-21
Uncertainty
Production cron may run a different processor variant; dynamic style UI default does not send ANALYZE_BAND_STYLE.

Related functionality: Image-generation form Queue submission Background render processing Song and lyric analysis Cinematic prompt creation Gemini image generation Retry and fallback behavior Local and Backblaze B2 storage Credit balances

Related warnings: arcana_queue schema missing in-repo

Related diagrams: AI Saga Arcana application overview

Authentication and access flow

Invite registration, email verification, session login, protected-page gating, and password reset against the users table.

Authentication and access flow Invite registration with Turnstile creates a user, email verification unlocks login, sessions gate protected pages, and password reset recovers access. Solid edges verified from source. Auth & access Solid = verified from source · Dashed = inferred. Select any box or arrow for its explanation. Invite code — open explanation Invite code access_codes Register — open explanation Register + Turnstile Email verify — open explanation Email verify token link Login — open explanation Login session Protected page — open explanation Protected page auth_check Password reset — open explanation Password reset forgot / reset users table — open explanation users table MySQL validates validates creates creates sends to sends to allows allows routes to routes to reads reads updates updates
What am I looking at? Invite registration, email verification, session login, protected-page gating, and password reset against the users table.
How to read this Solid line — verified from source Dashed line — inferred from source Select any box or arrow in the diagram to jump to its explanation.

Parts — what each one is

Each part explains why it appears, where it lives in the repository, and which files to read.

Invite code
Verified from source

Registration requires a valid row in access_codes that is deleted after use.

Related functionality: Account registration

Where it lives MySQL/
  • arcana.register.php
Files that implement or support it

Uncertain: access_codes DDL not in-repo.

Register
Verified from source

Creates the account after Turnstile, CSRF, and invite checks.

Related functionality: Account registration

Where it lives External to this repository.
  • arcana.register.php
  • arcana.turnstile.php
Files that implement or support it
Email verify
Verified from source

Token link marks email_verified and clears the verification token.

Related functionality: Email verification

Where it lives External to this repository.
  • arcana.verify.php
  • arcana.auth_email_verification.php
Files that implement or support it
Login
Verified from source

Validates credentials, blocks unverified emails, and starts a session.

Related functionality: Login and logout

Where it lives External to this repository.
  • arcana.login.php
  • auth_lib.php
Files that implement or support it
  • Entry pointarcana.login.php

    Canonical login UI.

    Open entry point

  • Primary implementationauth_lib.php

    auth_attempt_login / auth_login.

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

    Open implementation

Protected page
Verified from source

auth_check.php enforces login (and maintenance) before generator/gallery flows.

Related functionality: Login and logout Maintenance mode

Where it lives External to this repository.
  • auth_check.php
Files that implement or support it
  • Validationauth_check.php

    Shared protected-page gate.

    Canonical purpose: Require login and honor maintenance mode.

    View source on GitHub

Password reset
Verified from source

Forgot-password email issues a time-limited token; reset page sets a new hash.

Related functionality: Password reset

Where it lives External to this repository.
  • arcana.password.forgot.php
  • arcana.password.reset.php
  • arcana.password.auth_reset.php
Files that implement or support it
users table
Verified from source

Authoritative account, verification, password, plan, and credit columns.

Related functionality: Account registration Login and logout Credit balances

Where it lives MySQL/
  • auth_lib.php
Files that implement or support it
  • Data modelauth_lib.php

    auth_ensure_schema and user queries.

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

    View source on GitHub

Connections — why they connect

Each connection names the concrete mechanism linking its two parts. The mechanism is the proof the relationship passed the explainability gate.

Invite code validates Register
Verified from source Solid line

Registration looks up the invite code and refuses signup without a valid unused code.

Related functionality: Account registration

Files behind this connection
Register creates users table
Verified from source Solid line

auth_register_user inserts the new users row after validation.

Related functionality: Account registration

Files behind this connection
  • Primary implementationauth_lib.php

    User insert helper.

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

    Open implementation

Register sends to Email verify
Verified from source Solid line

After insert, registration generates a verification token and emails the verify link.

Related functionality: Email verification

Files behind this connection
Email verify validates Login
Verified from source Solid line

Login refuses sessions for users with email_verified=0 until the verify link succeeds.

Related functionality: Email verification Login and logout

Files behind this connection
Login routes to Protected page
Verified from source Solid line

A successful login sets session user_id; auth_check requires that session on protected pages.

Related functionality: Login and logout

Files behind this connection
  • Validationauth_check.php

    auth_require_login.

    Canonical purpose: Require login and honor maintenance mode.

    View source on GitHub

Login reads users table
Verified from source Solid line

Login SELECTs the user by username/email and verifies the password hash.

Related functionality: Login and logout

Files behind this connection
  • Primary implementationauth_lib.php

    auth_attempt_login.

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

    Open implementation

Password reset updates users table
Verified from source Solid line

Password reset writes password_hash and clears reset tokens on the users row.

Related functionality: Password reset

Files behind this connection
Diagram type
Authentication flow
Verification
Verified from source
Source evidence
Traced register/login/verify/reset and auth_check against source.
Last verified against source
2026-07-21
Uncertainty
access_codes table provisioning is external; users.status is not checked at login.

Related functionality: Account registration Email verification Login and logout Password reset Maintenance mode

Related warnings: access_codes schema missing in-repo Duplicate login pages Suspended/banned status not enforced at login Email change skips re-verification Password reset lacks rate limiting

Related diagrams: AI Saga Arcana application overview

Understand the technical system

Where data lives and which external services are involved.

Data and storage map

Dual PDO/mysqli MySQL access, local uploads/dble backups, Backblaze B2 objects, and PHP sessions.

Data and storage map PHP pages talk to MySQL through PDO and mysqli paths, store uploads under uploads/dble, and sync image objects to Backblaze B2. Sessions live in PHP session storage. Dashed edges mark dual DB client paths. Storage map Solid = verified from source · Dashed = inferred. Select any box or arrow for its explanation. PHP pages — open explanation PHP pages entrypoints PDO path — open explanation PDO path auth_lib mysqli path — open explanation mysqli path stripe_lib MySQL / MariaDB — open explanation MySQL / MariaDB users · queue · renders Local uploads — open explanation Local uploads uploads/dble Backblaze B2 — open explanation Backblaze B2 public objects PHP session — open explanation PHP session aisaga_sid calls calls calls calls reads reads writes writes stores in stores in sends to sends to stores in stores in
What am I looking at? Dual PDO/mysqli MySQL access, local uploads/dble backups, Backblaze B2 objects, and PHP sessions.
How to read this Solid line — verified from source Dashed line — inferred from source Select any box or arrow in the diagram to jump to its explanation.

Parts — what each one is

Each part explains why it appears, where it lives in the repository, and which files to read.

PHP pages
Verified from source

Server-rendered entrypoints and workers that perform reads/writes.

Related functionality: Login and logout Queue submission Stripe checkout

Where it lives repo root/
  • auth_lib.php
Files that implement or support it
  • Dependencyauth_lib.php

    Shared PDO/session helpers included widely.

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

    View source on GitHub

PDO path
Verified from source

Primary database access for auth, credits, queue pages using auth_pdo().

Related functionality: Login and logout Credit balances

Where it lives External to this repository.
  • auth_lib.php
Files that implement or support it
  • Primary implementationauth_lib.php

    auth_pdo and schema helpers.

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

    Open implementation

mysqli path
Verified from source

Stripe library uses mysqli for product/checkout/subscription tables.

Related functionality: Stripe checkout Stripe webhook processing

Where it lives External to this repository.
  • stripe_lib.php
Files that implement or support it
  • Primary implementationstripe_lib.php

    mysqli-based Stripe persistence.

    Canonical purpose: Stripe SDK helpers for products, checkout, webhooks, credit grants.

    Open implementation

MySQL / MariaDB
Inferred from source

Relational store for users, queue, renders, styles, settings, and Stripe tables.

Related functionality: Credit balances Queue submission User render gallery

Where it lives host DB/
  • auth_lib.php
Files that implement or support it
  • Data modelauth_lib.php

    Creates users/credit_transactions; other tables assumed external.

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

    View source on GitHub

Uncertain: Several tables lack in-repo CREATE statements.

Local uploads
Verified from source

Filesystem backup and staging under uploads/dble including refs and thumbs.

Related functionality: Portrait reference uploads Local and Backblaze B2 storage

Where it lives uploads/dble/
  • arcana.image.generator.php
Files that implement or support it
  • Storagearcana.image.generator.php

    Writes portrait refs under uploads/dble/refs.

    Canonical purpose: Primary user-facing generation UI and queue enqueue.

    View source on GitHub

Backblaze B2
Verified from source

Durable public object storage for generated images and thumbnails.

Related functionality: Local and Backblaze B2 storage

Where it lives includes/
  • includes/
    • b2_helpers.php
  • config/
    • backblaze.example.php
Files that implement or support it
  • Integration adapterincludes/b2_helpers.php

    B2 API helpers.

    Canonical purpose: Backblaze B2 upload/delete/public URL helpers.

    View source on GitHub

  • Configurationconfig/backblaze.example.php

    Documents B2 config variable names (not values).

    View configuration

PHP session
Verified from source

Cookie aisaga_sid holds the logged-in user_id and CSRF state.

Related functionality: Login and logout

Where it lives External to this repository.
  • auth_lib.php
Files that implement or support it
  • Primary implementationauth_lib.php

    Session bootstrap and cookie settings.

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

    Open implementation

Connections — why they connect

Each connection names the concrete mechanism linking its two parts. The mechanism is the proof the relationship passed the explainability gate.

PHP pages calls PDO path
Verified from source Solid line

Most auth and generator pages include auth_lib and call auth_pdo() for SQL.

Related functionality: Login and logout

Files behind this connection
  • Calleeauth_lib.php

    PDO factory.

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

    View callee

PHP pages calls mysqli path
Verified from source Solid line

Pricing and webhook pages use stripe_lib's mysqli connection for commerce tables.

Related functionality: Stripe checkout

Files behind this connection
  • Calleestripe_lib.php

    mysqli commerce path.

    Canonical purpose: Stripe SDK helpers for products, checkout, webhooks, credit grants.

    View callee

PDO path reads MySQL / MariaDB
Verified from source Solid line

PDO statements read and write the shared MySQL database.

Related functionality: Credit balances

Files behind this connection
  • Primary implementationauth_lib.php

    Prepared statements against MySQL.

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

    Open implementation

mysqli path writes MySQL / MariaDB
Verified from source Solid line

stripe_lib writes checkout sessions, subscriptions, and related commerce rows through mysqli.

Related functionality: Stripe webhook processing

Files behind this connection
  • Primary implementationstripe_lib.php

    Commerce persistence.

    Canonical purpose: Stripe SDK helpers for products, checkout, webhooks, credit grants.

    Open implementation

PHP pages stores in Local uploads
Verified from source Solid line

Generator and workers write portraits and WebP backups under uploads/dble.

Related functionality: Portrait reference uploads Local and Backblaze B2 storage

Files behind this connection
  • Primary implementationarcana.image.generator.php

    Portrait upload path.

    Canonical purpose: Primary user-facing generation UI and queue enqueue.

    Open implementation

Local uploads sends to Backblaze B2
Verified from source Solid line

After local encode, workers upload full image and thumbnail objects to B2.

Related functionality: Local and Backblaze B2 storage

Files behind this connection
  • Integration adapterincludes/b2_helpers.php

    b2_upload_file.

    Canonical purpose: Backblaze B2 upload/delete/public URL helpers.

    View source on GitHub

PHP pages stores in PHP session
Verified from source Solid line

Auth pages store user_id and CSRF tokens in the PHP session backed by cookie aisaga_sid.

Related functionality: Login and logout

Files behind this connection
  • Primary implementationauth_lib.php

    Session bootstrap.

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

    Open implementation

Diagram type
Storage map
Verification
Inferred from source
Source evidence
Mapped from auth_lib PDO usage, stripe_lib mysqli usage, and b2_helpers upload paths.
Last verified against source
2026-07-21
Uncertainty
External table DDL and whether both Stripe DB clients point at identical schemas in production.

Related functionality: Login and logout Credit balances Queue submission Local and Backblaze B2 storage Stripe checkout Portrait reference uploads

Related warnings: credit_transactions schema mismatch arcana_queue schema missing in-repo Stripe commerce tables missing CREATE

Related diagrams: AI Saga Arcana application overview Risk and uncertainty map

Understand uncertainty

Where to be careful and what is not yet verified.

Risk and uncertainty map

Dual Stripe receivers and double-grant risk, missing DDL, exposed debug endpoints, duplicate login pages, and unknown production cron selection.

Risk and uncertainty map Known landmines around dual Stripe webhooks and possible double grants, missing queue schema, exposed debug endpoints, duplicate login pages, and unverified production cron selection. Edges state concrete mechanisms only. Risk & uncertainty Solid = verified from source · Dashed = inferred. Select any box or arrow for its explanation. Dual webhooks — open explanation Dual webhooks endpoint + webhook.php Double grant risk — open explanation Double grant risk success + webhook Credit balances — open explanation Credit balances users.image_credits Missing DDL — open explanation Missing DDL queue / stripe / codes Debug endpoints — open explanation Debug endpoints B2 key prefixes Dual login pages — open explanation Dual login pages login.php legacy Cron unknown — open explanation Cron unknown which worker? Worker variants — open explanation Worker variants v3 / gpt / nw depends on depends on updates updates depends on depends on configures configures depends on depends on
What am I looking at? Dual Stripe receivers and double-grant risk, missing DDL, exposed debug endpoints, duplicate login pages, and unknown production cron selection.
How to read this Solid line — verified from source Dashed line — inferred from source Select any box or arrow in the diagram to jump to its explanation.

Parts — what each one is

Each part explains why it appears, where it lives in the repository, and which files to read.

Dual webhooks
Verified from source

Two Stripe receiver scripts exist with different grant/schema assumptions.

Related functionality: Stripe webhook processing

Where it lives External to this repository.
  • arcana.stripe.endpoint.php
  • webhook.php
Files that implement or support it
  • Entry pointarcana.stripe.endpoint.php

    Modern SDK-verified webhook.

    Open entry point

  • Entry pointwebhook.php

    Legacy HMAC webhook path.

    Canonical purpose: Lightweight Stripe webhook for checkout session credit grants.

    Open entry point

⚠ Warnings: Dual Stripe webhook implementations

Uncertain: Which URL Stripe calls in production is unknown.

Double grant risk
Verified from source

Checkout success page can grant packs if the session row is not yet marked completed, overlapping the webhook grant.

Related functionality: Credit-pack purchases Stripe webhook processing

Where it lives External to this repository.
  • arcana.purchase.success.php
  • stripe_lib.php
Files that implement or support it
  • Primary implementationarcana.purchase.success.php

    Client-side grant path.

    Open implementation

  • Primary implementationstripe_lib.php

    Webhook grant path.

    Canonical purpose: Stripe SDK helpers for products, checkout, webhooks, credit grants.

    Open implementation

⚠ Warnings: Possible double credit grant paths

Credit balances
Verified from source

users.image_credits is the spend currency; incorrect grants permanently change balances.

Related functionality: Credit balances

Where it lives MySQL/
  • auth_lib.php
Files that implement or support it
  • Primary implementationauth_lib.php

    Credit mutate helpers.

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

    Open implementation

Missing DDL
Verified from source

Critical tables are queried without in-repo CREATE statements.

Related functionality: Queue submission Stripe checkout Account registration In-app notifications

Where it lives External to this repository.
  • auth_lib.php
Files that implement or support it
  • Data modelauth_lib.php

    Only users/credit_transactions ensured in-repo.

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

    View source on GitHub

⚠ Warnings: arcana_queue schema missing in-repo Stripe commerce tables missing CREATE access_codes schema missing in-repo user_notifications schema missing

Uncertain: Production may have migrated tables out of band.

Debug endpoints
Verified from source

Unauthenticated or weakly gated debug scripts can leak configuration fingerprints.

Related functionality: Local and Backblaze B2 storage

Where it lives External to this repository.
  • arcana.debug_b2.php
  • path.php
Files that implement or support it

⚠ Warnings: Debug/test utilities present in tree

Dual login pages
Verified from source

login.php and arcana.login.php both exist; default redirects still mention login.php.

Related functionality: Login and logout

Where it lives External to this repository.
  • login.php
  • arcana.login.php
Files that implement or support it
  • Entry pointlogin.php

    Legacy login page.

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

    Open entry point

  • Entry pointarcana.login.php

    Canonical login page.

    Open entry point

⚠ Warnings: Duplicate login pages

Cron unknown
Inferred from source

Multiple processor variants coexist; host crontab is not in the repository.

Related functionality: Background render processing Parallel worker execution

Where it lives hosting/
  • path.php
Files that implement or support it

Uncertain: Actual scheduled script unknown.

Worker variants
Verified from source

v3 dynamicstyle, gpt-named, nowatermark, and sequential processors implement different watermark/parallel behaviour.

Related functionality: Background render processing Watermark application

Where it lives External to this repository.
  • arcana.queue.processor.cron.parallel.v3.dynamicstyle.php
  • arcana.queue.processor.cron.nowatermark.php
Files that implement or support it
  • Primary implementationarcana.queue.processor.cron.parallel.v3.dynamicstyle.php

    Best-evidence current worker.

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

    Open implementation

  • Supporting utilityarcana.queue.processor.cron.nowatermark.php

    Misnamed; still applies Imagick logos.

    View source on GitHub

Connections — why they connect

Each connection names the concrete mechanism linking its two parts. The mechanism is the proof the relationship passed the explainability gate.

Dual webhooks depends on Double grant risk
Verified from source Solid line

Having two receivers plus a success-page grant multiplies opportunities for the same checkout to be credited more than once.

Related functionality: Stripe webhook processing

Files behind this connection
  • Entry pointwebhook.php

    Legacy path still present.

    Canonical purpose: Lightweight Stripe webhook for checkout session credit grants.

    Open entry point

⚠ Warnings: Dual Stripe webhook implementations Possible double credit grant paths

Double grant risk updates Credit balances
Verified from source Solid line

Each grant path increments users.image_credits, so overlapping grants permanently inflate balances.

Related functionality: Credit balances Credit-pack purchases

Files behind this connection
  • Calleeauth_lib.php

    auth_user_add_credits / stripe_grant_credits.

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

    View callee

Missing DDL depends on Worker variants
Inferred from source Dashed line

Workers and enqueue code assume arcana_queue exists with expected columns even though CREATE DDL is absent from the repo.

Basis for the inference: Code queries the table; only ALTERs found in-repo, no CREATE.

Related functionality: Queue submission Background render processing

Files behind this connection
  • Primary implementationarcana.queue.processor.cron.parallel.v3.dynamicstyle.php

    Queries arcana_queue.

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

    Open implementation

⚠ Warnings: arcana_queue schema missing in-repo

Cron unknown configures Worker variants
Inferred from source Dashed line

The host crontab (not in repo) selects which worker variant actually runs in production.

Basis for the inference: Multiple processors exist; no crontab committed.

Related functionality: Background render processing

Files behind this connection

Uncertain: Exact schedule unknown.

Debug endpoints depends on Missing DDL
Inferred from source Dashed line

Debug utilities exist partly because operators must inspect external storage/schema state that is not fully bootstrapped by the repo.

Basis for the inference: Debug scripts reference external config and storage assumptions.

Related functionality: Local and Backblaze B2 storage

Files behind this connection

⚠ Warnings: Debug/test utilities present in tree

Diagram type
Risk and uncertainty map
Verification
Verified from source
Source evidence
Risks traced to concrete files and warning records during the 2026-07-21 rebootstrap.
Last verified against source
2026-07-21
Uncertainty
Host-level cron and live Stripe webhook URL remain unknown.

Related functionality: Stripe webhook processing Credit balances Queue submission Background render processing Login and logout Local and Backblaze B2 storage

Related warnings: Dual Stripe webhook implementations Possible double credit grant paths arcana_queue schema missing in-repo Stripe commerce tables missing CREATE access_codes schema missing in-repo user_notifications schema missing Debug/test utilities present in tree Duplicate login pages

Related diagrams: Data and storage map AI Saga Arcana application overview