Vintage Jokes Mobile App

A vintage-themed mobile application for browsing, searching, and managing a collection of classic jokes.

Features

Core Functionality

• Random Joke Display: Shows a random joke from the database on app launch

• Sequential Navigation: Navigate through jokes using Previous/Next buttons

• Joke Favoriting: Mark jokes as favorites with persistent storage

• Favorites View: Dedicated screen to view all favorite jokes

• Search Functionality: Search jokes by keywords or phrases

• Copy to Clipboard: Copy joke text to device clipboard

• Share Jokes: Share jokes using native device sharing

• Text-to-Speech: Have jokes read aloud using device TTS

User Interface

• Bottom Navigation: Three tabs (Jokes, Favorites, Search)
• Vintage Theme: Beige, brown, and cream color palette with serif fonts
• Responsive Design: Clean, intuitive interface optimized for mobile

Technical Implementation

• Architecture: Clean separation with Data/Logic/Presentation layers
• State Management: Uses Cubit pattern (flutter_bloc) for reactive state
• Database: SQLite database with ~900 pre-loaded jokes
• Offline First: 100% functional without internet connection

Dependencies

dependencies:
  flutter: sdk
  sqflite: ^2.3.0          # SQLite database operations
  flutter_bloc: ^8.1.3     # State management with Cubit
  equatable: ^2.0.5        # Value equality for state objects
  share_plus: ^7.2.1       # Native sharing functionality
  flutter_tts: ^3.8.3      # Text-to-speech capability
  path: ^1.8.3             # Path manipulation utilities

Project Structure

lib/
├── data/
│   └── joke_repository.dart    # Database operations and data access
├── logic/
│   ├── joke_cubit.dart        # Main joke state management
│   ├── joke_state.dart        # Joke-related states
│   ├── favorites_cubit.dart   # Favorites state management
│   ├── favorites_state.dart   # Favorites-related states
│   ├── search_cubit.dart      # Search state management
│   └── search_state.dart      # Search-related states
├── models/
│   └── joke.dart              # Joke data model
├── presentation/
│   └── screens/
│       ├── jokes_screen.dart     # Main jokes display screen
│       ├── favorites_screen.dart # Favorites list screen
│       └── search_screen.dart    # Search interface screen
├── theme/
│   └── vintage_theme.dart     # App theme configuration
└── main.dart                  # App entry point

Database Schema

The app uses a SQLite database with the following schema:

CREATE TABLE text_content (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    text_content TEXT,
    read TEXT,
    likes TEXT  -- Used as favorites flag ('1' = favorite, '' = not favorite)
);

Getting Started

1. Install Dependencies:

   flutter pub get

2. Run the App:

   flutter run

3. Build for Release:

   flutter build apk              # For Android
   flutter build ios              # For iOS

Usage

Main Screen (Jokes Tab)

• Displays a random joke on app launch
• Use Previous/Next buttons to navigate through jokes
• Tap Random button for a new random joke
• Tap heart icon to favorite/unfavorite jokes
• Use copy, share, and read-aloud buttons for additional actions

Favorites Tab

• Shows all jokes marked as favorites
• Tap any joke to view it in the main jokes screen
• Empty state shown when no favorites exist

Search Tab

• Enter keywords to search through all jokes
• Results update as you type
• Tap any result to view the joke in the main screen
• Shows result count and handles empty results gracefully

Architecture Details

State Management

The app uses the Cubit pattern for state management:

• JokeCubit: Manages current joke display and actions
• FavoritesCubit: Handles favorites list and updates
• SearchCubit: Manages search functionality and results

Data Layer

• JokeRepository: Encapsulates all database operations
• Joke Model: Represents joke data with proper serialization
• Database operations are asynchronous and include error handling

Theme

The vintage theme includes:

• Warm color palette (tans, browns, creams)
• Serif font family for classic appearance
• Consistent elevation and spacing
• Custom button and card styling

Requirements Compliance

This implementation satisfies all specified requirements:

✅ FR-01: Database Initialization - Automatic SQLite setup
✅ FR-02: Random Joke Display - Random joke on app start
✅ FR-03: Sequential Navigation - Previous/Next functionality
✅ FR-04: Joke Favoriting - Persistent favorite status
✅ FR-05: View Favorites - Dedicated favorites screen
✅ FR-06: Search Jokes - Keyword search functionality
✅ FR-07: Copy Joke - Clipboard integration
✅ FR-08: Share Joke - Native device sharing
✅ FR-09: Text-to-Speech - Device TTS integration

✅ UI-01: Bottom navigation with three tabs
✅ UI-02: Joke card with action buttons and navigation
✅ UI-03: Favorites list with navigation
✅ UI-04: Search input with results list

✅ NFR-01: High performance with local database
✅ NFR-02: Intuitive interface design
✅ NFR-03: Clean architecture with separated layers
✅ NFR-04: Consistent vintage theme design

License

This project is licensed under the Vintage Jokes Database and Application License.

Key License Terms:

• ✅ Personal & Educational Use: Free for non-commercial purposes
• ⚠️ Commercial Use: Requires permission and 20% revenue sharing
• 🔒 Database Protection: Proprietary joke collection with usage restrictions
• 📝 Attribution Required: Must credit original author Dhiraj Himani

The vintage jokes database contains curated content and is protected intellectual property. Any commercial use of this application or database requires prior written permission and includes mandatory revenue sharing terms.

For commercial licensing inquiries, please contact the project owner.

See the LICENSE file for complete terms and conditions.