GENFLUME TEST — CPANEL DEPLOYMENT GUIDE
Version 1.0 | PHP + MySQL | OpenAI only

WHAT YOU GET
User signup/login, password recovery, optional email verification, four AI tools,
recent chat memory, request history, and an admin usage/cost dashboard.
No subscriptions, payments, credits, Node.js, Docker, Composer, or terminal setup.

RECOMMENDED HOSTING
• PHP 8.3 or 8.4, 64-bit. Code requires PHP 8.0+; use a supported PHP release.
• Required extensions: PDO, pdo_mysql, cURL, OpenSSL, mbstring, JSON, session.
• MySQL 5.7+ or MariaDB 10.4+, with InnoDB and utf8mb4 support.
• Apache 2.4 or LiteSpeed with .htaccess and mod_rewrite support.
• HTTPS certificate (cPanel AutoSSL). Outbound HTTPS to api.openai.com:443.
• PHP mail() working on the host for password reset and verification messages.
• Suggested memory_limit: 128M or more; max_execution_time: 70 or more.
  The upstream HTTP timeout is 45 seconds; host/proxy limits also apply.

INSTALL — NO TERMINAL NEEDED
1. Open cPanel. Select PHP 8.3 or 8.4 in MultiPHP Manager / Select PHP Version.
   Enable the extensions listed above. Enable SSL for your domain.
2. Open MySQL Databases / Manage My Databases. Create a NEW empty database.
3. Create a MySQL user and a strong password.
4. Add that user to the database with ALL PRIVILEGES.
5. Open File Manager. Go to the domain's document root, usually public_html.
   For a subdomain, use its assigned document root shown in cPanel Domains.
   Use an empty folder or back up an existing website before replacing anything.
6. Upload GenFlume-Test-cPanel.zip and extract it. The ZIP contains index.php,
   .htaccess, app/, assets/, and storage/ directly, with no extra parent folder.
   Enable “Show Hidden Files” in File Manager so you can see .htaccess.
   Remove the uploaded ZIP from the public folder after extracting.
7. Open https://yourdomain.com/install immediately after uploading.
   The first person to finish installation becomes admin, so do not leave an
   uninstalled copy unattended on a public domain.
8. Enter Database Host (normally localhost), the FULL prefixed database name,
   FULL prefixed database username, and database password from cPanel.
   Example: cpaneluser_aitest, not just aitest.
9. Enter your admin name, email, password, and confirmation. Check Website URL.
   Use the final HTTPS address; include /folder if installed in a subfolder.
10. Click Install platform. Tables and protected configuration are created.
    Installation then locks itself. /install cannot run again while the
    configuration exists. There is no default admin password.
11. Sign in at https://yourdomain.com/admin using the admin account you created.
12. Open OpenAI Settings. Paste your OpenAI API key in the password field.
13. Select a model or type its API model ID. The default is gpt-4.1-mini.
    The model must support text output through OpenAI's Responses API and be
    available to your OpenAI project. Specialized audio/image models are not
    supported. ChatGPT subscriptions do not provide API billing credit.
14. Enter the current official INPUT and OUTPUT USD prices per 1 MILLION tokens.
    Also enter the cached-input rate, or leave it blank to apply the normal
    input rate to all input tokens. Check prices when changing the model.
    Official pricing: https://developers.openai.com/api/docs/pricing
    Default example: gpt-4.1-mini — input 0.40, cached input 0.10, output 1.60.
    These are editable examples, not a permanent pricing guarantee.
15. Check “I checked the official prices for this model” and click Save.
    No AI requests run until a key is saved and prices are confirmed.
16. Open /signup. Create a NORMAL USER account, separate from the admin account.
    Email verification is OFF by default, so you can test immediately.
17. Log in at /login. An admin account cannot be used as a normal user account.
18. Open Title Generator, enter a topic, and click Generate.
19. Try Description Generator and both AI companion chats.
    Girlfriend and Wife have separate recent conversation memory.
20. Return to /admin. You can remain signed in as admin and user in one browser;
    if an old form says it expired, refresh it after signing in or out.
21. Open API Usage and filter by user, tool, or UTC date.
22. Open Users → View user to see their requests, tokens, costs, prompts, replies,
    signup date, and last login. Test with 3–5 accounts to compare usage.

