docs/website/GETTING_STARTED.md

✅ GETTING STARTED CHECKLIST

Use this checklist to ensure everything is working properly.

---

🟢 PHASE 1: Environment Setup (5 minutes)

Step 1: Verify Python Installation

• Open PowerShell in project root
• Run: .venv\Scripts\python.exe --version
• Expected: Python 3.11+ (e.g., Python 3.11.0)
• If fails: Install Python or activate venv

Step 2: Check Dependencies

• Run: python test_system.py
• Look for: ✅ "ALL TESTS COMPLETED SUCCESSFULLY!"
• Check: spaCy model loaded
• Check: Whisper model loaded
• If fails: Run pip install -r requirements.txt then python -m spacy download en_core_web_sm

Step 3: Verify Node.js (for Frontend)

• Open new PowerShell window
• Run: node --version
• Expected: v18+ (e.g., v22.11.0)
• Run: npm --version
• Expected: 10+ (e.g., 10.9.0)
• If fails: Download from https://nodejs.org/

Step 4: Check Frontend Dependencies

• Navigate: cd frontend
• Run: npm install (only if node_modules missing)
• Should complete within 2 minutes
• If fails: Check npm/node installation

---

🟡 PHASE 2: Start Services (3 minutes)

Option A: Automated Startup (Easiest)

• In project root, double-click: START.bat
• Watch three windows open
• Wait 10-15 seconds for models to load
• All three should show "running" or "ready"

Option B: Manual Startup (Full Control)

Window 1 - Backend API

• Open PowerShell in project root
• Run: .venv\Scripts\python.exe -m uvicorn src.api.server:app --reload --port 8000
• Wait for: "Application startup complete"
• Keep window open

Window 2 - Frontend Dev Server

• Open new PowerShell
• Navigate: cd frontend
• Run: npm run dev
• Wait for: "Local: http://localhost:5173"
• Keep window open

Window 3 - Browser

• Open Web Browser
• Navigate to: http://localhost:5173
• You should see the sentiment analysis UI

---

🟢 PHASE 3: Verify Backend (2 minutes)

Test 1: Health Check

• Open browser and go to: http://localhost:8000/health
• Expected response:

  {"status": "ok", "spacy_model": "...", "whisper_model": "small", "whisper_device": "cpu"}
  

• ✅ If you see this, backend is working

Test 2: Simple Text Analysis

• Open New PowerShell Window
• Run:

  $body = @{text="The camera is great but battery is bad"}
  Invoke-RestMethod -Uri "http://localhost:8000/api/analyze" -Method Post -Body $body
  

• Expected: JSON response with "products" array
• Check: Products include "camera" and "battery"
• ✅ If successful, API is working

Test 3: Using Test Client

• Open: test_client.html (in project root)
• In browser: Type text in textarea
• Click: "Analyze" button
• Watch: Real-time results panel
• Expected: Products extracted with sentiment scores
• ✅ If working, API integration is good

---

🔵 PHASE 4: Test Frontend UI (5 minutes)

Test 1: Text Input

• Frontend should be open at http://localhost:5173
• Click: Text area in "Input" section
• Type: "The product is excellent but shipping took forever"
• Click: "Analyze" button
• Wait: For processing to complete
• Expected:
  • Results show in right panel
  • "product" sentiment appears correct
  • "shipping" sentiment appears negative
• ✅ Text input working

Test 2: Pipeline Visualization

• Check the pipeline shows steps:
  • ✓ Uploading
  • ✓ Speech-to-text (skipped for text)
  • ✓ NLP extraction
  • ✓ Sentiment analysis
• Each should show "completed" status
• ✅ Pipeline display working

Test 3: Results Display

• Results panel should show:
  • Sentiment gauge (circular)
  • Positive/Neutral/Negative breakdown
  • Product table with items
• Click: On a product item
• Expected: Highlights to appear in transcript
• ✅ Results display working

Test 4: Audio Input (Optional)

• Click: "Input Type" dropdown
• Select: "Audio File"
• File selector appears
• Choose: Any .wav or .mp3 file
• Click: "Analyze"
• Wait: 3-10 seconds (longer for audio)
• Expected: Same results as text
• ✅ Audio processing working

---

🟢 PHASE 5: Verify Results Accuracy (3 minutes)

Sample Test Case 1

Input: "The camera quality is stunning with sharp details. 
        Battery drains quickly though. Performance is excellent."

Expected Results:
- camera: POSITIVE (score > 0.7)
- battery: NEGATIVE (score < -0.5)
- performance: POSITIVE (score > 0.7)
- Positive%: 67%
- Negative%: 33%

