Build Tally

The build, in order

1. 1

   Form definition and admin auth

   hideshow

   An admin you can log into with the token, and forms you can create.

   1. 1.1Create the project and the tables

      forms (id, slug, title, description, accent, published, notify_email, webhook_url), fields (id, form_id, position, kind, label, help, required, options JSON, deleted), responses (id, form_id, submitted_at, ip_hash, user_agent_class), answers (id, response_id, field_id, value, file_path).

      terminalcopy

      mkdir forms && cd forms && git init && npm init -y && npm pkg set type=module
      npm install express@4 better-sqlite3@13
      mkdir -p data/uploads && cp .env.example .env

   2. 1.2Implement token login

      POST the token; compare with a constant-time function; set an HttpOnly cookie. Never accept the token in a URL.

   3. 1.3Build form CRUD in /admin

   done when · tick each as it passes

   • A wrong token is refused
   • A right one persists across a page load as a cookie
   • The token never appears in a URL or a log line
   • A form can be created, renamed and deleted

   next phase
2. 2

   Field editor

   hideshow

   Every field kind, reorderable, soft-deleted so old responses keep rendering.

   1. 2.1Add, edit and soft-delete fields with up/down buttons for order

      Kinds: text, textarea, email, select, checkbox, file. Explicit buttons work on mobile and are testable; drag can come later.

   2. 2.2Store select options as JSON and validate them on save

      At least one option, no duplicates, trimmed.

   done when · tick each as it passes

   • A form with one of every kind saves and reloads identically
   • Reordering persists
   • A soft-deleted field disappears from the public form but still shows in past responses

   next phase
3. 3

   Public form rendering

   hideshow

   Accessible, single column, works without JavaScript, unpublished forms 404.

   1. 3.1Build GET /f/:slug

      Labels with for attributes, one question per block, single column, mobile-first. Unpublished forms return 404.

   2. 3.2Add the accent custom property, dark mode and a designed thank-you page

      prefers-color-scheme with the same custom properties overridden.

   done when · tick each as it passes

   • No accessibility violations
   • Every field keyboard reachable with a focus ring
   • Submitting with JavaScript disabled works
   • An unpublished slug returns 404

   next phase
4. 4

   Submission and validation

   hideshow

   Validate on the server against the stored definitions and never lose what someone typed.

   1. 4.1Implement POST /f/:slug with server-side validation against the stored fields

      Required, email shape, select values drawn from the stored options, length caps. Never trust the client copy of the rules.

   2. 4.2Preserve every typed value on a validation error

      Re-render with inline errors and the answers intact; losing a long answer is the worst thing this app can do.

   3. 4.3Store one answers row per field with the field_id

      So a renamed or soft-deleted field still renders in past responses.

   done when · tick each as it passes

   • A valid submission stores one response with one answer per field
   • An invalid one re-renders with every typed value intact
   • A forged select value outside the stored options is rejected

   next phase
5. 5

   File uploads

   hideshow

   Safe uploads: streamed, capped, sniffed, stripped.

   1. 5.1Stream multipart to UPLOAD_DIR/<slug>/ under a generated name

      Cap at MAX_UPLOAD_MB while streaming; check MIME against the decoded header; strip EXIF from images with sharp.

      terminalcopy

      npm install busboy@1 sharp@0.35.3

   2. 5.2Never serve UPLOAD_DIR directly; serve via an admin-only route

   done when · tick each as it passes

   • An oversize file is refused before it is fully read
   • A .php renamed to .png is refused
   • Two uploads with the same original name coexist
   • Uploads are not reachable without admin auth

   next phase
6. 6

   Spam controls

   hideshow

   Honeypot, minimum fill time, per-IP limits in SQLite.

   1. 6.1Add a CSS-hidden honeypot and a signed minimum-fill timestamp requiring 3 seconds
   2. 6.2Rate limit 10 submissions per IP per hour in a SQLite table

      Survives restarts, unlike memory.

   done when · tick each as it passes

   • A filled honeypot shows thanks and stores nothing
   • A sub-3-second submission is refused
   • The eleventh in an hour is refused while another IP succeeds

   next phase
7. 7

   Notifications and export

   hideshow

   Email and webhook that can never make a respondent wait, and a streamed CSV.

   1. 7.1Send email over SMTP_URL and POST the webhook, fire-and-forget with a timeout
      terminalcopy

      npm install nodemailer@6

   2. 7.2Build the admin response table and streamed CSV export

   done when · tick each as it passes

   • A submission still stores and shows thanks with SMTP unreachable and the webhook timing out
   • A real email arrives readable on a phone
   • A 10,000-row CSV exports without memory growth

   next phase
8. 8

   Deploy

   hideshow

   Live, backed up including uploads, documented.

   1. 8.1Add /healthz, systemd, Caddy and a backup of data/

      Files deploy/forms.serviceCaddyfile

   2. 8.2Write the README

      .env keys, the Caddy snippet, where the database and uploads live, and the honest line that Tally's free tier is generous and the reason to build this is data ownership.

      Files README.md

   done when · tick each as it passes

   • A restore brings back both responses and files
   • A reader goes from clone to a published form using only the README

   next phase