Wolverine WISE Developer Documentation

Technical handoff for DCTS IT and authorized maintainers. Updated October 15, 2026.

Purpose and data boundaries

Wolverine WISE is an educational electronic medical record simulation. Patients and clinical scenarios must be fictional. Student and instructor identity accounts are real school account data and require appropriate access controls. This software is not for clinical care. Do not import real medical records.

This public guide contains no credentials, environment values, account exports, database backups, or private hosting configuration. Obtain repository and hosting access from the application owner through the school's approved process. The owner must maintain the private operational handoff separately, including recovery contacts and backup retention requirements.

Source and system architecture

Source repository: dcts-choate/wolverine-wise on GitHub. Repository permission is separate from application access. The application lives in application/; root Markdown files record requirements and DEVELOPMENT_LOG.md records implementation and deployment history. Confirm the deployed commit or release manifest before maintenance. A GitHub push does not deploy the website.

The application uses PHP 8.3 or newer within the supported Composer constraints, Laravel 13, Blade server-rendered templates, plain JavaScript, and shared CSS. Composer lock files are the authority for installed dependency versions. Production uses MySQL; automated feature tests use an isolated in-memory SQLite database. Dompdf renders PDFs and Picqer generates Code 128 barcodes. Existing shared screens load assets directly from public/css and public/js.

Local setup

Use a development checkout and fictional data only. Install PHP and Composer with the extensions required by the lock file. Use composer check-platform-reqs to identify missing extensions; do not bypass platform requirements in production. SQLite development needs its PDO driver; MySQL deployment needs its PDO driver. PDF/image handling also depends on the installed Composer platform requirements.

From application/:

composer install
# Copy .env.example to .env using your operating system's file tools.
php artisan key:generate
# Configure an isolated development database in .env before the next step.
php artisan migrate
php artisan serve --host=127.0.0.1 --port=8000

For SQLite, create the configured empty database file before migration if necessary. The optional local preview requires both APP_ENV=local and WISE_LOCAL_PREVIEW=true; it must remain disabled in production. The public guest tour is a separate fixture-only feature and does not use this login shortcut. Never copy a production database into local preview without an approved, appropriately de-identified process.

Node.js is needed for JavaScript tests and, when changing the Vite-managed asset pipeline, its build. Use the package lock and npm ci, then npm run build for that pipeline. Changes to the directly loaded CSS and JavaScript files must be deployed to the active public asset directory.

Authentication, roles, and authorization

School email/password login, email verification, active-account checks, and a per-session simulation acknowledgment protect normal use. Student safety requirements apply through middleware. Program memberships and record policies control clinical access. Check authorization in controllers and queries, not just visible links.

Administrators manage accounts and system feedback. Administrator status does not automatically grant clinical access. Administrator roleplay switches to a separate Student or Teacher identity for the selected program; it is an authenticated, writable classroom workflow with attributed changes. Return to Administrator before reviewing the cross-program feedback inbox.

Students can work within their permitted records and program. Teachers have classroom review and account oversight capabilities; these do not imply unrestricted access to other specialties. Preserve ownership, group access, program scopes, signed-record restrictions, and version checks when extending functionality.

Public routes and guest preview

/guest opens the read-only Student/Instructor Preview. /guest/{program}/{section} selects a supported program and example workflow. role, patient, and guide query parameters choose an allowlisted role, fictional patient, and guide visibility. /guest/{program}/sample.pdf downloads a rate-limited report generated exclusively from curated fixtures.

App\Support\GuestPreview is the fixture source. Guest pages do not log in a shared user, look up actual patients, or call clinical mutation controllers. Disabled controls explain the signed-in workflow. Guest PDF exports are a deliberate public exception because they contain only curated demonstration content; actual clinical PDF routes remain protected. Never replace guest fixtures with production database queries. Test both anonymous visitors and signed-in users entering the tour.

/developer-documentation is this public guide. /up is the framework health endpoint; it is not a substitute for checking authenticated workflows, database availability, or email delivery.

Data integrity and reports

Migrations are versioned. Use transactions for changes that also create history or audit events. Records use revision/version checks to reject stale updates. Signed encounters preserve their original documentation; corrections use addenda. Apply the same authorization to exports as on-screen records.

Four-digit Patient IDs are separate from permanent eight-digit scan codes. USB scanners behave as keyboard input in the unified lookup field. Do not recycle permanent scan-code mappings or derive clinical access from a barcode. The scanner is not an authentication mechanism. Patient PDF barcode images are 7.5 mm high; chart barcodes display at 238 pixels wide with quiet zones preserved. Physical scan testing remains necessary after changing print scale.

