Bootcamp Pomodoro PWA Development Assistant
This skill helps you work with the Bootcamp Pomodoro PWA codebase - a Progressive Web App with Node.js backend implementing a Pomodoro timer with session history, statistics, and motivational quotes.
Project Overview
**Stack:**
Frontend: Vite + Vanilla JS + PWA PluginBackend: Node.js + ExpressTesting: Playwright (E2E) + Node.js Test Runner (Unit)Containerization: Docker + Docker ComposeCI/CD: GitHub Actions + GitHub Pages**Architecture:**
Monorepo structure with `apps/web` (frontend PWA), `apps/api` (backend), and `tests/e2e` (Playwright tests). State is managed via localStorage on frontend and in-memory on backend. PWA uses Workbox service worker for offline support.
Key Instructions
1. Understanding the Codebase Structure
When asked about the project:
**Frontend entry point:** `apps/web/src/main.js` - UI initialization, event handlers, DOM updates**Timer logic:** `apps/web/src/timer.js` - Timer class with localStorage persistence**API client:** `apps/web/src/api-client.js` - Abstraction layer for backend calls**Backend entry:** `apps/api/src/index.js` - Express app and route mounting**Session routes:** `apps/api/src/routes/sessions.js` - CRUD endpoints and validation**Quotes service:** `apps/api/src/services/quotes.js` - Quotable API proxy**PWA config:** `apps/web/vite.config.js` - Service worker and manifest configuration**E2E tests:** `tests/e2e/pwa.spec.ts` (PWA functionality) and `tests/e2e/api.spec.ts` (API endpoints)**CI/CD:** `.github/workflows/ci-pwa.yml` - Build, test, Lighthouse, deploy pipeline2. Development Commands
**Setup:**
```bash
npm install # Root + all workspaces
```
**Development:**
```bash
npm run dev:web # Vite dev server (port 8080)
npm run dev:api # Node watch mode (port 3000)
```
**Build & Preview:**
```bash
npm run build:web
cd apps/web && npm run preview
```
**Testing:**
```bash
npm run test:unit # API unit tests (16 tests)
npm run test:e2e # E2E tests (requires web + API running)
cd tests/e2e && npm run test:ui # Interactive mode
```
**Docker:**
```bash
npm run docker:up # Start all services
npm run docker:down # Stop services
```
3. Adding New Features
**Timer Features:**
1. Update `Timer` class in `apps/web/src/timer.js` for state logic
2. Update UI handlers in `apps/web/src/main.js`
3. Update localStorage schema if needed
4. Add E2E tests in `tests/e2e/pwa.spec.ts`
**API Endpoints:**
1. Add route handler in `apps/api/src/routes/sessions.js` or new route file
2. Import and mount in `apps/api/src/index.js`
3. Update `apps/web/src/api-client.js` with new method
4. Add unit tests (sessions.test.js or new test file)
5. Add E2E tests in `tests/e2e/api.spec.ts`
**Validation Pattern:**
`mode` must be: `focus`, `shortBreak`, or `longBreak`Return 400 for validation errors, 404 for not found, 500 for server errorsAlways validate required fields and data types4. PWA Configuration
**Service Worker (apps/web/vite.config.js):**
Uses Workbox with `autoUpdate` strategyCaches: static assets, API responses (NetworkFirst), quotes APITo modify caching: edit `workbox.runtimeCaching` config**Manifest:**
`base: '/bootcamp2-chrome-ext-SrMorim/'` for GitHub Pages deploymentIcons: 192x192 and 512x512 (maskable) in `apps/web/public/icons/`Must match repository name for GitHub Pages5. Testing Requirements
**Unit Tests (API):**
16 tests total: 12 for sessions routes, 4 for quotes serviceValidates CRUD operations, statistics, validation, fallback mechanismsRun: `cd apps/api && npm test`**E2E Tests (Playwright):**
16 tests total: 8 PWA tests, 8 API testsPWA: manifest, service worker, timer controls, offline modeAPI: health, quotes, CRUD, validationRequires both API and web running**Lighthouse CI:**
All scores must be ≥ 80 (Performance, PWA, Accessibility, Best Practices, SEO)Critical assertions: service worker, installable manifest, ARIA attributesConfig: `.lighthouserc.cjs`6. Accessibility Implementation
Always maintain ARIA compliance:
All interactive elements have `aria-label` or visible labelTimer display uses `role="timer"` with `aria-live="polite"`Mode buttons use `aria-pressed` statesTab panels use `role="tabpanel"` with `aria-labelledby`Form inputs have `aria-describedby` for hintsScreen-reader only text uses `.sr-only` CSS classProper semantic HTML (h1→h2 hierarchy, landmarks)7. Deployment & CI/CD
**GitHub Pages (Automatic):**
Deploys on push to main via official GitHub Actions artifact methodUses `actions/upload-pages-artifact@v3` and `actions/deploy-pages@v4`Production API_URL points to Render backendAvailable at: https://srmorim.github.io/bootcamp2-chrome-ext-SrMorim/**CI/CD Pipeline Jobs:**
1. `build-test`: Install → Unit tests → Build → E2E tests → Lighthouse CI
2. `deploy`: Build with production API_URL → Upload Pages artifact → Deploy
3. `docker-build`: Test Docker builds and docker-compose config
**Quality Gates:**
API unit tests must pass (16 tests)E2E tests must pass (16 tests)Lighthouse scores ≥ 808. Common Issues & Solutions
**API not reachable:**
Check `VITE_API_URL` environment variable during buildDev: API on 3000, web on 8080Docker: API on 3000, web on 80 (mapped to 8080)**Service worker not updating:**
Hard refresh (Ctrl+Shift+R)Clear application cache in DevToolsVite PWA uses `autoUpdate` strategy**Tests failing:**
Ensure API and web preview are runningCheck ports 3000 and 8080 are availableVerify `E2E_BASE_URL` and `API_URL` env varsPlaywright browsers: `npx playwright install chromium`**Lighthouse CI fails:**
Common issues: missing aria-labels, color contrast, tap targetsReview `.lighthouserc.cjs` configurationMay need to relax thresholds temporarily during development**GitHub Pages deployment fails:**
Check workflow permissions (pages: write, id-token: write)Verify official Actions versions (configure-pages@v5, upload-pages-artifact@v3, deploy-pages@v4)Repository Settings → Pages → Source should show "GitHub Actions"9. Performance Considerations
Timer UI updates every second - keep `updateUI()` lightweightAPI returns all sessions - may need pagination for productionIn-memory sessions storage - consider database for persistenceMonitor service worker cache size in production10. API Endpoints Reference
**Base URL:** `http://localhost:3000`
`GET /api/health` - Health check`GET /api/quote` - Random motivational quote (Quotable proxy)`GET /api/sessions` - List all sessions (sorted by completedAt desc)`GET /api/sessions/:id` - Get specific session`GET /api/sessions/stats` - Statistics (total, today, thisWeek, byMode)`POST /api/sessions` - Create session (body: `{mode, duration, completedAt}`)`DELETE /api/sessions/:id` - Delete session`DELETE /api/sessions` - Clear all sessionsUsage Examples
**Example 1: Add new timer feature**
User: "Add a notification when the timer completes"
Steps:
1. Read `apps/web/src/timer.js` to understand Timer class structure
2. Add notification logic to complete callback
3. Update `apps/web/src/main.js` to handle notification permission
4. Add E2E test to `tests/e2e/pwa.spec.ts` for notification behavior
5. Run E2E tests to verify
**Example 2: Add new API endpoint**
User: "Add an endpoint to get today's completed sessions"
Steps:
1. Add route handler to `apps/api/src/routes/sessions.js`
2. Filter sessions by today's date
3. Add unit test to `apps/api/src/routes/sessions.test.js`
4. Update `apps/web/src/api-client.js` with new method
5. Add E2E test to `tests/e2e/api.spec.ts`
6. Run `npm run test:unit` and `npm run test:e2e`
**Example 3: Fix accessibility issue**
User: "Lighthouse is failing on ARIA labels"
Steps:
1. Run Lighthouse CI locally: `npx @lhci/[email protected] autorun --config=.lighthouserc.cjs`
2. Review violations in report
3. Add missing `aria-label` attributes to interactive elements
4. Verify with Lighthouse CI again
5. Run E2E tests to ensure functionality not broken
Important Notes
Always run tests before committing changesMaintain accessibility compliance (ARIA, semantic HTML)Keep timer UI updates lightweight (runs every second)Service worker caching strategy: NetworkFirst for API, StaleWhileRevalidate for staticDocker deployment uses multi-stage builds for frontendCI/CD enforces quality gates (unit, E2E, Lighthouse)GitHub Pages deployment is fully automated on main branch