vision board requirements for LLMs

vision-board-requirements.md

Vision Board Bliss - Requirements Document

Overview

Vision Board Bliss is a web-based application that allows users to create, manage, and track personal goals through visual vision boards. The application combines goal management with achievement tracking and social sharing capabilities.

Core Features

1. User Authentication & Management

• Sign Up/Login: Email-based authentication via Supabase Auth
• User Sessions: Persistent authentication with secure session management
• Protected Routes: Authentication-required sections of the application
• User Preferences: Customizable settings for notifications and sharing

2. Goal Management

• Create Goals: Users can add new goals with:
  • Visual image representation
  • Personal "why" statement (motivation)
  • Target deadline
• Edit Goals: Modify existing goal details
• Delete Goals: Remove goals from vision board
• Mark as Achieved: Toggle goal completion status with timestamp
• Goal Filtering: View active vs. achieved goals
• Goal Details View: Expanded view with navigation between goals

3. Vision Board Display

• Grid Layout: Visual display of goal cards in responsive grid
• Goal Cards: Individual cards showing goal image, the reason, and status
• Interactive Navigation: Click to view detailed goal information
• Empty State Handling: Appropriate messaging when no goals exist
• Loading States: Skeleton loading while data is fetched

4. Achievement System

• Automatic Achievement Creation: Auto-generated achievements when goals are completed
• Achievement Types: Support for different achievement categories
• Achievement Data: Structured data storage for achievement details
• Impact Metrics: Tracking of achievement-related metrics
• Featured Achievements: Ability to highlight notable achievements
• Achievement Counter: Display total count of achieved goals

6. Social Features

• Sharing Opt-in: User consent for sharing achievements
• Published Wins: System for sharing achievements on social platforms
• Success Stories: Carousel of featured user achievements on landing page
• Social Share Preview: Optimized sharing previews for social media

7. Performance & Offline Support

• Optimized Loading: Performance-optimized components and lazy loading
• Offline Indicator: Visual indication of connection status
• Offline Storage: Local storage capabilities for offline functionality
• Progressive Web App: PWA features with service worker

8. User Interface

• Responsive Design: Mobile-first responsive layout
• Dark/Light Mode: Theme switching capabilities
• Toast Notifications: User feedback for actions and errors
• Modal Dialogs: Various modal types for different interactions
• Loading Skeletons: Improved perceived performance during loading

Technical Requirements

Performance Features

• Code Splitting: Lazy loading of components
• Image Optimization: Optimized image handling and display
• Caching: Strategic caching with TanStack Query
• Bundle Optimization: Minimized bundle sizes
• Performance Monitoring: Lighthouse CI integration

User Workflows

1. New User Onboarding

1. User visits landing page
2. Creates account or logs in
3. Views empty vision board with call-to-action
4. Adds first goal with image, description, why, and deadline
5. Views populated vision board

2. Goal Management Workflow

1. User views vision board with existing goals
2. Can add new goals via floating action button
3. Can click on goals to view details
4. Can edit or delete goals from detail view
5. Can mark goals as achieved
6. Automatic achievement creation upon goal completion

3. Achievement Tracking

1. Goals marked as achieved trigger achievement creation
2. Achievements stored with metadata and timestamps
3. Users can view achievements in dedicated achievements page
4. Optional sharing and testimonial features

Pages & Navigation

Public Pages

• Landing Page (/): Marketing page with features and success stories
• Authentication (/auth): Login and signup forms
• Demo (/demo): Demo version of the application

Protected Pages

• Vision Board (/app): Main application interface
• Achievements (/achievements): Achievement tracking and display

Error Pages

• 404 Not Found (/404): Custom error page for invalid routes

Data Models

Goal

{
  id: string;
  image: string;
  why: string;
  why?: string;
  deadline: string;
  createdAt: string;
  achieved: boolean;
  achievedAt?: string;
}

User Achievement

{
  id: string;
  user_id: string;
  goal_id?: string;
  achievement_type: string;
  achievement_data?: Record<string, unknown>;
  impact_metrics?: Record<string, unknown>;
  testimonial?: string;
  is_featured: boolean;
  opt_in_sharing: boolean;
  created_at: string;
  updated_at: string;
}

Performance Requirements

• Load Time: Initial page load under 2 seconds
• Load Time: Entire vision board grid page load under 2 seconds
• Responsive: Smooth interaction on mobile and desktop
• Offline Capability: Basic functionality available offline
• Accessibility: WCAG 2.1 AA compliance
• SEO: Optimized for search engines

Browser Support

• Modern browsers (Chrome, Safari)
• Mobile browsers (iOS Safari, Chrome Mobile)
• Progressive Web App capabilities

Monitoring & Analytics

• Error Tracking: Runtime error monitoring
• Performance Monitoring: Core Web Vitals tracking
• Database Monitoring: Supabase built-in monitoring

Testing requirements

• on localhost, no DB connection is required to authenticate. Authentication should be off via a configuration. In production, authentication can be on.
• fill the dashboard of the test user with 15 goals.
• every feature must have a passing test.

Future Enhancements (Not Currently Implemented)

