Bible ScreenTime Manager

A React Progressive Web App (PWA) that helps users manage their screen time by requiring Bible verse memorization before unlocking device access.

Project Overview

The Bible ScreenTime Manager is a PWA that combines digital wellness with spiritual growth. Users set time limits for their device usage, and when those limits are reached, the app locks the screen and requires users to correctly type a Bible verse multiple times before regaining access.

Project Hierarchy

bible-screentime-manager/
├── public/
│   ├── manifest.json                 # PWA manifest configuration
│   ├── service-worker.js             # Service worker for offline/caching
│   ├── icons/                        # PWA icons (various sizes)
│   │   ├── icon-192x192.png
│   │   ├── icon-512x512.png
│   │   └── apple-touch-icon.png
│   └── index.html                    # Main HTML entry point
├── src/
│   ├── components/                   # React components
│   │   ├── core/                     # Core application components
│   │   │   ├── VerseLibrary/         # Verse management interface
│   │   │   │   ├── VerseLibrary.jsx
│   │   │   │   ├── VerseCard.jsx
│   │   │   │   ├── VerseForm.jsx
│   │   │   │   └── VerseLibrary.css
│   │   │   ├── VerseInput/           # Verse typing interface
│   │   │   │   ├── VerseInput.jsx
│   │   │   │   ├── TypingArea.jsx
│   │   │   │   ├── ProgressIndicator.jsx
│   │   │   │   └── VerseInput.css
│   │   │   ├── UsageTimer/           # Time tracking component
│   │   │   │   ├── UsageTimer.jsx
│   │   │   │   ├── TimerDisplay.jsx
│   │   │   │   ├── TimeProgress.jsx
│   │   │   │   └── UsageTimer.css
│   │   │   ├── LockScreen/           # Screen lock overlay
│   │   │   │   ├── LockScreen.jsx
│   │   │   │   ├── LockOverlay.jsx
│   │   │   │   ├── UnlockPrompt.jsx
│   │   │   │   └── LockScreen.css
│   │   │   └── Settings/             # App configuration
│   │   │       ├── Settings.jsx
│   │   │       ├── TimeLimits.jsx
│   │   │       ├── EnforcementMode.jsx
│   │   │       ├── VerseSettings.jsx
│   │   │       └── Settings.css
│   │   ├── layout/                   # Layout components
│   │   │   ├── Header.jsx
│   │   │   ├── Navigation.jsx
│   │   │   ├── Sidebar.jsx
│   │   │   └── Footer.jsx
│   │   └── common/                   # Reusable UI components
│   │       ├── Button.jsx
│   │       ├── Modal.jsx
│   │       ├── Card.jsx
│   │       ├── Input.jsx
│   │       └── Loading.jsx
│   ├── services/                     # Business logic and data management
│   │   ├── VerseService.js           # CRUD operations for verses
│   │   ├── StorageService.js         # IndexedDB persistence layer
│   │   ├── TimeService.js            # Time tracking and management
│   │   ├── NotificationService.js    # Browser notifications
│   │   └── PWAInstallService.js      # PWA installation handling
│   ├── hooks/                        # Custom React hooks
│   │   ├── useVerseLibrary.js        # Verse management hook
│   │   ├── useUsageTimer.js          # Timer functionality hook
│   │   ├── useLockScreen.js          # Lock screen state hook
│   │   ├── useSettings.js            # Settings management hook
│   │   └── usePWAInstall.js          # PWA installation hook
│   ├── utils/                        # Utility functions
│   │   ├── constants.js              # App constants
│   │   ├── helpers.js                # Helper functions
│   │   ├── validators.js             # Input validation
│   │   └── formatters.js             # Data formatting
│   ├── styles/                       # Global styles and themes
│   │   ├── globals.css               # Global CSS
│   │   ├── variables.css             # CSS custom properties
│   │   ├── components.css            # Component-specific styles
│   │   └── themes/                   # Theme variations
│   │       ├── light.css
│   │       └── dark.css
│   ├── data/                         # Static data and presets
│   │   ├── presetVerses.js           # Default Bible verses
│   │   ├── categories.js             # Verse categories
│   │   └── translations.js           # Bible translations
│   ├── context/                      # React context providers
│   │   ├── AppContext.js             # Main app state
│   │   ├── SettingsContext.js        # Settings state
│   │   └── TimerContext.js           # Timer state
│   ├── pages/                        # Page components
│   │   ├── Home.jsx                  # Main dashboard
│   │   ├── Library.jsx               # Verse library page
│   │   ├── Timer.jsx                 # Timer page
│   │   ├── Settings.jsx              # Settings page
│   │   └── About.jsx                 # About page
│   ├── App.jsx                       # Main app component
│   ├── index.js                      # App entry point
│   └── registerSW.js                 # Service worker registration
├── package.json                      # Dependencies and scripts
├── tailwind.config.js                # Tailwind CSS configuration
├── vite.config.js                    # Vite build configuration
├── .gitignore                        # Git ignore rules
├── .eslintrc.js                      # ESLint configuration
└── README.md                         # This file

