# 💻 Developer Guide

Want to contribute, fork, or understand how LearnAI TV works under the hood? You're in the right place!

🚀 Quick Start

Prerequisites

• Git installed

• Modern browser

• Code editor (VS Code recommended)

• (Optional) n8n instance for backend testing

Clone & Run

# Clone repository
git clone https://github.com/iavendas62-collab/learnai-tv.git
cd learnai-tv

# No build step needed! Just open in browser:
open index.html

# Or use a local server:
python -m http.server 8000
# Visit: http://localhost:8000

That's it! No npm install, no dependencies, no build tools.

---

📁 Project Structure

learnai-tv/
├── index.html          # Main HTML structure
├── styles.css          # Complete design system
├── app.js             # All application logic
├── README.md          # Project overview
└── docs/              # This documentation (GitBook)
    ├── introduction.md
    ├── features.md
    ├── architecture.md
    ├── user-guide.md
    └── developer-guide.md

Why so simple?

• ✅ No build complexity

• ✅ Easy to understand for students

• ✅ Deploy anywhere (GitHub Pages, Netlify, Vercel)

• ✅ Fast load times (no frameworks)

---

🏗️ Architecture Overview

Frontend (Static HTML/CSS/JS)

Technology Choices:

Tech	Why We Chose It
Vanilla JS	No React overhead, easier debugging
CSS Grid/Flexbox	Modern layout without frameworks
KaTeX CDN	Math rendering without local build
No bundler	Direct deployment, transparent code

Backend (n8n Workflow)

Hosted on: Easypanel (Docker containers) Endpoint: https://iavendas-n8n.tkxtrv.easypanel.host/webhook/[id]

Workflow Components:

1. Webhook node (receives POST)

2. AI Agent node (orchestrates LLM + tools)

3. OpenAI Chat Model (GPT-4.1-mini)

4. Memory Buffer (session storage)

5. 7x Tool nodes (MCP servers + Wolfram)

6. Response node (returns JSON)

---

🔧 Configuration

Environment Variables

Frontend (app.js):

// Line 7-8
const WEBHOOK_URL = 'https://iavendas-n8n.tkxtrv.easypanel.host/webhook/313ee9cc-b465-4154-8cc9-4e8145dbd38b';

To use your own n8n instance:

1. Deploy n8n (Easypanel, Railway, or self-host)

2. Import workflow JSON (Hackathon CS girlies (final).json)

3. Update WEBHOOK_URL in app.js

4. Configure API credentials (OpenAI, Wolfram)

API Credentials Needed

Service	Purpose	Get Key
OpenAI	Primary LLM	https://platform.openai.com
Wolfram Alpha	Math computation	https://products.wolframalpha.com/api
Google Docs API	Curriculum content	https://console.cloud.google.com

---

🛠️ Development Workflow

1. Frontend Changes

Edit HTML:

# Open in your editor
code index.html

# Make changes
# Save
# Refresh browser (no build needed!)

Edit CSS:

code styles.css

# Live reload with:
npx live-server
# Or use browser dev tools for instant preview

Edit JavaScript:

code app.js

# Debug in browser console (F12)
console.log() // Your best friend!

2. Testing Locally

Open Browser DevTools (F12):

// Test API call
const response = await fetch(WEBHOOK_URL, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    subject: 'Matemática',
    study_mode: 'list_topics',
    question: 'Liste 8 tópicos de matemática'
  })
});
console.log(await response.json());

// Test quiz parser
const quizText = `Pergunta 1: Quanto é 2+2?
a) 3
b) 4
c) 5
d) 6
Resposta correta: b`;

console.log(parseQuiz(quizText));

// Test topic extraction
const topicsText = `1. Números Naturais
2. Adição
3. Subtração`;

console.log(extractTopics(topicsText));

3. Deploy to Production

# Commit changes
git add .
git commit -m "Fix quiz parsing for História"

# Push to GitHub
git push origin main

# GitHub Pages auto-deploys in ~30 seconds
# Visit: https://iavendas62-collab.github.io/learnai-tv/

---

📊 Code Architecture

State Management

Global Variables (app.js lines 10-22):

let currentSubject = null;      // Active subject (Matemática, etc)
let currentTopic = null;        // Active topic (Geometria, etc)
let currentActivity = null;     // Active mode (topics, chat, quiz)
let chatHistory = [];          // Conversation messages
let quizQuestions = [];        // Current quiz data
let currentQuizIndex = 0;      // Quiz progress
let quizScore = 0;             // Correct answers
let userScore = 0;             // Total points
let userLevel = 1;             // Gamification level
let userXP = 0;                // Experience points