• Email notifications for goal deadlines
• Goal categories and tagging
• Goal sharing with other users
• Advanced analytics and reporting
• Mobile app version
• Integration with calendar applications
• Goal template library

vision-board-v2.md

Vision Board Bliss – Requirements (Refined)

0. Purpose

This document defines functional and non‑functional requirements for Vision Board Bliss. It removes ambiguity, adds explicit constraints, and supplies testable acceptance criteria to reduce future bugs.

1. Glossary

Goal: A user-defined objective with image, motivation (why), and deadline. Vision Board: The main grid view listing a user’s goals (a.k.a. Dashboard) – use the term “Vision Board” consistently. Achievement: A record generated when a goal is marked achieved (idempotent: one achievement per goal). Featured Achievement: Achievement flagged for public prominence. Sharing Opt‑In: Per-achievement boolean allowing public display. Mock Mode: Development mode with auth disabled and seeded goals.

2. Environment & Feature Flags

Flag	Type	Dev Default	Prod Default	Purpose
NEXT_PUBLIC_DISABLE_AUTH	boolean	true	false	Disable Supabase auth & use mock user.
NEXT_PUBLIC_MOCK_DATA	boolean	true	false	Seed 15 mock goals for test user.
NEXT_PUBLIC_ENABLE_PWA	boolean	true	true	Enable service worker / manifest.
NEXT_PUBLIC_ENABLE_SOCIAL_SHARING	boolean	false	true (phase 2)	Expose social sharing UI.
NEXT_PUBLIC_SHOW_OFFLINE_INDICATOR	boolean	true	true	Show connectivity badge.

Changing a flag must not break runtime (provide fallbacks). Document in README.

3. Functional Requirements

3.1 Authentication & User Session

FR-A1 Users can sign up / log in via email (Supabase) when auth enabled. FR-A2 In Mock Mode a static mock user (id: test-user) is injected immediately. FR-A3 Protected routes redirect unauthenticated users to /auth/login. FR-A4 Session is restored on refresh (Supabase getUser or mock).

3.2 Goal Management

FR-G1 Create goal with: image (URL or uploaded), why (motivation), deadline. FR-G2 Edit any mutable fields (image, why, deadline) while active. FR-G3 Delete a goal (soft delete not required now – permanent removal). FR-G4 Mark as achieved sets achieved=true, achievedAt=ISO timestamp and triggers achievement creation (once only). FR-G5 Filter goals: all | active | achieved (default = active). FR-G6 View goal details (modal or dedicated page) with navigation next/prev.

3.3 Vision Board Display

FR-V1 Responsive grid (1 / 2 / 3+ columns at breakpoints sm/md/lg). FR-V2 Each card shows image (lazy), truncated why, deadline, achieved badge if applicable. FR-V3 Empty state (copy: “No goals yet. Start building your vision board!” + CTA button). FR-V4 Loading state uses skeleton placeholders (minimum 3) with aria-busy.

3.4 Achievement System

FR-C1 Achievement auto-created when a goal becomes achieved (if not already). Idempotent check by goal_id. FR-C2 Supported achievement_type values (enum): goal_completion, milestone, featured_story (extensible; unknown types rejected). FR-C3 Users can view list of achievements at /achievements sorted desc by created_at. FR-C4 Featured achievements (is_featured=true) appear in landing page carousel (if sharing opted in). FR-C5 Counter of total achieved goals visible on Vision Board header.

3.5 Social / Sharing

FR-S1 Achievements display share action only if ENABLE_SOCIAL_SHARING=true and opt_in_sharing=true. FR-S2 Share metadata (Open Graph tags) generated for landing page and featured achievements. FR-S3 Users can toggle opt_in_sharing per achievement (default false).

3.6 Offline & PWA

FR-O1 When offline: existing cached goals still render; creating/editing queues mutations locally (in-memory + localStorage) and flushes on reconnect. FR-O2 Offline indicator visible when navigator.onLine = false or last 2 consecutive fetches failed. FR-O3 Service worker caches: static assets (CacheFirst), images (StaleWhileRevalidate), API JSON (NetworkFirst with fallback to cache).

3.7 UI / UX

FR-U1 Dark / Light theme toggle stored in localStorage (key: vb-theme). FR-U2 All modals trap focus and close with ESC. FR-U3 Toast notifications for success (goal created, updated, achieved) and errors (upload failed, network error) auto-dismiss in 4–6s.

4. Data Models & Constraints

4.1 Goal (table: goals)

Field	Type	Constraints
id	uuid	PK
user_id	uuid	FK users.id, required
image	text	HTTPS URL or storage public URL; max length 512
why	text	1–280 chars (Unicode); trimmed; no duplicate field (removed earlier duplication)
deadline	date	Must be >= current date at creation/update
createdAt	timestamptz	Default now()
achieved	boolean	Default false
achievedAt	timestamptz	Nullable; set only when achieved flips true

Validation Errors (codes): WHY_REQUIRED, WHY_LENGTH, DEADLINE_PAST, IMAGE_INVALID_URL.

4.2 Achievement (table: achievements)

