Help / TRD
Technical Requirement Document
PrintWise — implementation architecture and operational requirements
Prepared 5 November 2026 · Based on the implemented PrintWise build.
1. System architecture
PrintWise uses server-rendered PHP with a MySQL/MariaDB relational database. index.php dispatches page routes and request handlers; includes/ contains authentication, calculations, decision logic, management, reporting, documentation and backup/restore functions. There is no application framework or Node.js runtime dependency.
The browser renders semantic HTML and the existing CSS/JavaScript. JavaScript enhances the assessment wizard, debounced preview, saved-quote comparison, charts, confirmation controls, theme selection and responsive sidebar; core submission remains server validated.
2. Runtime and hosting requirements
| Component | Requirement |
|---|---|
| Server | PHP 8.2+; MySQL or MariaDB with InnoDB; Apache-compatible cPanel hosting and functioning private-directory rules. |
| PHP extensions | PDO MySQL, mbstring, sessions, JSON/iconv; ZIP for application archives; GD for report-logo handling. Development tests also use cURL/DOM and a Chromium browser. |
| Client | Current desktop/mobile browser supporting native forms and JavaScript. Responsive navigation adapts at the established 800px mobile breakpoint. |
| Visualization | Chart.js 4.4.3 loaded from jsDelivr. Google Fonts enhances typography; local data tables/native text provide fallback content. |
| Private configuration | config/config.local.php supplies deployment-specific DB connection settings and optional private backup directory. It is not distributed with real secrets. |
| Storage | Writable PHP sessions and owner-controlled private backup/staging storage outside public document roots; adequate disk, memory, time and upload quota. |
| Transport | HTTPS with a valid certificate. Secure cookie behavior is enabled when the request is HTTPS. |
3. Main modules and interfaces
| Module / route | Responsibility |
|---|---|
| auth.php / login, register, logout | Current user lookup, role guards, password verification, session lifecycle and persistent authentication throttling. |
| assessment.php + calculator.php | Input validation, server preview, eligible-shop calculation, saved results and transactional assessment creation/update. |
| dss.php + decision_views.php | Preference normalization, weighted ranking, explanation, budget alternatives and what-if comparison. |
| management.php + shop_management.php | Owned history, version rendering, shared filters/pagination, user controls, shop/service/rate administration. |
| analytics.php | Period-scoped saved-quote aggregates, recent assessment activity, usage series and estimated-cost distributions. |
| pdf.php + reports route | Saved-assessment/summary PDF generation and filtered HTML print reports. |
| application_restore.php + backup_validation.php | Private signed ZIP backup/staging/apply/recovery and constrained SQL restore validation. |
| manual.php + requirements.php | Existing help manuals, Help hub, PRD/TRD rendering, and visible dedicated demo-login instructions. |
4. Database entities and relationships
| Table | Purpose / important relationship |
|---|---|
| users | Identity, unique email, password hash, user/admin role, active flag and timestamps. No plaintext password column. |
| printing_shops | Shop identity, active state, demo key, duplex capability and optional configured metadata. |
| printing_services | Finishing names/types/fees and active/demo metadata. |
| shop_services | Many-to-many shop/service assignments with availability flags. |
| shop_rates | Paper-specific B&W/color prices and effective dates; unique shop/paper pair. |
| print_assessments | Owner and requirements, status, preference JSON and parent_assessment_id. Parent is a logical application-enforced revision link. |
| assessment_quotes | Assessment/shop foreign keys, printing/finishing/total cost, budget flag and complete details_json snapshot. |
| recommendations | Chosen shop, assessment link, explanation and budget-match flag. |
| assessment_versions | Full previous assessment/quote/recommendation JSON, actor and timestamp before an update. No cascading foreign keys, intentionally preserving archived history. |
| rate_history | Old/new paper prices and responsible administrator metadata. Historical entries are reviewed alongside shop pricing. |
| activity_logs | Actor/name snapshot, action, details, IP and timestamp. User removal does not require losing its name snapshot. |
| backup_records | Database/application/restore metadata, filename, result and timestamp. |
| auth_attempts | Hashed IP/identity keys, attempt counts and rolling authentication windows. |
| notifications | Schema-supported user notifications; no broad real-time notification service is claimed. |
| system_settings | Permitted stored setting keys and values; distinct from private deployment constants. |
5. Assessment transaction and consistency
- Quantities and budget have validated numeric bounds; paper/color/duplex choices are allowlisted. Cost calculation uses integer centavos to avoid floating-point boundary errors.
- Creation stores requirements, preference metadata, all eligible quote snapshots and the chosen recommendation in one transaction.
- Update locks the owned completed assessment, checks the submitted expected snapshot, rejects a parent with child revisions, stores its full previous state in assessment_versions, replaces its current quotes/recommendation, and commits together.
- A new revision uses a separate assessment ID and validates/locks an owned completed parent. Archival sets the existing deleted status instead of cascading away quote history.
- Later shop/price changes do not alter saved quote values or snapshotted names. An explicit assessment update intentionally recalculates using current rates while retaining the older snapshot.
6. Authorization, passwords and sessions
- require_login verifies a current enabled account; require_admin verifies the admin role. Assessment queries bind the owner ID, including preview, view, update and PDF access.
- Registration uses password_hash(PASSWORD_DEFAULT); authentication uses password_verify. This is one-way password hashing, not reversible password encryption.
- Authentication rate limits are stored in auth_attempts: identity and IP windows apply over 15 minutes. Login/registration use a session arithmetic CAPTCHA.
- Login regenerates the session ID and CSRF token. Cookies are HttpOnly, SameSite=Lax and Secure on HTTPS; inactivity beyond 1,800 seconds clears protected session state.
- POST mutations verify CSRF. Confirmation is handled at form submission, including keyboard submission. Rendered values are escaped and SQL inputs parameterized.
- User-role changes use InnoDB locking, re-read active admin authority and protect self-lockout/the final active admin. Existing-password editing is not part of the user management form.
7. Querying, pagination and analytics
- History, users and shops use SQL LIMIT/OFFSET with 10-row pages; activity uses 15. New management lists clamp invalid/out-of-range page inputs and apply stable primary-key tie breaks.
- Assessment filters validate actual calendar dates and allowlisted color/status values. Shared scope construction retains owner restrictions and matching report criteria.
- Analytics aggregate only completed saved assessments within the selected date window. Personal dashboards scope to the logged-in user; admin overview can aggregate all users and filter recommended shop.
- Saved recommended quote totals provide estimated spending/averages. Potential savings compares highest eligible saved quote with the recommended quote. These values are not accounting records.
8. Reports and document generation
- HTML reports use print-specific CSS, browser print preview, organization heading, generated date/time and relevant filter summaries.
- Assessment PDFs use owned saved snapshots. Admin summary PDFs apply the validated report filters when opened from the filtered report screen.
- The application timezone is Asia/Manila. Report organization text comes from SCHOOL_NAME in deployment configuration.
- The proposal uses the same structured requirement text as the PRD/TRD webpages, preventing disagreement between online requirements and submitted document content.
9. SQL backup and restore
- Admin SQL export includes current schema/data. Backups contain private records/hashes and must be kept outside public access.
- Controlled SQL restore accepts PrintWise-generated backups under 20 MB, checks existing schema compatibility and restricts statements/literal values. It is not a general migration or arbitrary SQL-import interface.
- SQL restore may drop/recreate application tables as part of recovery and is not fully transactionally reversible because database DDL can commit. Make a fresh export and use maintenance/staging before recovery.
- Additive migrations and sample-data SQL are imported separately through phpMyAdmin. Do not restore a fresh full project export over an existing live database for an ordinary code update.
10. Application ZIP backup and restore
- Application backups use an explicit runtime-file allowlist. A manifest includes SHA-256 hashes, release contract and normalized database-schema fingerprint; an HMAC uses a private installation key.
- The validator requires the complete supported file list and signature. It rejects traversal/absolute paths, duplicates, symlinks/special files, encryption, checksum changes and incompatible contract/schema.
- Limits are 50 MiB compressed, 100 MiB expanded, 20 MiB per entry and 200:1 compression ratio. Host PHP/post/time/memory limits may be stricter.
- Files stage privately, preview is session/admin-bound and expires after 30 minutes, and execution rechecks CSRF, confirmation, live admin authority, checksums and permissions.
- Before replacement the app creates a private recovery ZIP and rollback copies. Atomic per-file replacement attempts rollback on failure; incomplete recovery leaves a maintenance marker. Hosting-level maintenance is still needed to avoid in-flight mixed versions.
- All configuration, secrets, uploads, storage, server rules, SQL and setup/test tools are excluded. Legacy unsigned archives, other installation keys and incompatible schemas require manual recovery.
11. Deployment, migration and demonstration data
- Keep live configuration/server rules/uploads. Back up files and SQL, enter maintenance, import the additive management migration once, replace compatible application files, verify and release maintenance.
- migration-management.sql creates only assessment_versions with IF NOT EXISTS. It does not alter existing accounts or require replacing the database.
- The dedicated public student demo is a normal user, provisioned by a separate additive SQL file with a hashed initial password. Existing accounts/admin passwords are not reset or published.
- Administrator and student sample datasets together provide 72 labeled fictional completed assessments, 216 saved quotes and 72 recommendations across six months. Inactive fictional shops keep sample prices out of new real comparisons.
- The proposed hosted URL is https://system.pakongadame.site/. Local code changes, cPanel SQL import and assets-folder sharing are separate deployment/submission tasks; local success does not automatically update hosting.
12. Verification and known operational limits
- Existing local regression evidence covers authentication, ownership/admin guards, CSRF, CRUD, migration preservation, history/filter pagination, reports, browser navigation/layout and isolated restore checks.
- The demo-data test verifies original-row preservation, idempotent import, missing-account no-op, consistent quote arithmetic, chart variety, owner scope and browser chart/history rendering.
- Submission-specific checks verify Help/PRD/TRD access, shared content, demo-login UI/authentication, normal-user privilege denial, dataset counts and printable requirements.
- Actual cPanel permissions, quotas, PHP configuration and hosted demo-account provisioning remain host-owner checks. Concurrent administrator races and a forced partial-write/failed rollback have not been load/fault tested.
- HTTPS evidence must come from a verified public request and certificate check, not a fabricated browser padlock. No unverified screenshot is presented as proof of a live production restore.