forms/docs/implementation_plan.md

Forms Response Collection System Implementation Plan

Goal Description

Create a simple, Microsoft Forms-like response collection system using flat files (no database) with HTML, PHP, JS, and CSS. The system will support creating forms via drag-and-drop, storing data on a shared hosting environment, capturing answers with user memory, sending native PHP emails, and viewing responses through a secure admin link.

Proposed Architecture

Since there is no database, we will use JSON files to store forms and responses.

Data Structure (/data directory)

• /data/forms/<form_id>.json - Stores form structure (questions, types, creation details).
• /data/answers/<form_id>_<answer_id>.json - Stores individual submitted responses.

Key Workflows

1. Form Creation (create mode)

• Drag-and-drop UI to assemble questions (text, multiple choice, etc.).
• Admin can optionally provide an email address to receive the admin link.
• Save creates a new <form_id> and a unique <admin_token>.
• Redirects to a success page showing the public link to share and the secret admin link.

2. Form Answering (answer mode)

• User accesses the public link (answer.php?id=<form_id>).
• Prompts for Name and Email (optional). These are saved in localStorage / cookies to remember the user on future visits.
• Displays questions for answering.
• Prevents double submissions (checked via localStorage & matching data).
• Upon submit, sends a confirmation email (if email was provided) with the Q&A summary using PHP's native mail().
• Post-submit view shows a read-only list of submitted answers with options to "Add another answer" (with different identity) or "Edit response".

3. Admin View (admin mode)

• Accessible via admin.php?id=<form_id>&token=<admin_token>.
• Displays a table/list of all submitted responses for that specific form.

Appearance

• The UI will faithfully implement the intranet dark theme specified in docs/style_system.md (e.g., #2f3541 deep surface area, #cac300 accents).

Proposed Changes

Assets

[NEW] assets/css/style.css

Implementation of the portable intranet style system spec (variables, spacing, grids, dark theme, typography).

[NEW] assets/js/create.js

Drag-and-drop logic for adding questions. Generating form payload for submission.

[NEW] assets/js/answer.js

Client-side logic for caching Name/Email, validating submissions, and enforcing single-submit-per-person logic.

Pages & Logic

[NEW] index.php

Landing page with a split choice: "Create a Form".

[NEW] create.php

The drag and drop editor view and the PHP handler for saving the form JSON.

[NEW] answer.php

The page that loads a specific form's JSON and renders it for the end user to fill out.

[NEW] submit.php

PHP endpoint that receives a form submission, saves the answer JSON, and dispatches native PHP notification emails.

[NEW] admin.php

The private dashboard for viewing form submissions. Loaded via a secret token.

[NEW] data/.htaccess

A security lock to prevent direct public access to raw JSON files.

Open Questions

[!WARNING]
Before proceeding, please confirm the following details:

1. Drag-and-Drop Complexity: Are simple text inputs and text areas enough for questions, or do you require multiple-choice capabilities (radio/checkbox/dropdowns) in the form builder for version 1?
2. Double Submission: Since there are no user accounts, is remembering the user via cookies/LocalStorage sufficient to prevent double submissions?
3. Validation: Should we use external JS libraries for the drag-and-drop (like SortableJS) via CDN, or should I write a lightweight native HTML5 Drag and Drop implementation?

Verification Plan

Automated/Manual Testing

• Create a new form with two custom questions and enter an admin email.
• Verify that a JSON structure correctly saves to disk.
• Navigate to the answering link in an incognito window.
• Fill out the Name, Email, and answers. Submit and ensure local data remembers the submission.
• Verify rendering of the completed answers.
• Hit the "Reload" button and verify double submission logic flags the active session.
• Validate that the CSS applied matches the docs/style_system.md values properties exactly using browser dev tools.
• (Local email debugging will log to file or use standard syslog if native mail() is tricky to verify externally).