| Field | Type | Constraints | | id | uuid | PK | | user_id | uuid | required | | goal_id | uuid | FK goals.id nullable (some achievements may not map 1:1) | | achievement_type | text | Enum (see FR-C2) | | achievement_data | jsonb | Optional structured payload | | impact_metrics | jsonb | Optional metrics | | testimonial | text | Optional 0–500 chars | | is_featured | boolean | Default false | | opt_in_sharing | boolean | Default false | | created_at | timestamptz | Default now() | | updated_at | timestamptz | Updated on mutation |

Business Rule: (goal_id, achievement_type) must be unique when achievement_type = goal_completion.

4.3 User Preferences (table: user_preferences)

| Field | Type | Notes | | user_id | uuid | PK/FK | | theme | text | 'light' | 'dark' (default system) | | notifications_enabled | boolean | Default true | | sharing_default_opt_in | boolean | Default false |

5. Goal State Machine

Draft -> Active (on creation immediate Active) -> Achieved. (Future: Archived). Only transition Active -> Achieved sets achievedAt and triggers achievement.

6. Acceptance Criteria (Samples)

AC-GOAL-CREATE

Given mock mode enabled When user submits valid image URL, why length 20, future deadline Then a goal appears at top of grid with achieved badge absent.

AC-GOAL-ACHIEVE

Given an active goal When user marks achieved Then card shows achieved badge AND an achievement record exists AND second mark attempt does not create duplicate.

AC-EMPTY-STATE

Given user has zero goals When Vision Board loads Then message “No goals yet. Start building your vision board!” and CTA button are visible.

AC-OFFLINE-CREATE

Given user offline When user creates goal Then goal appears with pending state indicator (e.g., opacity) AND on reconnect it persists and pending clears.

AC-SHARE-PERMISSION

Given achievement opt_in_sharing=false Then share button is hidden.

7. Validation & Error Handling

Client validates before mutation; server (Supabase policies or edge functions) re-validates. Error envelope (front-end normalized): { code: string; message: string; field?: string }. Image upload: on failure show toast “Image upload failed. Please retry.” Keep prior image value.

8. Non-Functional Requirements

Performance Budgets: LCP < 2.5s (mid-tier mobile; 4x CPU throttle, Fast 3G) for Vision Board. Total initial JS < 250KB gzip. CLS < 0.1; TBT < 300ms. Accessibility: WCAG 2.1 AA, keyboard nav, aria-live for toasts, alt text required. SEO: Landing page meta + Open Graph for featured achievements. Security: No PII beyond email; enforce HTTPS image sources. Privacy: Sharing always explicit opt-in (per achievement and global default setting).

9. Testing Requirements

T1 Unit Tests: hooks (auth, goals CRUD, achievements creation logic). T2 Component Tests: GoalCard, GoalForm, AchievementList, OfflineIndicator, ThemeToggle. T3 Integration: create -> achieve -> achievement record, offline queue flush. T4 E2E (future Playwright/Cypress): onboarding, goal CRUD, achieve flow, offline create sync. T5 Contract: Validate Supabase schema (migration snapshot test) – required before deployment. Coverage Target: ≥80% lines overall; ≥100% for goal mutation & achievement creation logic. Mock Mode: Must seed exactly 15 goals for test user (id: test-user) when NEXT_PUBLIC_MOCK_DATA=true.

10. Monitoring & Analytics Events

Events (name, payload excerpt): goal_created { goal_id } goal_updated { goal_id, changed_fields } goal_achieved { goal_id } achievement_created { achievement_id, goal_id } share_clicked { achievement_id } offline_queue_flushed { count }

11. PWA & Offline Strategy

Cache Strategies: Static assets: CacheFirst Images (goal images): StaleWhileRevalidate API (goals, achievements): NetworkFirst (timeout 4s) -> Cache fallback Queue: LocalStorage key vb-offline-queue (array of pending mutations). Flush order = FIFO.

12. Copy & UI Consistency

Empty state copy (canonical): "No goals yet. Start building your vision board!" Achieved badge text: "Achieved". Create button: "Add Goal" (CTA) / form submit label: "Create" or "Update" depending on mode.

13. Change Management

Semantic Versioning (MAJOR.MINOR.PATCH). Changelog required per release (CHANGELOG.md). Schema changes require migration script + test update.

14. Deferred / Future Features

Email notifications (deadline reminders) Goal categories & tagging Goal sharing with other users Advanced analytics & reporting Mobile app Calendar integration Goal template library

15. Out of Scope (Explicitly)

User-to-user collaboration Role-based permissions beyond single user ownership Internationalization (phase 2)

16. Risk Mitigations

Duplicate why field removed (prevent schema confusion). Enum enforced for achievement_type prevents silent typos. Feature flags isolate incomplete modules. Offline queue idempotency handled by client assigning temporary IDs.

17. Open Questions (Track & Resolve Before Release)

Should achieved goals be visually de‑emphasized (opacity) or grouped? (Default: no grouping, simple badge.) Retention policy for deleted goals? (Default: hard delete.)

---

This refined spec supersedes prior ambiguous sections and is the single source of truth for development & testing.