Core Components

VerseLibrary

• Purpose: Manages preset and custom Bible verses
• Features:
  • Browse preset verses by category (encouragement, wisdom, etc.)
  • Add custom verses with reference and text
  • Edit and delete custom verses
  • Search and filter functionality
  • Verse difficulty ratings

VerseInput

• Purpose: Requires users to type verses correctly multiple times
• Features:
  • Real-time typing validation
  • Progress tracking (X/Y correct attempts)
  • Error highlighting and correction suggestions
  • Configurable repetition count
  • Success celebration animation

UsageTimer

• Purpose: Tracks device usage time and triggers locks
• Features:
  • Real-time usage tracking
  • Visual progress indicators
  • Configurable time limits (daily, session)
  • Break reminders
  • Usage statistics and reports

LockScreen

• Purpose: Overlay that blocks access until verse task completion
• Features:
  • Full-screen overlay blocking all interactions
  • Verse selection interface
  • Integration with VerseInput component
  • Emergency override options
  • Lock screen customization

Settings

• Purpose: UI for app configuration and preferences
• Features:
  • Enforcement mode selection (strict/gentle)
  • Time limit configuration
  • Verse repetition count settings
  • Notification preferences
  • Theme selection (light/dark)

Service Layer

VerseService

• CRUD Operations: Create, read, update, delete verses
• Features:
  • Preset verse management
  • Custom verse storage
  • Verse categorization
  • Search and filtering
  • Import/export functionality

StorageService

• Persistence: Local data storage using IndexedDB (Dexie.js)
• Features:
  • Verse database management
  • Settings persistence
  • Usage statistics storage
  • Offline data access
  • Data migration handling

TimeService

• Time Management: Track elapsed time and manage thresholds
• Features:
  • Usage time tracking
  • Reset logic (daily, weekly)
  • Threshold management
  • Break scheduling
  • Time zone handling

PWA Setup Checklist

manifest.json

• App name and short name
• Icons (192x192, 512x512, Apple touch icon)
• Theme colors and background
• Display mode (standalone)
• Start URL and scope
• Orientation preferences

Service Worker

• Workbox integration for caching
• Offline functionality
• Background sync
• Push notifications
• Cache strategies

Installable PWA

• Install prompt handling
• Beforeinstallprompt event
• Installation instructions
• App icon placement
• Splash screen configuration

Tools & Libraries

Core Dependencies

• React 18+: Component library
• Vite: Build tool and dev server
• Dexie.js: IndexedDB wrapper for data persistence
• Workbox: Service worker and caching utilities

UI & Styling

• Tailwind CSS: Utility-first CSS framework
• Headless UI: Unstyled accessible components
• React Icons: Icon library
• Framer Motion: Animation library

Utilities

• date-fns: Date manipulation
• uuid: Unique identifier generation
• localforage: Enhanced local storage
• react-hot-toast: Toast notifications

Development

• ESLint: Code linting
• Prettier: Code formatting
• Husky: Git hooks
• Lint-staged: Pre-commit linting

Development Roadmap

Phase 1: Scaffold React + PWA Shell (Week 1)

• Initialize React project with Vite
• Set up PWA configuration
• Configure Tailwind CSS
• Create basic project structure
• Set up development environment

Phase 2: File Structure + Placeholder Components (Week 1-2)

• Create all component directories
• Add placeholder components
• Set up routing structure
• Create basic layouts
• Add navigation components

Phase 3: Data Schema Definition (Week 2)

• Define verse data structure
• Design settings schema
• Plan usage tracking schema
• Set up IndexedDB tables
• Create data migration strategy

Phase 4: Verse Library + Input System (Week 3-4)

• Build verse library interface
• Implement verse CRUD operations
• Create typing validation system
• Add progress tracking
• Implement error handling

Phase 5: Timer & Lock Screen Logic (Week 4-5)

• Build usage timer component
• Implement lock screen overlay
• Create timer-lock integration
• Add break reminder system
• Implement emergency override

Phase 6: Settings + Persistence (Week 5-6)

• Create settings interface
• Implement data persistence
• Add configuration validation
• Create backup/restore functionality
• Add data export/import

Phase 7: Style and UX Polish (Week 6-7)

• Apply consistent styling
• Add animations and transitions
• Implement responsive design
• Create loading states
• Add accessibility features

Phase 8: PWA Testing + Notifications (Week 7-8)

• Test offline functionality
• Implement push notifications
• Add install prompts
• Performance optimization
• Cross-browser testing

Getting Started

1. Clone the repository
2. Install dependencies: npm install
3. Start development server: npm run dev
4. Build for production: npm run build
5. Test PWA features: npm run preview

Contributing

Please read the contributing guidelines before submitting pull requests.

License

This project is licensed under the MIT License.