QUICKSTART.txt

╔════════════════════════════════════════════════════════════════════════════╗
║                                                                            ║
║           🎮 JAVA TRIVIA Q&A APPLICATION - QUICK START 🎮                 ║
║                                                                            ║
║                    Production-Ready Maven Project                         ║
║                                                                            ║
╚════════════════════════════════════════════════════════════════════════════╝

📋 SYSTEM REQUIREMENTS
═══════════════════════════════════════════════════════════════════════════

✓ Java 21 JDK or later
✓ Maven 3.8.0 or later
✓ Windows, macOS, or Linux
✓ Internet connection (for live version only)

═══════════════════════════════════════════════════════════════════════════

🚀 INSTALLATION
═══════════════════════════════════════════════════════════════════════════

1. VERIFY JAVA INSTALLATION
   java --version             (should show Java 21+)

2. VERIFY MAVEN INSTALLATION
   mvn --version             (should show Maven 3.8+)

3. DOWNLOAD PROJECT
   Extract the project files to a directory

4. NAVIGATE TO PROJECT
   cd trivia-qa

═══════════════════════════════════════════════════════════════════════════

▶️  RUN THE APPLICATION
═══════════════════════════════════════════════════════════════════════════

COMPILE FIRST
   mvn clean compile

DEMO VERSION (No Internet Required)
   mvn exec:java -Dexec.mainClass="com.trivia.app.TriviaAppDemo"

LIVE VERSION (Requires Internet)
   mvn exec:java -Dexec.mainClass="com.trivia.app.TriviaApp"

CREATE EXECUTABLE JAR
   mvn clean package
   java -jar target/trivia-qa-app.jar

═══════════════════════════════════════════════════════════════════════════

💻 USING IDE
═══════════════════════════════════════════════════════════════════════════

INTELLIJ IDEA:
  1. Open project (File > Open)
  2. Select pom.xml or project directory
  3. Right-click on TriviaAppDemo.java
  4. Select "Run 'TriviaAppDemo.main()'"

ECLIPSE:
  1. Import project (File > Import > Maven > Existing Maven Projects)
  2. Right-click on TriviaAppDemo.java
  3. Select "Run As > Java Application"

VS CODE:
  1. Open project directory
  2. Install Extension Pack for Java
  3. Right-click on TriviaAppDemo.java
  4. Select "Run" or "Debug"

═══════════════════════════════════════════════════════════════════════════

📁 PROJECT STRUCTURE
═══════════════════════════════════════════════════════════════════════════

trivia-qa/
├── pom.xml                  - Maven configuration
├── src/
│   └── main/java/com/trivia/app/
│       ├── TriviaApp.java       - Live version (450 lines)
│       └── TriviaAppDemo.java   - Demo version (350 lines)
├── target/                  - Build output
│   └── trivia-qa-app.jar   - Executable JAR
└── README.md               - Full documentation

═══════════════════════════════════════════════════════════════════════════

🎮 HOW TO PLAY
═══════════════════════════════════════════════════════════════════════════

1. Application loads 10 trivia questions
2. Questions display with category and difficulty
3. Choose your answer (press 1, 2, 3, or 4)
4. See immediate feedback
5. Get final score when done

═══════════════════════════════════════════════════════════════════════════

🔧 USEFUL MAVEN COMMANDS
═══════════════════════════════════════════════════════════════════════════

# Clean build artifacts
mvn clean

# Compile source code
mvn compile

# Run demo
mvn exec:java -Dexec.mainClass="com.trivia.app.TriviaAppDemo"

# Run live
mvn exec:java -Dexec.mainClass="com.trivia.app.TriviaApp"

# Build JAR
mvn package

# Run JAR
java -jar target/trivia-qa-app.jar

# Show dependencies
mvn dependency:tree

# Install locally
mvn install

# Generate documentation
mvn javadoc:javadoc

# Full build and test
mvn clean compile package

═══════════════════════════════════════════════════════════════════════════

⚙️ CONFIGURATION
═══════════════════════════════════════════════════════════════════════════

