From 64aa1e69a03e5e219e7475d106c447341d17d863 Mon Sep 17 00:00:00 2001 From: ingecarlosgutie <45578430-ingecarlosgutie@users.noreply.replit.com> Date: Sun, 31 Aug 2025 20:05:22 +0000 Subject: [PATCH] Initial commit --- .replit | 0 ...nt-to-buil-1756670497155_1756670497156.txt | 204 ++++++++++++++++++ 2 files changed, 204 insertions(+) create mode 100644 .replit create mode 100644 attached_assets/Pasted-got-it-here-s-a-clean-copy-paste-prompt-you-can-drop-into-your-favorite-codegen-agent-to-buil-1756670497155_1756670497156.txt diff --git a/.replit b/.replit new file mode 100644 index 0000000..e69de29 diff --git a/attached_assets/Pasted-got-it-here-s-a-clean-copy-paste-prompt-you-can-drop-into-your-favorite-codegen-agent-to-buil-1756670497155_1756670497156.txt b/attached_assets/Pasted-got-it-here-s-a-clean-copy-paste-prompt-you-can-drop-into-your-favorite-codegen-agent-to-buil-1756670497155_1756670497156.txt new file mode 100644 index 0000000..553810f --- /dev/null +++ b/attached_assets/Pasted-got-it-here-s-a-clean-copy-paste-prompt-you-can-drop-into-your-favorite-codegen-agent-to-buil-1756670497155_1756670497156.txt @@ -0,0 +1,204 @@ +got it — here’s a clean, copy-paste **prompt** you can drop into your favorite codegen/agent to build the app exactly as you described. after the prompt, I added a compact API contract and folder blueprint so the output stays consistent. + +--- + +# Prompt: “Pomodorian – Study Sessions Timer (sound + suggestions + history, no login)” + +**Goal:** Build a full-stack “Pomodorian” study timer that plays a sound at the end of sessions, lets users configure times, receives smart time suggestions based on past usage, and records a local/anonymous history. No authentication required. + +## Tech & Architecture + +* **Client:** React + TypeScript, **Vite**, **Ant Design (antd)**, **Framer Motion**, **Atomic Design** (atoms/molecules/organisms/templates/pages). +* **Server:** Node.js + TypeScript, **Express**, **MVC pattern** (Models / Views / Controllers; Views are JSON only). +* **State:** Lightweight (e.g., Zustand or Context) on client; keep it simple. +* **Storage:** + + * Client: localStorage/IndexedDB for quick offline history. + * Server: simple persistence (SQLite or file-based) for anonymized analytics & suggestions. Identify users via a generated anonymous `deviceId` cookie (no login). +* **Sound:** Play an audible signal on session end and break start; default and user-selectable options. + +## Core Features + +1. **Pomodoro Timer** + + * Presets: 25/5 (focus/break), 50/10, plus **custom** durations. + * Visual progress ring, time left, start/pause/reset, skip break. + * Optional long break every N focus sessions. + * **Sound** on phase change (respect browser autoplay policies; request interaction first). Volume and mute toggle. + +2. **Time Suggestions** + + * Show 3 dynamic suggestions (e.g., “25 min focus”, “40 min deep work”, “15 min power sprint”) based on recent completion rate, preferred durations, and time-of-day success. + * Explainability note (“Based on your last 7 sessions…”). + +3. **History (No Login)** + + * Log each session locally: start/end timestamps, intended/actual duration, focus/break, completion status, interruptions count. + * Simple charts: sessions per day, completion rate, average focus duration. + * Export CSV/JSON. + +4. **No-Login, Anonymous** + + * On first load, generate `deviceId` (UUID) and store in cookie/localStorage. + * Use `deviceId` on server endpoints for suggestions & aggregate trends (no PII). + +5. **Polish** + + * Dark/light theme toggle. + * Keyboard shortcuts: Space (start/pause), R (reset), S (skip break). + * PWA basics (installable + offline for timer & history). + +## Client Requirements + +* **Atomic Design structure** with Ant Design components wrapped as atoms/molecules. +* **Pages:** Home (Timer), History/Insights, Settings. +* **Animations:** Framer Motion for page transitions and subtle UI feedback (button taps, card entrance). +* **Accessibility:** Focus states, ARIA for timer, sound toggle explained. +* **Persistence:** Local history mirrors to server when online (best-effort). +* **Error states:** Graceful toasts via antd. + +## Server (MVC) Requirements + +* **Routes (JSON only):** + + * `POST /api/sessions` — record session result `{ deviceId, type, intendedMinutes, actualSeconds, startedAt, endedAt, completed, interruptions }`. + * `GET /api/suggestions?deviceId=...` — return up to 3 durations with reasons. + * `GET /api/stats/summary?deviceId=...` — compact aggregates for charts (optional). +* **Controllers:** validation, error handling, 2xx/4xx/5xx responses with clear messages. +* **Models:** Session model; Suggestions service (uses simple heuristics: moving average of completed sessions, time-of-day buckets). +* **Persistence:** SQLite with a minimal schema (`sessions` table, `device_profiles` optional). +* **No auth**; CORS enabled for the Vite client origin only. +* **Tests:** minimal unit tests for suggestions logic. + +## Acceptance Criteria + +* Timer plays a sound reliably on phase changes after first user interaction. +* User can pick from **suggested durations** and see a one-line reason. +* History shows today + 7/30-day trends; export works. +* Works entirely without login; consistent anonymous `deviceId`. +* Clean, responsive UI using Ant Design; animated but subtle. +* Code is organized: atomic design on client; MVC on server; TypeScript everywhere. +* One-command dev start for client and server; `.env.example` provided. + +## Deliverables + +* **Client folder** (`vite` + `antd` + `framer-motion` + atomic design), **Server folder** (Node/TS/Express MVC). +* Sound assets (short beep + gentle chime). +* README with setup, scripts, and architectural notes. + +--- + +## API Contract (compact) + +**POST** `/api/sessions` +Request: + +```json +{ + "deviceId": "uuid", + "type": "focus|break", + "intendedMinutes": 25, + "actualSeconds": 1490, + "startedAt": "2025-08-31T14:05:00Z", + "endedAt": "2025-08-31T14:30:50Z", + "completed": true, + "interruptions": 1 +} +``` + +Response `201`: + +```json +{ "ok": true, "id": "session_id" } +``` + +**GET** `/api/suggestions?deviceId=uuid` +Response `200`: + +```json +{ + "suggestions": [ + { "minutes": 25, "reason": "Your 7-day completion rate is 82% at 25m." }, + { "minutes": 40, "reason": "Afternoons: best focus avg 37–42m." }, + { "minutes": 15, "reason": "High interruption mornings benefit from short sprints." } + ] +} +``` + +**GET** `/api/stats/summary?deviceId=uuid` +Response `200`: + +```json +{ + "last7d": { "sessions": 18, "completionRate": 0.76, "avgFocusMin": 28 }, + "last30d": { "sessions": 64, "completionRate": 0.71, "avgFocusMin": 26 } +} +``` + +--- + +## Folder Blueprint + +``` +pomodorian/ + client/ # Vite + React + TS + src/ + assets/sounds/ # chime.mp3, beep.mp3 + design/ # theme tokens, colors + state/ # store (Zustand/Context) + utils/ # time, audio, id + api/ # fetchers for /api/* + components/ + atoms/ + Button.tsx + Toggle.tsx + ProgressRing.tsx + SoundPicker.tsx + molecules/ + TimerControls.tsx + DurationSelector.tsx + SuggestionChips.tsx + organisms/ + PomodoroTimer.tsx + HistoryChart.tsx + ExportPanel.tsx + templates/ + MainLayout.tsx + pages/ + Home.tsx + History.tsx + Settings.tsx + index.html + main.tsx + vite.config.ts + tsconfig.json + server/ # Node + TS + Express (MVC) + src/ + app.ts + routes/ + index.ts + sessions.routes.ts + suggestions.routes.ts + controllers/ + sessions.controller.ts + suggestions.controller.ts + models/ + session.model.ts + services/ + suggestions.service.ts + stats.service.ts + db/ + prisma.schema.sql or knex migrations + middleware/ + cors.ts + error.ts + utils/ + validate.ts + package.json + tsconfig.json + README.md +``` + +--- + +If you want, I can turn this into a starter repo (with Vite, antd, motion, and a minimal Express MVC) and drop in a couple of example components & endpoints.