Directory Structure

Root Structure

/                                   # Whizzybase Root
├── index.php                       # Single entry point — all requests flow through here
├── .htaccess                       # Apache config + PHP prepend (platform_init + load_function)
├── .env                            # Environment variables (DB creds, app mode, etc.)
├── .env.example                    # Template for .env
├── composer.json                   # Optional: PHP dependencies & autoload
├── README.md                       # Platform overview
├── changelog.md                    # Version history
│
├── apps/                           # Installed applications (sandboxed)
├── apis/                           # HTTP-accessible API endpoints
├── plugins/                        # Platform extension modules
├── framework/                      # Core platform code (do not modify)
├── global_functions/               # Platform-level utility functions
├── themes/                         # Layout partials & frontend assets
├── pages/                          # Standalone pages (no app shell)
├── scripts/                        # Server, client & background scripts
├── storage/                        # Runtime-generated files
├── config/                         # Platform-wide configuration
├── cron_jobs/                      # Scheduled job definitions
└── install_wb_framework/           # Platform installation scripts

index.php — Entry Point

The single entry point for all requests. Routes based on URL parameters.

Routing Logic

App Rendering Flow

include(themes/navbar.php)
include(themes/header.php)
→ Fetch and execute requested app page
include(themes/footer.php)

.htaccess — Server-Level Bootstrap

Configures Apache and sets PHP auto_prepend_file to automatically load before every request:

apps/ — Installed Applications

Every application is sandboxed in its own directory. Apps are self-contained and independently installable.

apps/
└── attendance/                     # Example app
    ├── manifest.json               # App metadata: name, version, dependencies, entry points
    ├── roles.json                  # Role & permission definitions (developer defaults)
    ├── settings.json               # App configuration defaults
    ├── README.md                   # App documentation
    │
    ├── index.php                   # Default page (loaded when no page is specified)
    ├── report.php                  # Additional app page
    ├── dashboard.php               # Additional app page
    │
    ├── services/                   # System APIs — functions other apps can call
    │   └── fetch_attendance.php    # e.g., fetch_attendance() returns attendance data
    │                               # Executed by phantom functions for inter-app communication
    │
    ├── installation_files/         # Runs during app install
    │   └── install.php             # Creates DB tables, seeds data, registers roles
    │
    └── app_functions/              # App-specific helper functions
        ├── local/                  # Private to this app only
        └── global/                 # Registered to global scope (accessible by other apps)

Key Files

apis/ — HTTP-Accessible Endpoints

Public-facing REST/API endpoints accessible directly via URL. These are not the same as app services/.

apis/
├── global/                         # Platform-wide APIs (not tied to any app)
│   └── fetch_attendance.php        # domain.com/apis/global/fetch_attendance.php
│
└── app_backend_name/               # App-specific public APIs
    └── get_report.php              # domain.com/apis/app_backend_name/get_report.php

APIs vs Services

plugins/ — Platform Extensions

Plugins extend platform-wide functionality. Unlike apps (which are user-facing), plugins provide backend capabilities that apps and the platform consume.

plugins/
├── mailer/
│   ├── manifest.json
│   ├── init.php                    # Plugin bootstrap — registers hooks/functions
│   └── send_mail_outlook.php       # Outlook mail integration
│
└── oauth/
    ├── manifest.json
    ├── init.php
    └── oauth_handler.php           # OAuth flow handler

Apps vs Plugins

framework/ — Core Platform Code

framework/
├── platform_init.php               # Prepend script — sanitizes requests, sets constants
├── load_function.php               # Registers loadfunction() — the universal loader
│
├── cli/                            # Command-line tools for platform management
│
├── db_ops/
│   └── db_pdo.php                  # PDO database connection layer
│
├── functions/                      # Core loadable functions
│   ├── DataBridge.php              # Database abstraction (GlideRecord-style CRUD)
│   ├── DataBridgeSchema.php        # Schema management (create/alter tables)
│   ├── DataBridgeMigration.php     # Versioned migration manager
│   ├── SessionManager.php          # Session read/write/group operations
│   ├── sweetalert1.php             # SweetAlert v1 integration
│   ├── sweetalert2.php             # SweetAlert v2 integration
│   ├── bootstrapv3.php             # Bootstrap v3 loader
│   └── bootstrapv4.php             # Bootstrap v4 loader
│
├── phantom/                        # Phantom function system
│   ├── executepreScript.php        # executepreScript("script_name") runner
│   ├── phantomAJAX.php             # Custom AJAX handler for background scripts
│   └── UserClass.php               # getUserID(), getCurrentUser(), etc.
│
├── preprocessors/                  # Request preprocessing (sanitize, validate)
├── postprocessors/                 # Response postprocessing (logging, notifications)
│
├── migrations/                     # Platform-level DB migrations
└── data_seeds/                     # Seed data for fresh installations