Store canonical timestamps in UTC and present them through the school-time helper. Display conventions are MM/DD/YYYY with Eastern time and EST/EDT. Preserve date-only values without timezone shifts. PDF output includes an educational-simulation label on every page.

Height and weight are entered and displayed in inches and pounds. Workout loads use pounds. Stored height/weight and workout load values remain metric for historical compatibility; VitalSigns converts at request and presentation boundaries. Do not relabel stored values or convert historical snapshots in place. Entry forms carry an imperial-unit marker to reject stale metric forms. BMI is entered by students, not calculated automatically. Historical body-fat values remain stored and are never interpreted as BMI.

Exercise & Sports Science charts have a Rehabilitation tab listing permitted patient-linked plans. Its combined PDF selects the latest accessible encounter by visit date (then ID) and latest linked plan by creation date (then ID). Both records must exist, and each keeps its own author, dates, and saved version. It does not imply the records were created together. Existing ownership/group/program restrictions apply.

Feedback and email

The administrator Feedback link brings together system reports and instructor questionnaires. System reports support status changes, attributed responses, and version checks; students see their own submissions and program teachers see authorized program reports. General system reports are saved in-app and do not currently send email notifications.

Instructor questionnaires are stored separately. Email is attempted after the submission is saved, so transport failure does not discard the feedback. A sent timestamp indicates that the mail transport accepted the send operation, not confirmed inbox delivery. Review saved submissions first, then private application logs and cPanel mail delivery tools if notification delivery is questioned. Do not paste credentials or entire production logs into support tickets.

Testing and release checks

From the application directory:

php artisan test
php vendor/bin/pint --test
php artisan view:cache
php artisan route:list

JavaScript checks are standalone .cjs files in tests/js; run each relevant file with Node (for example, node tests/js/intake-scanning.cjs). Test authorization, validation, transactional history, stale edits, and exports for changed workflows. Guest tests must prove that classroom tables are not queried or changed and that real clinical routes remain inaccessible to anonymous visitors. Review desktop and narrow layouts, keyboard navigation, and PDFs visually. Clear local compiled views with php artisan view:clear when needed.

Deployment through cPanel

1. Review and test the intended commit. Keep .env, credentials, dependencies, database files, logs, generated exports, and backup archives out of Git. Push reviewed source and documentation to GitHub.
2. Identify the correct WISE cPanel account, domain document root, active application directory, and PHP runtime. Do not assume the CLI PHP matches the website handler. Do not modify unrelated hosting accounts.
3. Create a private source/assets backup and a consistent database backup outside the web root. Verify backup completion and record checksums. Use restrictive file permissions and school-approved retention. Never place backups in public_html.
4. Upload a manifest-checked release into private staging. Install Composer dependencies from the lock file when they change, using production options such as --no-dev --prefer-dist --optimize-autoloader. Validate platform requirements for the production runtime.
5. Use a brief maintenance window for non-atomic updates. Preserve the existing .env, application key, storage data, and required writable directories. Apply reviewed migrations with php artisan migrate --force only after backup and compatibility review.
6. Deploy both private application files and any separate public assets. The document root must expose only the public entry point and assets; application source, configuration, vendor files, and storage must remain outside public access. Preserve and verify the existing front-controller paths if the public directory is separate.
7. Refresh route/view/config caches as appropriate for the release and actual environment. Bring the app out of maintenance mode even if a deployment step fails. Verify deployed hashes, HTTP responses, sign-in, permissions, and changed user workflows. Record the release and backup location privately.

Production must use APP_ENV=production, APP_DEBUG=false, the correct HTTPS APP_URL, production database/mail configuration, and WISE_LOCAL_PREVIEW=false. Do not regenerate APP_KEY on an existing installation. Environment configuration and secret rotation require a coordinated operational procedure.

Backups and rollback

Back up application source, public assets, the database, required private storage, and securely protected configuration. Database and source backups must correspond to a known release. Establish and document backup scheduling, retention, recovery objectives, and an actual restore test with IT; the application does not itself guarantee automated backups.

For a code-only rollback, restore the corresponding source and public assets, refresh caches, exit maintenance mode, and verify behavior. A schema-changing release needs a reviewed database recovery plan. Never blindly run migrate:fresh or destructive rollback commands on production. Restoring an older database can discard subsequent work; coordinate downtime and recovery with the owner.

Troubleshooting and maintenance

Check dependency updates in a test environment and review relevant security advisories before production updates. Review account access and mail configuration under school policy. Actual queue-worker and scheduler requirements depend on deployed configuration and features; inspect routes/console.php, queued jobs, and the production queue driver before adding cron jobs or workers. Keep this guide and DEVELOPMENT_LOG.md current with architectural and operational changes.

