mirror of
https://github.com/CarGDev/pomodoro.git
synced 2025-09-18 17:48:28 +00:00
205 lines
7.0 KiB
Plaintext
205 lines
7.0 KiB
Plaintext
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.
|