How loadfunction() Works

loadfunction("DataBridge");         // Loads framework/functions/DataBridge.php
loadfunction("session");            // Loads framework/functions/SessionManager.php
loadfunction("bootstrapv4");        // Loads framework/functions/bootstrapv4.php

global_functions/ — Platform Utilities

Platform-level helper functions that admins or integrators can add or modify. Unlike framework/functions/ (which is locked), this directory is extensible.

global_functions/
├── mailer/
│   └── send_mail.php               # loadfunction("send_mail")
│
└── notification/
    └── send_notification.php        # loadfunction("send_notification")

framework/functions/ vs global_functions/

themes/ — Layout & Frontend Assets

UI layout partials and shared frontend resources.

themes/
├── default/                        # Default theme
│   ├── navbar.php                  # Top navigation bar
│   ├── sidebar.php                 # Side navigation
│   ├── header.php                  # Page header (meta, CSS includes)
│   └── footer.php                  # Page footer (JS includes, closing tags)
│
├── css/                            # Shared stylesheets
├── js/                             # Shared JavaScript
└── assets/                         # Images, icons, fonts

pages/ — Standalone Pages

Independent pages that render without the app shell (no navbar, header, footer wrapping). Full-page renders.

pages/
├── login.php                       # Login page
├── signup.php                      # Registration page
├── forgot_password.php             # Password reset
└── error.php                       # Error/404 page

pages/ vs App Pages

scripts/ — Executable Scripts

Three distinct script types, each with a defined contract.

scripts/
├── server_scripts/                 # Run on server (PHP/other languages)
│   └── cleanup_temp.php
│
├── client_scripts/                 # Run in browser (JavaScript)
│   └── form_validator.js
│
└── background_scripts/             # AJAX endpoints via phantomAJAX (PHP → JSON)
    └── check_notifications.php

Script Contracts

storage/ — Runtime Files

All platform-generated files at runtime. Nothing in this directory is committed to version control.

storage/
├── uploads/                        # User-uploaded files
├── cache/                          # Cached data (compiled templates, query cache)
├── logs/                           # Platform and app logs
│   └── 2026-03-01.log
├── tmp/                            # Temporary files (cleared periodically)
└── app_assets/                     # App-specific media and static files

config/ — Platform Configuration

config/
├── config.php                      # Loads .env, sets platform constants
├── database.php                    # DB connection settings
└── permissions/                    # Global role definitions
    └── platform_roles.json         # Platform-level roles (superadmin, admin, user)

cron_jobs/ — Scheduled Tasks

cron_jobs/
├── daily_cleanup.php               # Remove expired temp files
├── sync_attendance.php             # Nightly attendance sync
└── send_digest.php                 # Weekly email digest

install_wb_framework/ — Platform Installer

install_wb_framework/
└── install_scripts/
    ├── setup_database.php          # Create platform tables
    ├── create_admin.php            # First admin user
    └── verify_requirements.php     # Check PHP version, extensions, permissions

JSON-Default, DB-Override Pattern

This pattern applies across the platform for roles, settings, and any configurable value.

Developer authors → JSON file (ships with app)
User customizes  → DB override (stored at runtime)
Runtime reads    → Check DB override → if null → fall back to JSON default
Reset            → Delete DB overrides → JSON defaults restored

Example Lookup

get_config("attendance", "max_leave_days")
// 1. Check DB: SELECT value FROM config_overrides
//    WHERE app='attendance' AND key='max_leave_days'
// 2. If null: Read apps/attendance/settings.json → max_leave_days
// 3. Return value

Same pattern applies for get_role_permissions("attendance", "viewer").

Quick Reference — Where Things Go

Getting Started — 5 Things You Need to Know