IMPORTANT URLS
Installation:       /install
Admin login:        /admin (redirects to /admin/login when signed out)
User signup:        /signup
User login:         /login
User dashboard:     /dashboard
Forgot password:    /forgot-password
Reset password:     /reset-password?token=... (from the email)
Deployment guide:   /guide
Key, model, prices: /admin/openai
Limits and email:   /admin/settings
Total API cost:     /admin
User costs:         /admin/users → View user
Request ledger:    /admin/usage
Error logs:         /admin/errors
If installed in /aitest, prepend /aitest to all these paths.

EMAIL SETUP
Create an address such as noreply@yourdomain.com in cPanel Email Accounts.
Set Admin → Settings → From Email Address to that address. This small version
uses PHP mail(), not an external SMTP library. Ask your host to enable local
mail sending and configure SPF/DKIM if messages do not arrive.
Test Forgot password with a registered user before enabling verification.
The recovery form also supports admin accounts. Reset links expire in 1 hour;
verification links expire in 24 hours. Links are one-time tokens, stored hashed.
New password changes invalidate other sessions. Requesting another email
invalidates the previous link of the same type.
A successful mail() result means accepted by the host, not guaranteed delivery.
Failed submissions appear in Error Logs. For privacy, Forgot password returns
an identical message whether or not an email address is registered.
Turning verification ON blocks AI access for every unverified account, including
existing users. Users can resend verification from Profile. Keep it OFF until
email delivery works. Basic signup/login works without any mail configuration.

HOW TOKEN AND COST TRACKING WORKS
OpenAI calls happen only in PHP on the server at https://api.openai.com/v1/responses.
The app uses store=false, standard service tier, and no billable built-in tools.
Only the current prompt, tool instructions, and recent chat context are sent.
The user's name and email are not automatically included in model prompts.
API-reported usage is stored; the app does not estimate tokens from character
counts. Input tokens include system/tool instructions and re-sent chat messages.
Output counts may include internal reasoning or other non-visible model tokens.

Without a separate cached-input price:
  Input cost = input tokens / 1,000,000 × input price
  Output cost = output tokens / 1,000,000 × output price
  Total cost = input cost + output cost

With a cached-input price:
  Input cost = (input tokens - cached tokens) / 1,000,000 × input price
             + cached tokens / 1,000,000 × cached-input price
  Output and total formulas stay the same.

Prices are stored with each request. Editing a model or rate affects future
requests only. Calculations use integer fixed-point arithmetic on 64-bit PHP;
costs are stored to 12 decimal places and shown with at least 6. This keeps
small amounts visible. All currencies are USD, not PKR. All dates use UTC.

These are estimates of this app's text-token charges, NOT an invoice or a live
OpenAI billing balance. Taxes, prepaid credit, discounts, price changes, unusual
model pricing tiers, cache-write fees, and other API activity are not covered.
Choose a model with ordinary flat text-token pricing. If a provider charges
additional token categories or context-dependent rates, compare directly with
its dashboard. Official usage/billing is the final authority.

REQUEST STATUS AND LIMITS
• completed: a usable response and valid usage were saved; counts as a generation.
• incomplete: the API returned valid usage but did not finish a usable response.
  Reported tokens and cost are saved, but it is NOT counted as a generation.
  Check the output token cap, particularly when using reasoning models.
• failed: a definite rejection, such as invalid key, unavailable model, or 429.
  Not a successful generation. No token usage is invented.
• unknown: a timeout/network/server failure or invalid usage response. The API
  may still have consumed tokens. Local cost is not known. Review OpenAI usage.
• pending: a request is running or was interrupted before its outcome was saved.
  Persistent pending rows need reconciliation against the OpenAI dashboard.

Total API Requests counts all submitted attempts. Total Generations counts only
completed requests. Token/cost totals include any recorded incomplete usage.
The admin overview flags pending/unknown requests so missing usage is visible.
No automatic API retries: a timeout can occur after OpenAI processes a request.
Check History before manually retrying. A repeated request ID cannot trigger
another API call; the same completed response is returned again when possible.

Per-minute limits count all admitted API attempts in a rolling 60-second window.
Daily limits reset at 00:00 UTC and count completed, incomplete, pending, and
unknown requests. Definite failed requests do not consume the daily allowance.
0 means unlimited daily requests. One AI request runs per user at a time, even
across different browsers/sessions. This also keeps chat context in order.
These are per-user test controls, not an overall spending cap. Open signup can
create additional accounts. Configure a project budget/alerts at OpenAI too.

