WhatIDo/PRD.md

PRD.md — Product Requirements Document: WhatIDo

Version: 1.0
Status: Active
Last Updated: 2026-09-09

---

1. Product Summary

WhatIDo is a self-hosted accounting system for an educational center (youth club, coding school, art studio). It tracks attendance, student project works, group photo chronicles, and publishes public showcase pages via share links. Designed for zero-public-IP deployment using Tailscale Funnel.

Target Users:

• Administrators/Teachers — manage groups, students, entries, files, settings
• Parents/Students — view public showcase pages (read-only, no auth)

Core Value: Simple, secure, zero-infrastructure publishing. Runs on any Linux box with Docker.

---

2. Functional Requirements

2.1 Groups Management

ID	Requirement	Priority
GRP-1	CRUD groups: name, schedule (day of week, start/end time), branch assignment	Must
GRP-2	Group cover photo (auto-set from latest group photo or manual)	Must
GRP-3	Photo chronicle per group: upload, caption, date taken, pagination	Must
GRP-4	Active groups endpoint (filters by current day/time in Europe/Moscow)	Must
GRP-5	Branches (locations): CRUD with address, phone; groups link to branch	Should

2.2 Students Management

ID	Requirement	Priority
STU-1	CRUD students: name, group assignment	Must
STU-2	Batch assign students to group	Should
STU-3	Unique name constraint per student	Must

2.3 Journal Entries (Attendance + Project Works)

ID	Requirement	Priority
ENT-1	Create entry: student name (free text), group, description, photo, multiple files	Must
ENT-2	List entries with filters: group, date range, student name, search (name/description), deleted flag	Must
ENT-3	Update entry: description, photo, files	Must
ENT-4	Soft delete / restore (deleted_at timestamp)	Must
ENT-5	Trash view: list deleted entries, restore, permanent delete	Must
ENT-6	Pagination (limit/offset) + total count	Must
ENT-7	Anti-spam: min interval between entries per student (configurable, default 30 min)	Must
ENT-8	Files attached to entry: upload (max 10 files, per-file and total size limits from UPLOAD_FILE_LIMIT_MB/UPLOAD_TOTAL_LIMIT_MB), download by token	Must

2.4 Files Management (Centralized)

ID	Requirement	Priority
FIL-1	List all files with filters: search, student, group, date range	Must
FIL-2	Detached files tab: files with entry_id = NULL	Must
FIL-3	Detach file from entry (sets detached_at)	Must
FIL-4	Delete file (removes from disk + DB)	Must
FIL-5	Public file access by token (image inline, others download)	Must
FIL-6	File size display in list	Should

2.5 Share Links (Public Showcase Pages)

ID	Requirement	Priority
SHR-1	Create share link: name, optional group, student, date range, anonymize names, expiry (default 7 days), optional password	Must
SHR-2	List/Edit/Delete share links (admin)	Must
SHR-3	Public page (/s/:token): shows filtered entries + group photos	Must
SHR-4	Password protection on share link (bcrypt)	Must
SHR-5	Expiry enforcement (410 Gone after expires_at)	Must
SHR-6	Anonymize student names on public page (Student 1, Student 2...)	Should
SHR-7	Group photos on public page (latest 12)	Should
SHR-8	File download from share page (validates link + password + filters)	Must

2.6 Dashboard & Statistics

ID	Requirement	Priority
DSH-1	Stats cards: total entries, trash count, groups, unique students	Must
DSH-2	Active groups right now (schedule match)	Must
DSH-3	Activity chart: entries per day (last 14 days)	Should
DSH-4	Top students by entry count	Should
DSH-5	Recent entries list (last 10)	Should

2.7 Settings

ID	Requirement	Priority
SET-1	Footer left/right text (displayed on public pages)	Must
SET-2	Anti-spam interval (minutes)	Must
SET-3	Admin-only access	Must

2.8 Backup & Restore

ID	Requirement	Priority
BAK-1	Download full backup: tar.gz with data.json (all tables) + uploads/	Must
BAK-2	Restore from backup file: validates format, replaces all data, resets sequences	Must
BAK-3	Host-level scripts: backup.sh, restore.sh	Should
BAK-4	Audit log entry for backup download/restore	Must

2.9 Audit Log

ID	Requirement	Priority
AUD-1	Log all mutating actions: action name, target JSON, IP, timestamp	Must
AUD-2	Admin view: paginated list (default 100, max 1000)	Must

2.10 Security & Infrastructure