Edit in TriviaApp.java or TriviaAppDemo.java:

class Config {
    public static final String API_ENDPOINT = 
        "https://opentdb.com/api.php?amount=10";
    public static final int REQUEST_TIMEOUT = 10000;  // 10 seconds
    public static final int MAX_RETRIES = 3;          // retry attempts
    public static final int RETRY_DELAY = 1000;      // 1 second delay
}

CHANGE LOGGING LEVEL:
    LogLevel.DEBUG      - Verbose output
    LogLevel.INFO       - Standard output
    LogLevel.WARNING    - Warnings + errors only
    LogLevel.ERROR      - Errors only

═══════════════════════════════════════════════════════════════════════════

❓ TROUBLESHOOTING
═══════════════════════════════════════════════════════════════════════════

"java: command not found"
  → Install Java 21 JDK from https://www.oracle.com/java/technologies/

"mvn: command not found"
  → Install Maven from https://maven.apache.org/download.cgi
  → Add Maven bin directory to PATH

"JAVA_HOME is not set"
  → Set JAVA_HOME to JDK installation directory
  → Linux/macOS: export JAVA_HOME=/path/to/jdk21
  → Windows: Set via System Properties

"Could not find artifact com.google.code.gson:gson"
  → Run: mvn dependency:resolve
  → Or: mvn clean install

"HttpTimeoutException: Connection refused"
  → Use demo version (no internet needed)
  → Or check internet connection

"Invalid input error"
  → Enter numbers 1-4 only
  → Press Enter after each selection

═══════════════════════════════════════════════════════════════════════════

✨ FEATURES
═══════════════════════════════════════════════════════════════════════════

✓ 10 random trivia questions (live) or 5 mock questions (demo)
✓ Multiple-choice answers with randomization
✓ Immediate feedback on each answer
✓ Final score with percentage calculation
✓ Detailed question-by-question results
✓ Automatic retry on network failure
✓ Structured logging and error handling
✓ Production-ready architecture
✓ Java 21 LTS with latest features
✓ Maven build system

═══════════════════════════════════════════════════════════════════════════

📚 WHAT'S INCLUDED
═══════════════════════════════════════════════════════════════════════════

Source Code:
  • TriviaApp.java         - Main implementation (450 lines)
  • TriviaAppDemo.java     - Demo with mock data (350 lines)

Build Configuration:
  • pom.xml               - Maven project configuration

Documentation:
  • README.md             - Complete guide (14 KB)
  • QUICKSTART.txt        - This file

═══════════════════════════════════════════════════════════════════════════

🎯 QUICK COMMANDS
═══════════════════════════════════════════════════════════════════════════

Try Demo (Fastest Way):
  cd trivia-qa
  mvn clean compile
  mvn exec:java -Dexec.mainClass="com.trivia.app.TriviaAppDemo"

Or Build JAR:
  mvn clean package
  java -jar target/trivia-qa-app.jar

═══════════════════════════════════════════════════════════════════════════

📖 FOR MORE INFORMATION
═══════════════════════════════════════════════════════════════════════════

See README.md for:
  ✓ Full installation instructions
  ✓ Architecture overview
  ✓ All configuration options
  ✓ Extension points and customization
  ✓ Performance characteristics
  ✓ Design patterns used
  ✓ Troubleshooting guide
  ✓ Future enhancements

═══════════════════════════════════════════════════════════════════════════

🎉 YOU'RE READY TO PLAY!
═══════════════════════════════════════════════════════════════════════════

DEMO (No Internet):
  mvn exec:java -Dexec.mainClass="com.trivia.app.TriviaAppDemo"

LIVE (With Internet):
  mvn exec:java -Dexec.mainClass="com.trivia.app.TriviaApp"

EXECUTABLE JAR:
  mvn package
  java -jar target/trivia-qa-app.jar

═══════════════════════════════════════════════════════════════════════════

Made with ❤️ following enterprise architecture best practices.

Production-Ready Java • Java 21 LTS • Maven Build • Gson JSON

════════════════════════════════════════════════════════════════════════════