Why Globals?

• Single-page application (no routing)

• State resets on page reload

• Easier debugging (inspect in console)

• No state management library needed

Function Organization

app.js structure (~1,200 lines):

Lines 1-30:    Configuration & State
Lines 31-70:   Gamification System
Lines 71-110:  Navigation & Subject Selection
Lines 111-300: Study Topics (list, render, select)
Lines 301-450: Chat System (send, render, LaTeX)
Lines 451-750: Quiz System (generate, parse, render, scoring)
Lines 751-850: Challenge Mode
Lines 851-900: Keyboard Navigation
Lines 901-920: Initialization

Key Functions

Topic Extraction:

function extractTopics(text) {
  // 1. Try numbered lists (1. Topic, 2. Topic)
  // 2. Try bullet lists (• Topic, - Topic)
  // 3. Try plain newlines
  // 4. Fallback to hardcoded defaults
  return topics; // Array of 8 strings
}

Quiz Parsing:

function parseQuizMultiple(text) {
  // Split by separators (---, Pergunta X:, etc)
  // Parse each question independently
  // Validate (has question, 2+ options, correct answer)
  return questions; // Array of quiz objects
}

API Call:

async function startQuiz() {
  // Show loading screen
  // Call n8n webhook with timeout
  // Parse response
  // Render quiz or fallback
  // Handle errors gracefully
}

---

🎨 Design System

Color Palette

/* Primary Colors */
--primary-blue: #3b82f6;      /* Buttons, highlights */
--primary-purple: #9333ea;    /* Active states, gradients */
--dark-purple: #7c3aed;       /* Hover states */

/* Semantic Colors */
--success-green: #10b981;     /* Correct answers */
--error-red: #ef4444;         /* Wrong answers */
--warning-yellow: #f59e0b;    /* Alerts */
--gold: #ffd700;              /* Points, rewards */

/* Neutral Colors */
--dark-bg: #1e1b4b;           /* Page background */
--medium-dark: #312e81;       /* Gradients */
--light-gray: #d1d5db;        /* Text */
--white: #ffffff;             /* Content areas */

Typography

/* Font Sizes */
--heading-xl: 3rem;    /* Welcome screen */
--heading-lg: 2.5rem;  /* Page titles */
--heading-md: 2rem;    /* Section headers */
--body-lg: 1.8rem;     /* Quiz questions */
--body-md: 1.6rem;     /* Content text */
--body-sm: 1.4rem;     /* Explanations */

/* Font Family */
font-family: 'Arial', sans-serif; /* System default for speed */

Spacing System

/* Padding/Margin Scale (4px base) */
--space-xs: 8px;
--space-sm: 15px;
--space-md: 20px;
--space-lg: 30px;
--space-xl: 40px;

Component Patterns

Button Variants:

.btn-primary   /* Blue, main actions */
.btn-secondary /* Gray, cancel/back */
.btn-success   /* Green, positive actions */

Card Components:

.activity-card  /* Clickable activity cards */
.topic-item     /* Topic selection buttons */
.quiz-option    /* Quiz answer choices */

---

🧪 Testing

Manual Testing Checklist

Functional Tests:

• All 6 subjects load

• Topics generate (or fallback works)

• Chat sends/receives messages

• Quiz shows 5 questions

• Scoring system works

• Level-up animation triggers

• Keyboard navigation functional

Cross-Browser Tests:

• Chrome (latest)

• Firefox (latest)

• Safari (iOS + macOS)

• Edge (latest)

Responsive Tests:

• Desktop (1920x1080)

• Laptop (1366x768)

• Tablet (768x1024)

• Mobile (375x667)

Automated Testing (Future)

// Potential test framework setup
// Currently not implemented (hackathon scope)

describe('Quiz System', () => {
  it('should parse valid quiz text', () => {
    const input = `Pergunta 1: Test?
    a) Option A
    b) Option B
    Resposta correta: a`;
    
    const result = parseQuiz(input);
    expect(result.question).toBe('Test?');
    expect(result.options.a).toBe('Option A');
    expect(result.correct).toBe('a');
  });
});

---

🔌 API Reference

Webhook Endpoint

URL: POST https://iavendas-n8n.tkxtrv.easypanel.host/webhook/313ee9cc-b465-4154-8cc9-4e8145dbd38b

Headers:

{
  "Content-Type": "application/json"
}

Request Body:

{
  "subject": "Matemática",
  "topic": "Geometria Básica",
  "study_mode": "explicacao",
  "question": "Explique triângulos para criança de 8 anos"
}

Response:

