# Project Collaborations

## Update an existing installation

1. Back up your current application and database.
2. Copy the updated application files to the existing SLPS installation. Preserve your server's environment configuration and live `storage/private` contents; do not overwrite live uploaded projects with storage from this development archive.
3. Run `database/migrations/20261015_project_collaborations.sql` in the SLPS database using phpMyAdmin or your MySQL client. The migration creates two new tables and preserves previous submissions. For a fresh installation, the tables are also in `database/slps_schema.sql`.
4. Use PHP 8.1 or later with MySQLi. Enable PHP ZIP for ZIP import and export. Keep the private storage protections described in the existing deployment documentation; the web server must be able to write there.
5. Refresh the page (Ctrl+F5). Open **Project Collaborations** from the dashboard or sidebar.

## Administrator workflow

Create a project with a title and description. Open **Team members**, search by name or username (at least two characters), and add the required students. You can remove members here later. All administrators can manage school collaboration projects. Students see only projects to which they have been assigned. HOD and staff roles do not inherit access to private student teams.

## Team workflow

Open your assigned project. Use **New file** or **New folder** to build a structure directly in the workspace. Nested paths such as `src/components/header.html` automatically create parent folders. Use **Upload files / ZIP** for individual files or a ZIP archive. Leave the destination empty for the project root, or name a folder. ZIP archives are validated and expanded into that destination. Multiple uploads run sequentially; if a later upload fails, earlier successful uploads remain saved and the dialog reports the completed count. Existing paths are protected: edit existing text files or upload into a different folder.

Click a file to view or edit UTF-8 source (up to 1 MB). Save with the button or Ctrl/Cmd+S. Binary and larger files are downloadable. Download ZIP exports the current complete workspace. Source code is stored privately and never executed by this module.

## Attribution and concurrent changes

Each file and folder shows its last-change date/time and contributor. Changing a nested file also updates its ancestor folders. Recent activity shows the latest 100 file/folder events; the complete file activity history is retained in the project manifest. Dates are stored in UTC and displayed in the viewer's local timezone. The workspace refreshes its file list every 15 seconds while visible and without unsaved edits; **Refresh files** retrieves it immediately.

Writes require the workspace revision read by the client; text saves also require the file's content hash. A concurrent update returns a conflict instead of overwriting another contribution. Unsaved editor text remains in place. Copy your pending edits before discarding/reopening a conflicting file, then reapply them to its current contents. This workspace provides shared files and an activity log; it does not implement Git branches, commits, pull requests or merge tooling.

Limits: 25 MB per ZIP, 10 MB per individual file, 100 MB and 3,000 entries per project, 25 path levels. Configure PHP and web-server request limits to allow a 25 MB upload plus multipart overhead.

Old submission menu entries now open Project Collaborations; their previous assessment records and APIs are preserved. Student Projects remains a separate module with its existing design and behavior.

## Verification

`node tests/project_collaborations_ui.cjs` exercises the controller and DOM bindings using a mock API. `php tests/project_collaborations_storage.php` verifies real filesystem behavior, attribution, nested folders, unsafe paths and conflicts. In the target installation, verify login as administrator and two assigned students, an unassigned student's denied access, team removal, ZIP import/export and concurrent edits. This package was prepared without access to your running database or authenticated server.

Completed checks in the development environment: PHP 8.3 syntax checks on every new/changed PHP entry point, filesystem/storage regression tests, and the Node controller integration test passed. Live MySQL authorization and browser visual checks require the target environment.

## October 16: separate pages and line history

Opening Project Collaborations displays only the school project library. Selecting a project navigates to its own full-width file-manager page. Selecting a file navigates to a dedicated editor page. Back controls return to the containing folder or the school library; the browser Back/Forward buttons and bookmarked project/file links work normally. Project-wide activity is available from a modal in the file manager.

The editor has a separate **Line changes** panel. Every newly saved text edit records the contributor, UTC timestamp, revision, old/new line ranges, and references to the before/after source snapshots. **View changes** displays removed and added code with line numbers. Clicking a current revision’s line range jumps to it in the code editor. Historical line numbers refer to that historical revision. Notification text and audit details are never inserted into source code.

New contributions are checked every 15 seconds, including while you have unsaved edits; notification refresh never replaces your editor contents. **Reload file** loads the latest version with the existing unsaved-change guard. Conflicting saves are rejected. History shows the latest 100 contributions for this file; the complete history remains stored. Each preview is limited to 400 lines and 2,000 bytes per displayed line. Extensive repetitive rewrites may be grouped as a changed block to keep diff calculations bounded.

Older contributions remain visible with their author and timestamp. Line-level details begin with edits saved after this update; previous versions did not record the before/after relationship. No additional SQL migration is required if Project Collaborations has already been installed. Preserve your live database, environment configuration and private project storage during the source-file update.

Additional checks passed: separate library/project/editor route tests, line attribution and preview wiring, notification refresh while editing, stale-file save preservation, PHP line-diff reconstruction tests including 300 randomized cases, and large-file diff checks. Live server/MySQL and visual browser validation remain to be completed in the deployment environment.

## Nested explorer and context actions

The project explorer now shows a real parent/child tree with short names, yellow folder icons and chevrons. Click a chevron to expand or collapse a folder, or a folder name to view its contents. Files appear inside their parent folder. Collapse all resets the explorer to the project root. Searching reveals matching branches without discarding your previous expansion choices.

Right-click a folder or use **Folder actions** to create a file, create a subfolder, upload into it, or delete it. The creation dialog shows the selected parent, so you can enter just the new name. Right-click files to delete them. Keyboard users can focus an item and press Shift+F10 for the menu, navigate menu options with arrow keys, and close with Escape.

Deletion requires confirmation and includes all descendants of a folder. The project root cannot be deleted. It uses the revision captured when the confirmation opened; concurrent changes reject the deletion until the list is refreshed and the action is reviewed again. Deletions are recorded with author, timestamp, removed paths and item count. Historical content blobs are retained for audit records; deletion removes items from the current project workspace. Existing member/admin access rules apply to these operations. No new database migration is required.

## Project rename/delete, administrator names and department student lists

Apply `database/migrations/20261016_collaboration_management.sql` before using this update. Fresh installations include it in the full schema. It adds a per-administrator department setting and a record of deleted projects. Existing `admins.department_id` or `users.department_id` values are imported when those columns exist. Where no department is assigned, open Team members, select Your department and Save department once. This is saved for the signed-in administrator.

Administrators can right-click project cards to Rename project or Delete project. Rename requires a nonempty name; Delete requires confirmation. A deleted project disappears from active listings and members cannot open it. Stored files, membership and audit records are retained; deletion does not erase historical source material. Rename and delete reject stale project names.

Team members automatically loads active students from the signed-in administrator’s department. The initial list needs no search input; all matching students are available in pages of 100 through Load more students. Search filters within the same department. Adding a student is also checked against that department on the server, preventing an out-of-department ID from being added manually. Existing assigned students remain listed and removable.

Project administrator displays the creator’s current full name; missing, blank, literal null or undefined names fall back to their username, then account ID. The display is labelled Project administrator on cards, the file manager and the member form.

Automated PHP checks and controller tests passed for this update, including right-click rename/delete and immediate student loading. The migration and database-backed authorization still require validation on your deployment. Preserve the live configuration and private project files when copying updated source.
