Initial commit

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.