Skip to content

README.md

Latest commit

 

History

History
253 lines (179 loc) · 6.98 KB

README.md

File metadata and controls

253 lines (179 loc) · 6.98 KB
Raw

Reflect App

A modern journaling application with AI-powered reflection capabilities. Built with Next.js, TypeScript, and OpenAI integration to provide users with meaningful insights into their journal entries.

🚀 Features

Core Functionality

  • AI-Powered Journaling - Get automated reflections, pattern detection, and actionable suggestions
  • Journal Entry Input - Enhanced textarea with auto-resize, validation, and character counting
  • Real-time Feedback - Instant validation and feedback on journal entries
  • Responsive Design - Optimized experience across all devices and screen sizes
  • Dark/Light Mode - Full theme support with system preference detection

Technical Features

  • Next.js 15 with App Router
  • OpenAI Integration - GPT-4 Turbo with GPT-3.5 Turbo fallback
  • TypeScript for type safety
  • Tailwind CSS v4 with CSS variables for theming
  • shadcn/ui for beautiful, accessible UI components
  • Rate Limiting & Caching - Optimized AI API usage with cost reduction
  • Comprehensive Testing - Unit tests with Vitest + E2E tests with Playwright
  • Code Quality - ESLint, Prettier, Husky pre-commit hooks
  • Path aliases (@/*) configured
  • Vercel deployment ready

Architecture Philosophy

This application follows a simplified, standard-first approach:

  • Standard HTML elements for accessibility (no over-engineered custom focus management)
  • Component simplicity over complex abstractions
  • Testing reliability with standard patterns
  • Maintainability through clear, readable code

Note: A comprehensive custom focus management system was removed in September 2025 to reduce complexity and improve maintainability.

📦 Package Manager

This project uses pnpm for faster, more efficient dependency management.

🛠️ Getting Started

Prerequisites

  • Node.js 18+ and pnpm
  • OpenAI API key (required for AI features)

Installation

# Install dependencies
pnpm install

# Set up environment variables
cp .env.example .env.local

# Add your OpenAI API key to .env.local
echo "OPENAI_API_KEY=your_openai_api_key_here" >> .env.local

# Start development server
pnpm dev

Environment Setup

The application requires several environment variables for full functionality:

Required:

OPENAI_API_KEY=your_openai_api_key_here

Optional (with defaults):

# AI Model Configuration
OPENAI_MODEL=gpt-4-1106-preview
OPENAI_FALLBACK_MODEL=gpt-3.5-turbo-1106
OPENAI_MAX_TOKENS=500
OPENAI_TEMPERATURE=0.7

# Rate Limiting
AI_RATE_LIMIT_RPM=10

# Caching
AI_CACHE_TTL=3600

Get your OpenAI API key from: https://platform.openai.com/api-keys

Available Scripts

# Development
pnpm dev              # Start development server
pnpm build            # Build for production
pnpm start            # Start production server

# Code Quality
pnpm lint             # Run ESLint
pnpm format           # Format code with Prettier
pnpm format:check     # Check code formatting

# Testing
pnpm test             # Run unit tests
pnpm test:ui          # Run tests with UI
pnpm test:coverage    # Run tests with coverage
pnpm test:e2e         # Run e2e tests
pnpm test:e2e:ui      # Run e2e tests with UI
pnpm test:e2e:debug   # Debug e2e tests

🧪 Testing

Unit Tests

  • Vitest for fast unit testing
  • @testing-library/react for React component testing
  • jsdom environment for DOM testing
  • Test files: **/__tests__/**/*.test.{ts,tsx}

E2E Tests

  • Playwright for end-to-end testing
  • Tests across Chrome, Firefox, and Safari
  • Test files: e2e/**/*.spec.ts

🎨 UI Components

This application includes custom and shadcn/ui components:

Custom Components

  • JournalEntryInput - Enhanced textarea for journal writing with auto-resize, validation, and character counting
  • LoadingSpinner - Animated loading indicators with size/color variants
  • ErrorMessage - Accessible error display with icons and variants
  • Feedback - Thumbs up/down rating component for user feedback
  • ThemeToggle - Light/dark/system mode switching

shadcn/ui Components

  • Button, Card, Input, Label, Textarea, Dialog

Add more shadcn/ui components with:

pnpm dlx shadcn@latest add [component-name]

📁 Project Structure

src/
├── app/
│   ├── api/
│   │   └── reflect/           # AI processing endpoint
│   │   └── page.tsx              # Main application page
├── components/
│   ├── ui/                   # UI components (buttons, inputs, etc.)
│   └── __tests__/           # Component unit tests
├── lib/
│   ├── openai.ts            # OpenAI service utilities
│   ├── ai-client.ts         # Client-side AI utilities
│   └── utils.ts             # General utilities
├── types/
│   └── ai.ts                # AI service type definitions
└── test/                    # Test setup and utilities

e2e/                         # Playwright end-to-end tests
.taskmaster/                 # Project task management

🔧 Configuration

  • ESLint: Extends Next.js config
  • Prettier: Includes Tailwind plugin for class sorting
  • Tailwind: v4 with CSS variables for theming
  • TypeScript: Strict mode enabled
  • Path Aliases: @/* maps to src/*

🤖 AI Integration

The app uses OpenAI's API to provide intelligent reflections on journal entries:

API Endpoint

  • POST /api/reflect - Process journal entries with AI

Features

  • Dual Model Support - GPT-4 Turbo primary, GPT-3.5 Turbo fallback
  • Rate Limiting - 10 requests/minute per IP (configurable)
  • Caching - Reduces API costs for similar entries
  • Error Handling - Comprehensive error types and recovery
  • Response Format - Summary, pattern detection, actionable suggestions

Client Usage

import { aiClient } from '@/lib/ai-client'

const response = await aiClient.processEntry({
  content: 'Your journal entry here...',
})

console.log(response.summary) // Brief summary
console.log(response.pattern) // Detected pattern/theme
console.log(response.suggestion) // Actionable suggestion

🚀 Deployment

Vercel (Recommended)

  1. Push to GitHub
  2. Import project in Vercel
  3. Add environment variables:
    • OPENAI_API_KEY (required)
    • Other optional AI configuration variables
  4. Deploy automatically

Other Platforms

Works on any platform supporting Next.js. Ensure environment variables are configured properly.

🛡️ Code Quality

  • Pre-commit hooks with Husky
  • Lint-staged for staged file linting
  • ESLint + Prettier integration
  • TypeScript strict mode

📊 Performance

  • Next.js 15 performance optimizations
  • Static generation where possible
  • Optimal bundle splitting
  • Image optimization built-in

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Run tests and linting
  5. Submit a pull request

📝 License

MIT License - see LICENSE file for details.