Sop To Internal Docs Expansion 2026 05 06
SOP to Internal Docs Expansion — 2026-05-06
Update Summary
Took the contents of Tadabase Standard Operating Procedures (SOP).md at the docs root and expanded each section into a full technical reference inside exported-articles/internal. Each new doc was researched directly against the appifany2 codebase (and the pdf-forms sibling repo), then enriched with gotchas, env flags, schedule wiring, and failure modes that are not in the SOP itself.
Why
The SOP is a list of headings — operationally useful only to people who already know the system. The team needs a single, indexed, technical source-of-truth that answers "what does this command actually do, where is it scheduled, and what bites us when we run it?" without needing to grep the codebase every time. The internal-docs portal already houses similar deep-dives (App Lifecycle, Backups, Workflows, AI Queue), so this work expands that library to cover the remaining SOP topics.
Files Created
Path (relative to exported-articles/) | Covers |
|---|---|
internal/Code & Implementation/codebase-repositories.html | Plain-English map of every repo in the SOP's "Codebase Repositories" list — what each does, where it runs, and the gotchas we keep re-learning. |
internal/Subscriptions & Plans/users-and-subscriptions-management.html | Delete Apps, Update User Status, Update Totals — the SOP's "Users & Subscriptions" section, with status meanings, related commands, and lifecycle-guard interactions. |
internal/Backups & Restores/automated-app-backups.html | Hourly backup schedule, the BackupAppWithQueueJob flow, S3 bucket detail, the backup-apps-by-id env-driven schedule, and full purge-backups reference. |
internal/App Management/moving-apps-between-databases.html | php artisan move-app-new options, what the job does internally, and the SSL / Global Accelerator / Load Balancer / Target Group routing topology from the SOP's Moving Apps tables. |
internal/Code & Implementation/health-checking-and-database-processes.html | server-health-checker Cloud Run service (URL, headers, reboot loop) and the kill-db-process command + HTTP killer endpoint. |
internal/App Management/database-cleanup-jobs.html | Every nightly cleanup job: record logs, delete logs, page versions, workflow versions, page views, user tokens, backup purge — schedules, plan keys, the 7-day buffer, and which SOP-listed jobs are aspirational vs. actually scheduled. |
internal/Workflows & Automation/scheduled-tasks-architecture.html | End-to-end flow of customer scheduled tasks: Cloud Scheduler → API endpoint → queue → RunTbTaskJob. Cron secret, force-trigger params, heartbeat strategy. |
internal/PDFs/pdf-forms-infrastructure.html | How Appifany2 wires the standalone pdf-forms Laravel app — config keys, staging/live URLs, plan gates, the iframe post-message protocol, session-cookie pitfalls. |
internal/Fields/troubleshooting-equations-and-debug-flags.html | Every debug flag in Appifany2 (DEBUG_FORMULA_UPDATE_FORM, TB_ENABLE_SQL_QUERY_LOG, enable_task_debug, enable_record_debug, settings.app._debug.enable, settings.tlogs) — what each captures, where the output lands, and an equation-debug playbook. |
Research Method
- Read
Tadabase Standard Operating Procedures (SOP).mdend-to-end and extracted every distinct operational topic. - For each topic, located the canonical source in
appifany2:- Console commands →
app/Console/Commands/ - Schedule registrations →
app/Console/Kernel.php - Cron HTTP routes →
routes/api.php+app/Http/Middleware/TbCronCheck.php - Cleanup script bodies →
app/Console/Commands/RunNewScript.php - Debug logging →
app/library/TbLogHelper.php+app/Providers/AppServiceProvider.php+app/Models/AppFieldQuery.php - PDF Forms wiring →
config/settings.phpin Appifany2 +pdf-forms/README.md
- Console commands →
- Cross-referenced existing internal docs (App Lifecycle, Backup/Restore, Workflows, AI) to avoid duplication and keep style/structure consistent (TL;DR → tables → gotchas).
- Captured plan retention keys, env flags, default values, and the most common ways each command fails — these are what the SOP omits.
Coverage vs. SOP Sections
| SOP Section | Covered by new doc |
|---|---|
| Codebase Repositories | codebase-repositories.html |
| Users & Subscriptions | users-and-subscriptions-management.html |
| App Backups (Creating Automated Backups, Purging Backups) | automated-app-backups.html |
| Moving Apps + SSL/LB topology | moving-apps-between-databases.html |
| Health Checking (EC2, Database Processes) | health-checking-and-database-processes.html |
| Clean Up (Record/Delete/Page Version/User Token/Backup purges) | database-cleanup-jobs.html (+ automated-app-backups.html for the backup-purge specifics) |
| Database Checks (kill processes) | health-checking-and-database-processes.html |
| Scheduled Tasks | scheduled-tasks-architecture.html |
| PDF Forms | pdf-forms-infrastructure.html |
| Staging / Sandbox debug flags & Troubleshooting Equations | troubleshooting-equations-and-debug-flags.html |
Codebase Changes
No code changes were made — this is a pure documentation expansion. The Appifany2 source was read-only research material. Every doc cross-references the file paths it draws from, so a reader can jump from doc → code in one step.
Possible Follow-ups
- The SOP marks
remove_webhook_logs,remove_pageview_logs, andremove_email_logswith ❌ — they are listed but not registered inKernel.php. Confirm whether they should be wired up; if so, that's a one-line schedule addition + ensuring each case exists inRunNewScript.php. - The cron secret in
TbCronCheck.phpis hardcoded. Consider moving to env so rotation doesn't require a deploy (out of scope for this docs pass; flagged here so it doesn't get lost). - The
PurgeBackupCommandstring-matches bucket namestadabase-secure-backup-2019/tadabase-secure-backup-2023in path stripping. Worth refactoring to a config array before adding a third bucket.
We'd love to hear your feedback.