chat/README.md

CyberChat

CyberChat is a framework-free PHP, SQLite, JavaScript, and HTML5 chat application with configurable paid tiers, Stripe subscriptions, Mailgun email verification, voice messages, personal archives, an administrator dashboard, and an optional MySQL/MariaDB mirror.

Included Features

• Registration without an email address
• Verified email required before premium checkout
• Mailgun email verification and email two-factor login codes
• Stripe Checkout, Billing Portal, webhook synchronization, and cancellation
• Configurable plans, prices, Stripe Price IDs, limits, and feature assignments
• Subscription display switch that hides new sales while preserving billing management for existing customers
• Premium-configurable recording presence for both sending and viewing
• Premium-configurable automatic voice sending
• Tier-configurable automatic playback of newly received voice clips
• Optional FFmpeg voice transcoding to iPhone-compatible AAC/M4A or H.264/AAC MP4
• Administrator tier overrides that grant plan features without payment
• Single-worker queued polling with cursor catch-up, request timeouts, deduplication, bounded retry backoff, and a capped browser message buffer
• Plan-based custom username colors
• Personal text archives retained for at least 30 days
• Plan-based voice archive access and JSON/CSV exports
• Visitor and feature usage statistics
• SQLite by default, with optional automatic MySQL/MariaDB mirroring
• Dark neon interface with a saved light-mode toggle

Requirements

• PHP 8.1 or newer
• PHP extensions: pdo_sqlite, curl, and fileinfo
• A web server with HTTPS for production
• Write access to db/, archive/, uploads/voice/, and config.json
• A modern browser with MediaRecorder for voice recording
• Optional: FFmpeg with AAC support; libx264 is also required for the H.264 profile
• Optional: PDO MySQL for the MySQL/MariaDB mirror

Installation

1. Place the application in the web root.
2. Make the runtime directories and configuration writable by the web-server user.
3. Configure Apache with the included .htaccess, or adapt nginx-example.conf.
4. Open admin.php and sign in with the initial password changeme123.
5. Immediately change admin.password in the Configuration tab.
6. Open Plans & Platform to configure tiers, Mailgun, Stripe, optional voice transcoding, and MySQL mirroring.

The SQLite schema and default Free, Plus, and Pro tiers are created automatically on first use.

For a simple shared-hosting deployment:

chmod 0777 db archive uploads/voice

For a managed server, ownership is preferable:

chown -R www-data:www-data db archive uploads/voice
chmod -R 0770 db archive uploads/voice

Replace www-data with the PHP-FPM or web-server account. SQLite must be able to create the database plus -wal and -shm sidecar files. When the application directory itself is restricted, database.main_db may be an absolute path to a writable persistent directory.

Default Tiers

The defaults are starting points and are fully editable in the dashboard.

Feature	Free	Plus	Pro
Recording status send/view	No	Yes	Yes
Automatic voice send	No	Yes	Yes
Automatic voice play	No	Yes	Yes
Custom username color	No	Yes	Yes
Text archive	30 days	90 days	365 days
Text export	Yes	Yes	Yes
Voice archive/export	No	Yes	Yes
Email 2FA	No	Yes	Yes

Administrators can assign a tier directly from Admin > Users > Edit > Tier Override. The override grants that tier's features without changing Stripe billing data and remains in effect until it is changed back to Follow Stripe / billing status.

Mailgun

Configure these fields under Admin > Plans & Platform:

• API key
• Sending domain
• From address
• API base, normally https://api.mailgun.net/v3
• EU API base, when applicable: https://api.eu.mailgun.net/v3

The reusable mailer is in lib/mailer.php. It sends verification links and codes, limits verification attempts, and sends 2FA codes with a direct link to the authentication screen.

Mailgun API reference: https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/messages/post-v3--domain-name--messages

Stripe

1. Create recurring Stripe Prices for the paid tiers.

2. Enter each price_... ID in the matching dashboard plan.