ID	Requirement	Priority
SEC-1	Admin auth via X-Admin-Token header (env ADMIN_PASSWORD, no default)	Must
SEC-2	Rate limiting: entries 10/15min, files/share 300/15min	Must
SEC-3	Upload validation: block dangerous extensions, MIME check, size limits	Must
SEC-4	Path traversal protection on file delete/serve	Must
SEC-5	Helmet headers (X-Frame-Options, nosniff, HSTS, Referrer-Policy)	Must
SEC-6	No CORS (cross-origin blocked)	Must
SEC-7	DB port not exposed publicly	Must
SEC-8	TLS termination by Tailscale (Let's Encrypt), app uses self-signed cert internally	Must
SEC-9	Tailscale Funnel publication (no public IP, no port forward)	Must

---

3. Non-Functional Requirements

Category	Requirement
Performance	API responses < 500ms for typical queries; pagination for large lists
Reliability	DB healthcheck; app restarts on crash; uploads persisted on host
Scalability	Single-instance design; PostgreSQL connection pooling via pg.Pool
Maintainability	Single server.js file; vanilla frontend; no build step
Portability	Docker Compose; runs on any Linux/ARM64/AMD64 with Docker
Backup/Recovery	Full restore < 5 min for typical dataset (< 1 GB)
Security	No secrets in image; env vars only; regular dependency updates

---

4. Data Model

groups
  id PK, name UK, created_at, day_of_week (0-6), time_start, time_end, branch_id FK, cover_path

students
  id PK, name UK, group_id FK, created_at

entries
  id PK, student_name, group_id FK, description, photo_path, deleted_at, created_at

project_files
  id PK, entry_id FK (nullable), token UK, path, name, created_at, detached_at

group_photos
  id PK, group_id FK, photo_path, caption, taken_at, created_at

share_links
  id PK, token UK, name, group_id FK, student_name, date_from, date_to,
  anonymize_names, expires_at, access_password_hash, created_at

settings
  key PK, value

audit_log
  id PK, action, target JSONB, ip, created_at

branches
  id PK, name UK, address, phone, created_at

---

5. API Surface (Key Endpoints)

Method	Path	Auth	Description
GET	/api/entries	Admin	List entries (filters, pagination)
POST	/api/entries	Admin	Create entry (photo + files)
PUT	/api/entries/:id	Admin	Update entry
DELETE	/api/entries/:id	Admin	Soft delete
POST	/api/entries/:id/restore	Admin	Restore from trash
GET	/api/files	Admin	All files (filters)
GET	/api/files/detached	Admin	Detached files
POST	/api/files/:id/detach	Admin	Detach file
GET	/api/files/:token	Public	Download file by token
GET	/api/groups	Public	List groups
POST/PUT/DELETE	/api/groups	Admin	CRUD groups
GET/POST	/api/groups/:id/photos	Admin	Group photo chronicle
GET	/api/share/:token	Public	Share page data
GET	/api/links	Admin	List share links
POST/PUT/DELETE	/api/links	Admin	CRUD share links
GET	/api/backup	Admin	Build & download backup (compat)
POST	/api/backup	Admin	Build backup, returns download URL
GET	/api/backup/:token	Token	Download built backup (resumable)
POST	/api/restore	Admin	Upload & restore backup
GET	/api/dashboard	Admin	Dashboard data
GET	/api/stats	Admin	Stats cards
GET	/api/audit	Admin	Audit log

---

6. User Flows

6.1 Teacher Creates Attendance Entry

1. Opens /journal.html
2. Fills form: student name (typeahead from existing), group, description
3. Adds photo (optional) + project files (optional)
4. Submits → entry appears in list, files accessible by token

6.2 Admin Publishes Showcase for Parents

1. Opens /links.html
2. Creates share link: selects group, date range, sets password
3. Copies link https://whatido.tailnet.ts.net/s/abc123
4. Sends to parents → they open, enter password, view entries + photos

6.3 Admin Restores from Backup

1. Opens /settings.html → Backups tab
2. Uploads .tar.gz backup file
3. Confirms → all data replaced, sequences reset, orphans cleaned

---

7. Deployment Architecture

Internet / Tailnet
       │
       ▼
┌──────────────────┐
│  Tailscale       │  (network_mode: host, port 443)
│  Funnel/Serve    │  TLS: Let's Encrypt (*.ts.net)
└────────┬─────────┘
         │ HTTPS (trusts app self-signed cert)
         ▼
┌──────────────────┐
│  App (Node.js)   │  127.0.0.1:3443 (HTTPS), :3003 (HTTP→HTTPS redirect)
│  Express + pg    │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  PostgreSQL 16   │  Internal docker network only
│  (named volume)  │
└──────────────────┘

Host filesystem:
  ./uploads  ──────► /app/uploads (bind mount)
  ./certs    ──────► /etc/tailscale/app-certs (ro)

---

8. Configuration

Variable	Required	Description
ADMIN_PASSWORD	Yes	Admin token value (no default, server refuses start)
DB_PASSWORD	Yes	Postgres app user password

---

9. Release Criteria

• All Must-have requirements implemented and tested
• Docker Compose starts cleanly on fresh host (docker compose up -d --build)
• Tailscale Funnel publishes successfully (manual verification)
• Backup/restore roundtrip works (data + files intact)
• No critical security findings (rate limits, upload validation, auth)
• README.md updated with accurate setup instructions

---

10. Future Considerations (Not in Scope v1)

• Multi-user auth (teachers with own logins)
• Email/push notifications
• Mobile app / PWA
• Rich text editor for descriptions
• Bulk import students (CSV)
• Webhooks for external integrations
• Automated scheduled backups to S3/remote
• Role-based access (read-only vs admin)

---

11. Acceptance Test Scenarios

Scenario	Steps	Expected
Fresh deploy	cp .env.example .env → edit → docker compose up -d --build	App healthy, DB migrated, HTTPS on 3443
Create entry	POST /api/entries with photo + 2 files	Entry created, files downloadable by token
Share link	Create link with password → open /s/token → enter password	Entries filtered, photos shown, files download
Backup/restore	Download backup → delete entry → restore → verify entry back	Full state restored, sequences correct
Tailscale publish	tailscale up → enable Funnel → tailscale funnel	Public URL accessible via HTTPS
Upload rejection	POST .html file → 400 error	Dangerous extensions blocked
Rate limit	11 rapid POST /api/entries → 429 on 11th	Entry limiter enforced

---