Technical Requirements Document

SYSTEM DOCUMENT · CURRENT IMPLEMENTATION

This document describes the runtime, architecture, data, security, and operational requirements for the GastosWise web application.

Audience: developers, maintainers, and deployment operators Status: implementation-aligned technical baseline

1. Runtime and platform

Web server: Apache HTTP Server with PHP support. The documented local setup uses XAMPP on Windows.
PHP: PHP 8.0 or later, with PDO and the PDO MySQL driver enabled. The application uses native PHP and does not require a PHP framework.
Database: MariaDB or MySQL with InnoDB and utf8mb4 support. The checked-in schema creates the gastoswise database.
Browser: a modern browser supporting standard HTML, CSS, JavaScript, and browser APIs used by the interface.
Configuration: database connection values can be supplied through GASTOSWISE_DB_HOST, GASTOSWISE_DB_PORT, GASTOSWISE_DB_NAME, GASTOSWISE_DB_USER, and GASTOSWISE_DB_PASSWORD.

Request entry: index.php initializes the application and dispatches public, authenticated, and role-protected page requests using the page query parameter.
Shared services: includes/ provides bootstrap, session and authentication helpers, CSRF verification, request utilities, and the shared student/admin layout.
Business logic: classes/DecisionSupport.php scores, classifies, ranks, and allocates expense recommendations; database operations use PDO and shared repositories/helpers.
Interfaces: student and administrator pages are server-rendered PHP and HTML, with custom CSS and vanilla JavaScript; JSON/action endpoints and form handling are implemented in api/actions.php.
State: application records are stored in MariaDB/MySQL. Profile pictures and application backup files use the application’s storage directories.

Import database/database.sql for a new installation. Apply the numbered SQL migrations in order when upgrading an existing schema.
Persist users, budgets, expenses, transactions, savings goals and contributions, comparisons, recommendation sessions and details, categories, decision criteria, settings, and activity logs in relational tables.
Use InnoDB foreign keys and ownership-aware queries to preserve relationships and scope a student’s financial records to that account.
Use PDO prepared statements for database queries, and retain actual transactions separately from planned expenses and recommended allocations.
Keep application logs, profile images, and backups in their designated storage locations; deployment must provide appropriate filesystem permissions and backup protection.

Require authentication for student and administrator workspaces; enforce role checks on administrator-only operations and pages.
Store passwords using PHP’s password_hash and verify them with password_verify. Regenerate the session identifier on login.
Use session-only, HTTP-only, SameSite=Lax cookies, strict session mode, and secure cookies when HTTPS is active.
Require and verify CSRF tokens on state-changing forms. Escape untrusted text in HTML output and parameterize database values.
Keep database credentials outside source control and use a dedicated least-privilege database account in hosted deployments; serve hosted traffic over HTTPS.
Validate profile image uploads and expose an image only to an authenticated user. Keep runtime errors out of browser responses and record server-side errors in protected logs.
Preserve the application’s response security headers and Content Security Policy when adding external assets or integrations; review policy changes before deployment.

Score expenses from importance, urgency, deadline proximity, and essentiality using administrator-configured weights.
Require configured weights to total 100% and classification thresholds to remain in descending order.
Rank eligible pending expenses and keep allocations within the available budget. Partial funding is permitted only for an expense marked divisible.
Save the criteria snapshot with each recommendation so historical output can be interpreted using the configuration active when it was generated.
Do not treat a recommendation as a transaction or infer actual spending from an allocation.

Configure the application timezone and database connection for the deployment environment.
Provide write access only where needed for logs, profile pictures, and backups. Prevent direct web access to protected storage and configuration files.
Use the supported database schema and migrations, and take protected backups before schema changes or restoration operations.
Do not expose the XAMPP development database account or a temporary preview tunnel as a production service. Hosted deployments require a hardened server, restricted database account, TLS, and an operational backup and recovery process.
Set deployment-specific retention, monitoring, recovery objectives, and availability targets before production use; those values are not defined by the current application.

Run PHP syntax checks on changed PHP files.
Run tests/run.php to verify decision-support, persistence, ownership, password hashing, and related database behavior.
Run tests/http_smoke.php with Apache and MariaDB available to verify registration/login, role restrictions, student workflows, reports, and administrator workflows.
For changes to page routes or navigation, verify signed-in student and administrator access, including mobile navigation and direct route requests.
For schema changes, verify a clean database import and the documented migration path on an existing installation.