CHAT AND HISTORY
Each character remembers its own last 12 messages (six user/AI exchanges).
New chat clears that character's current context; it does not remove History.
Both characters are fictional AI, with distinct friendly, non-explicit prompts.
Full request history is retained so you can inspect and compare test costs.
Admins can read request histories. Avoid entering sensitive personal data.
Long-running deployments should periodically archive old history through normal
database backups; no automatic history deletion or scheduled job is required.

SECURITY AND FILES
Passwords: password_hash/password_verify. SQL: PDO prepared statements.
Forms: CSRF tokens. Sessions: HttpOnly, SameSite=Lax, Secure over HTTPS,
2-hour inactivity timeout, session rotation and invalidation on password change.
Roles: admin and user accounts use separate tables and server-side checks.
A logged-in user cannot use admin pages without separate admin credentials.
Suspension is checked server-side; it signs out the user's other sessions.
Account login, signup and mail flows also have database-backed abuse throttles.

The API key is AES-256-GCM encrypted in the settings table. The random encryption
key and database credentials live in storage/config.php (created by installer).
PHP access guards and .htaccess rules protect app/ and storage/ from web access.
Saved secrets are never filled into forms or returned by API error responses.
Protect your hosting account and backups: access to both config and database
can decrypt the API key. Do not delete or regenerate the existing app_key.

Expected permissions: folders 755, regular files 644; generated config.php 600
when your hosting runs PHP as your cPanel user. storage/ must be writable by
that PHP user. Do not set everything to 777. If config cannot be read, ask the
host for owner-only PHP-compatible permissions rather than exposing it.
Deleting a user removes identity, chat messages, reset tokens, prompts, and
responses. Anonymous usage rows remain to preserve total cost accounting.

The database has eight small gf_-prefixed tables: users, admins, settings,
api_usage, chat_messages, error_logs, password_resets, and rate_limits.
Generation history is stored directly in api_usage to avoid duplicated data.
rate_limits is used for login/signup/email abuse controls. Expired throttle rows
are cleaned periodically during normal requests. No cron is needed.

BACKUP / MOVE
Back up both the MySQL database and the site files, especially storage/config.php.
Keep backups private. To move domains/folders, restore both, then edit only
base_url and base_path in storage/config.php to match the new HTTPS location.
Do not change app_key. Never rerun the installer over an existing database.

TROUBLESHOOTING
404 on /install or /admin:
- Confirm .htaccess was extracted beside index.php and mod_rewrite is enabled.
- Confirm you used the correct domain document root and no extra ZIP folder.

500 immediately after uploading:
- Select PHP 8.3/8.4 and enable all required extensions.
- Check ownership/permissions and cPanel Errors.
- Some hosts prohibit the Options directive. Ask the host to permit the shipped
  rules or handle Options -Indexes -MultiViews at the virtual-host level.
  Do not remove the app/storage protection rules.

Database connection fails:
- Use cPanel-prefixed database and user names. Add the user with ALL PRIVILEGES.
- Normally the host is localhost; confirm with your hosting provider.
- If installation partially created tables before failing, use a new empty
  database. Never delete tables belonging to an existing working installation.

API 401: update the key in OpenAI Settings.
API 429: wait, or check quota/billing/project rate limits in your OpenAI account.
Invalid model: use a Responses-compatible model your project can access.
Timeout/network: ask the host to allow outbound HTTPS and check its timeout.
Never turn off TLS certificate verification to fix an API connection problem.
Incomplete response: increase Maximum Output Tokens and check model suitability.
Unknown/pending: reconcile against OpenAI's dashboard; avoid blind retries.
Mail missing: check From address, spam, SPF/DKIM, PHP mail availability, Error Logs.
Form expired: refresh after signing in/out, password changes, or long inactivity.

OFFICIAL REFERENCE PAGES
https://developers.openai.com/api/docs/guides/text
https://developers.openai.com/api/docs/guides/token-counting
https://developers.openai.com/api/docs/guides/prompt-caching
https://developers.openai.com/api/docs/models/gpt-4.1-mini
https://developers.openai.com/api/docs/pricing