{
  "answer": "Um triângulo é uma forma com 3 lados... [AI explanation]"
}

Study Modes

Mode	Purpose	Expected Response
list_topics	Get 8 topic names	Numbered list of topics
explicacao	Explain a topic	Detailed explanation with examples
chat	Conversational Q&A	Natural language answer
quiz	Generate 5 questions	Formatted quiz with separators
challenge	Generate 1 hard question	Single quiz question

---

🐛 Common Issues & Fixes

Issue: Topics show "Tópico 1, Tópico 2"

Cause: AI didn't respond with proper format, or parsing failed.

Fix:

// Check extractTopics() function (line ~165)
// Add more regex patterns for AI response formats

const patterns = [
  /^\d+[\.\)]\s*(.+)$/gm,     // Existing
  /^Topic \d+:\s*(.+)$/gm,    // Add: English format
  /^\d+\.\s*\*\*(.+)\*\*$/gm  // Add: Bold markdown
];

Issue: Quiz parsing fails

Cause: AI used unexpected format.

Debug:

// Add this to parseQuizMultiple() (line ~580)
console.log('🔍 QUIZ DEBUG - Raw text:', text);
console.log('🔍 QUIZ DEBUG - Split result:', parts);

Solution: Expand parseQuiz() to handle more formats.

Issue: Chat doesn't show math formulas

Cause: KaTeX not loading or wrong syntax.

Fix:

// Verify KaTeX CDN loaded (check Network tab)
// Ensure LaTeX wrapped in $ or $$

// Correct: $x^2$
// Wrong: x^2

---

🚀 Deployment Guide

GitHub Pages (Current)

# Already configured! Just push:
git push origin main

# Settings → Pages → Source: main branch → / (root)

Alternative: Vercel

vercel login
vercel --prod

# Auto-detects static site
# Deploys in ~10 seconds

Alternative: Netlify

# Drag & drop folder to netlify.com/drop
# Or connect GitHub repo

n8n Deployment

Option 1: Easypanel (Current)

• Docker-based

• One-click deploy

• Includes SSL

Option 2: Railway

railway login
railway init
railway up

Option 3: Self-Host

docker run -d \
  -p 5678:5678 \
  -v ~/.n8n:/home/node/.n8n \
  n8nio/n8n

---

🤝 Contributing

How to Contribute

1. Fork the repository

2. Create a feature branch

   git checkout -b feature/improve-quiz-parser

1. Make your changes

2. Test thoroughly

3. Commit with clear message

   git commit -m "Improve quiz parser to handle bold markdown"

1. Push and create PR

   git push origin feature/improve-quiz-parser

Code Style Guidelines

JavaScript:

• Use const/let, not var

• Descriptive function names: extractTopics() not getT()

• Comments for complex logic

• Error handling with try/catch

• Console logs for debugging (remove in production)

CSS:

• BEM-like naming: .quiz-option, .btn-primary

• Group related styles

• Use CSS variables for colors

• Mobile-first media queries

HTML:

• Semantic tags: <nav>, <main>, <section>

• Accessible: aria-label, tabindex, alt text

• No inline styles (use classes)

Feature Ideas

Good First Issues:

• Add Spanish language support

• Create dark mode toggle

• Add sound effects for correct/wrong answers

• Implement local storage for progress persistence

• Add more subjects (Art, Music, Physical Education)

Advanced Features:

• Voice input for questions

• PDF export of quiz results

• Multiplayer quiz mode

• Teacher dashboard

• Parent progress reports

---

📚 Additional Resources

Learning Resources

• Vanilla JS: https://javascript.info

• CSS Grid: https://cssgrid.io

• n8n Documentation: https://docs.n8n.io

• Wolfram API: https://products.wolframalpha.com/api/documentation

• MCP Protocol: https://modelcontextprotocol.io

Inspirations

• Duolingo - Gamification mechanics

• Khan Academy - Educational content structure

• Netflix - TV-style interface

• Quizlet - Quiz generation patterns

---

💬 Support

Questions?

• 📧 Email: [your-email]

• 💬 Discord: [hackathon-channel]

• 🐙 GitHub Issues: https://github.com/iavendas62-collab/learnai-tv/issues

Found a bug? Open an issue with:

1. Steps to reproduce

2. Expected vs actual behavior

3. Browser/device info

4. Screenshots if applicable

---

📜 License

This project was created for the CS Girlies Hackathon 2025.

Open Source License: MIT

You're free to:

• ✅ Use for personal/commercial projects

• ✅ Modify and distribute

• ✅ Fork and create derivatives

Attribution appreciated but not required! 🙏