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.