3. Enter the Stripe secret key and webhook signing secret.

4. Add this webhook endpoint:

   https://YOUR-DOMAIN/YOUR-PATH/api/stripe-webhook.php

5. Subscribe the endpoint to:

   • checkout.session.completed
   • customer.subscription.created
   • customer.subscription.updated
   • customer.subscription.deleted
   • invoice.paid
   • invoice.payment_failed

Checkout is rejected until the account has a verified email. Stripe customer and subscription IDs, status, current period end, cancellation state, and selected plan are synchronized into SQLite.

When subscriptions.enabled is off, plans and checkout are hidden from non-subscribers. Existing Stripe customers retain Billing Portal and cancellation access.

Stripe references:

• https://docs.stripe.com/api/checkout/sessions/create
• https://docs.stripe.com/webhooks

Voice Compatibility and FFmpeg

Browsers that support WebM continue to record WebM by default. Safari and iPhone may record MP4/AAC instead, which the upload API also accepts.

Under Admin > Plans & Platform > Voice Transcoding / FFmpeg, configure:

• Enable or disable server-side transcoding
• FFmpeg executable name or absolute path
• M4A / AAC-LC, recommended for audio-only playback on iPhone, Safari, Android, and desktop
• MP4 / H.264 + AAC, which adds a tiny black H.264 video track for systems requiring a conventional MP4
• Audio bitrate and conversion timeout
• Whether to retain the original source when conversion fails

When transcoding is disabled, the original browser recording is stored. WebM remains the preferred default on supported browsers. When enabled, new uploads are converted; existing voice files are unchanged.

Archives

The application archives daily messages into:

archive/{year}/{month}/{day}.sqlite

The public legacy archive browser now redirects to the authenticated My Archive view. Users can only query their own sent messages within their plan retention window. Free users receive text history only; voice history and voice export require the corresponding plan entitlements.

MySQL/MariaDB Mirror

SQLite remains the required primary database. The optional mirror imports the main database and all archive databases into sqlite_mirror_rows using:

• source database path
• source table
• row key
• JSON row data
• synchronization time

Set a PDO MySQL DSN in the dashboard, enable the mirror, and optionally enable automatic import. A manual Run MySQL Mirror Now action is also available.

Embedding

<link rel="stylesheet" href="/chat/assets/css/cyberchat.css?v=20260609.3">
<div id="my-chat" style="width:100%;height:600px"></div>
<script>
  window.CYBERCHAT_BASE = '/chat';
</script>
<script src="/chat/assets/js/cyberchat-app.js?v=20260609.6"></script>
<script>
  CyberChat.init('#my-chat');
</script>

See embed-example.html for a complete example.

Main Files

admin.php                    Administrator dashboard
bootstrap.php                Configuration, schema, auth, plans, archives, stats
config.json                  Runtime settings and service credentials
api/account.php              Email, color, and 2FA settings
api/archive.php              Private personal archive and export
api/auth.php                 Registration, login, 2FA, sessions
api/billing.php              Stripe checkout, portal, and cancellation
api/messages.php             Text, voice, polling, and recording presence
api/stripe-webhook.php       Stripe event synchronization
assets/js/cyberchat-app.js   Browser application
lib/mailer.php               Reusable Mailgun sender
lib/stripe.php               Stripe REST client and subscription sync
lib/voice_transcoder.php     Optional FFmpeg voice compatibility pipeline
lib/mysql_mirror.php         Optional SQLite-to-MySQL mirror

Production Security

• Change the default administrator password and statistics salt.
• Serve the application only over HTTPS.
• Keep .htaccess rules enabled or reproduce all deny rules in the web-server configuration.
• Never expose config.json, db/, archive/, or lib/.
• Use separate Stripe test and live webhook secrets.
• Restrict admin.php by IP or additional HTTP authentication where practical.
• Back up SQLite databases and voice files together.