Sample Test Case 2

Input: "Excellent customer service but product is fragile"

Expected Results:
- customer service: POSITIVE
- product: NEGATIVE (due to "fragile")
- Positive%: 50%
- Negative%: 50%

Sample Test Case 3

Input: "The device works fine"

Expected Results:
- device: NEUTRAL or slightly POSITIVE
- Mostly NEUTRAL or balanced sentiment

---

🔴 PHASE 6: Troubleshooting (If Something Fails)

Problem: "API Connection Refused"

Solution:

1. Check backend window is running
2. Verify no other app uses port 8000
3. Restart backend:

   .venv\Scripts\python.exe -m uvicorn src.api.server:app --reload --port 8000
   

4. Try health check: http://localhost:8000/health

Problem: "Frontend Won't Load"

Solution:

1. Check frontend window is running
2. Verify no other app uses port 5173
3. Look for errors in terminal
4. Restart frontend:

   cd frontend && npm run dev
   

Problem: "spaCy Model Not Found"

Solution:

python -m spacy download en_core_web_sm

Problem: "Whisper Model Download Stuck"

Solution:

1. Press Ctrl+C to cancel
2. Ensure internet connection works
3. Try again:

   python -c "import whisper; whisper.load_model('small')"
   

Problem: "No Products Extracted"

Try:

• Longer input text (5+ sentences)
• More descriptive text (mention actual products)
• Use English language
• Example: "The phone camera is good and display is bright"

Problem: "Sentiment Scores Seem Wrong"

Check:

1. Are the products actually mentioned? (algorithm extracts nouns)
2. Is there adjective context? ("amazing camera" vs just "camera")
3. Try more obvious sentiment: "Absolutely terrible" vs "not great"
4. Context window might be isolating different phrase

---

🟢 FINAL VERIFICATION CHECKLIST

When everything is working:

• Backend console shows no error messages
• Frontend console (F12) shows no red errors
• http://localhost:8000/health returns 200 OK
• http://localhost:5173 loads the UI
• Test input produces sentiment scores
• Products are correctly extracted
• Sentiment labels match your expectations
• Export buttons work (JSON/PDF)
• No crashes or freezing

---

🎯 Quick Restart (If Something Breaks)

Complete Restart

1. Close all PowerShell windows
2. Close browser tabs
3. Run START.bat again
4. Or manually restart both terminals

Clean Test Run

# In project root
python test_system.py  # Should pass all tests

Verify Again

# Check health
curl http://localhost:8000/health

# Try test API request
$body = @{text="Test input"}
Invoke-RestMethod -Uri "http://localhost:8000/api/analyze" -Method Post -Body $body

---

🎉 Success Indicators

You'll know everything is working when:

1. ✅ Browser shows the sentiment analysis dashboard
2. ✅ You can type text and see results in < 1 second
3. ✅ Products are extracted from your input
4. ✅ Sentiment is labeled (positive/negative/neutral)
5. ✅ Confidence scores appear (0-1 range)
6. ✅ No error messages in any console
7. ✅ Tests pass when you run python test_system.py

---

📚 Using the System

Basic Workflow

1. Paste Text or Upload Audio in the input section
2. Click Analyze button
3. Watch the real-time pipeline
4. View Results in the dashboard
5. Export as JSON or PDF if needed

Advanced Features

• Multi-language support (select language before upload)
• Audio transcription (Whisper)
• Confidence scoring
• Context highlighting
• Product deduplication
• Trend analysis

---

📈 Next Steps

Short-term

• Test with your own data
• Try different languages
• Test with audio files
• Export results

Medium-term

• Add more test cases
• Customize product categories
• Adjust sentiment thresholds
• Build integrations

Long-term

• Deploy to production
• Add database for history
• Build API clients (Python, JavaScript, etc.)
• Create dashboard for analytics

---

📞 Support

If you get stuck:

1. Read the SYSTEM_GUIDE.md
2. Check API_DOCUMENTATION.md
3. Run: python test_system.py
4. Review terminal output for error messages
5. Check test_client.html for manual API testing

---

✅ Verification Summary

Phase 1 (Environment):  ⏳ → ✅
Phase 2 (Services):     ⏳ → ✅
Phase 3 (Backend):      ⏳ → ✅
Phase 4 (Frontend):     ⏳ → ✅
Phase 5 (Accuracy):     ⏳ → ✅
Phase 6 (Crisis):       N/A (hopefully!)

Overall Status: 🟢 READY

---

Checklist Version: 1.0 Last Updated: April 13, 2026 Status: Production Ready