Profile photos, login badges and wristband sheets (October 28, 2026)

Migration 28 adds private profile-photo paths and encrypted badge secrets with unique SHA-256 lookup hashes and a rotation version. Badge login uses 24 cryptographically random decimal digits (Code 128 C), never patient IDs. The guest POST is CSRF protected and limited to 10 attempts per minute per IP. Codes are excluded from session old input and model serialization. Only active, verified students/instructors with valid memberships can use badges; administrators and roleplay identities are excluded. Normal login event/session regeneration, acknowledgment and safety requirements remain. Issuance/replacement is explicit, locked/versioned and audited without recording the secret. Replacement immediately invalidates the prior code. Treat PDFs as credentials. Email/password remains supported.

Photos are validated, cropped and reencoded as 480-pixel JPEGs with metadata stripped. GD is required; EXIF enables phone orientation correction. Storage is the local private disk, served through authorized responses only. Preserve storage/app/private/profile-photos during releases and backups. Users upload/remove their own photos; instructors may print student badges via Students > student activity. Portrait and landscape PDFs use actual 3.375 by 2.125 inch pages (243x153 points, rotated for portrait), with green/gold school branding. Program identity is selected from the badge subject's assigned primary program or first valid membership, never from request parameters.

The PLS-102W print view uses landscape Letter, a four-column/five-row grid of 2.5 by 1 inch labels and one 8.3125 by 0.75 inch wristband. Geometry now follows the owner-supplied PLS-102W tamper-evident template: remove the 36pt printer-mark margin, retain the 792x612pt Letter trim area. Labels start at (36,36) points, 180x72 points; wristband starts at (96.75,537.75), size 598.5x54 points. The patient chart downloads the PDF directly in one click, with no guide or offset controls. Filenames include the patient ID, first initial, and last name. Program logo dimensions preserve their original aspect ratio. Each label and wristband includes the authenticated exporter's assigned primary-program logo (or first assigned program), never a client-supplied program override. Export stays within authenticated simulation/safety/patient access middleware. Never put real patients on these sheets.

Administrator-owned teacher roleplay may issue/download badges for real student accounts; authorization checks the active verified administrator owner and attributes issuance to that owner with the persona ID recorded. Roleplay identities remain ineligible for badge login; student roleplay cannot issue peer badges. Missing profile photos use an embedded silhouette.

Printable forms and classroom quarterback example (October 28, 2026)

Printable Forms is available beside Start Intake on the workspace to enrolled students, instructors, and administrators. The library contains 19 blank patient worksheets, with search/program/category filters and contextual links on patient workflows. Account, profile, administrative, software feedback, and system-operation worksheets are excluded. Downloads use authenticated, verified, simulation-acknowledged, safety-qualified routes. No saved patient or account data is read into these blank PDFs.

The maintained static catalog is resources/forms/catalog.json; app/Support/PrintableForms.php expands live intake, vital-sign, clinical-entry, registration, care, and timeline definitions. Keep catalog entries aligned when changing page-specific forms. The PDF repeats a 180x72-point (2.5x1-inch) patient-sticker box, student/class/date fields, patient ID, simulation notice, form identifier, revision date, and page number on Letter pages. Print at actual size to preserve sticker dimensions. Blank worksheets and saved-record exports are separate actions.

The explicit classroom fixture uses patient ID 0017 and scenario key fictional-quarterback-0017-v1. All birthdate, measurements, symptoms, injuries, and clinical content are invented and labeled accordingly. The character name is Josh Allen; public nonmedical sports references (number 17 and Wyoming Cowboys) are sourced from https://www.buffalobills.com/team/players-roster/josh-allen/ . No real injury history was imported. The fixture contains 12 read-only teaching encounters across five programs, four shared chart entries, and three read-only rehabilitation plans. It does not alter patient 0001.

Run php artisan wise:quarterback-scenario ADMIN_ID to inspect; append --apply only after a private database backup and explicit scenario authorization. Installation is transactional and idempotent. If 0017 is occupied by a different scenario, the old chart is assigned an unused ID and archived with an audit; its work and scan-code identity remain intact. The new scenario receives a new scan code. Migration 29 adds is_teaching_sample to workout_plans: enrolled Exercise & Sports Science students can view/export sample plans, while update/group assignment/restoration remain denied even for teachers. Other programs cannot access these plans. New personal plans keep existing permissions.

Migration 30 simplifies the quarterback fixture wording to the standard simulation label. Exact text replacements apply only to this scenario, increment record versions, and preserve prior text in audit history. The special chart/PDF banner is removed.