Frontend Architecture

js/
├── app_v2.js              # Application entry point
├── router.js              # Hash-based SPA router
├── services/
│   ├── api.js             # Backend API client
│   └── state.js           # Global state management
├── views/
│   ├── home.js            # Dashboard with stats
│   ├── explore.js         # Browse all courses
│   ├── learning.js        # In-progress courses
│   ├── route.js           # Learning path detail
│   ├── course.js          # Course modules view
│   └── player.js          # Video player + navigation
└── components/
    ├── navbar.js          # Top navigation bar
    └── card.js            # Course/route cards

document.addEventListener('DOMContentLoaded', async () => {
    console.log('🚀 Initializing Platzi Viewer 2.0...');
    const app = document.getElementById('app');

    // Show loading while data loads
    app.innerHTML = `
        <div class="loading">
            <div class="loading-spinner"></div>
            <p>Cargando plataforma...</p>
        </div>
    `;

    try {
        await state.init();
    } catch (error) {
        // Display error with diagnostic info
        const code = error?.code || 'bootstrap_unavailable';
        // ... error UI
        return;
    }

    // Build layout shell
    app.innerHTML = `
        ${Navbar.render()}
        <div id="main-content"></div>
    `;

    // Start Router
    const router = new Router(routes);
    router.appContainer = document.getElementById('main-content');
    router.handleRoute();
});

const routes = {
    '#home': HomeView,
    '#explore': ExploreView,
    '#learning': LearningView,
    '#route/:catIdx/:routeIdx': RouteView,
    '#course/:catIdx/:routeIdx/:courseIdx': CourseView,
    '#player/:catIdx/:routeIdx/:courseIdx/:modIdx/:classIdx': PlayerView,
};

async handleRoute() {
    const hash = window.location.hash || '#home';
    let match = null;
    let route = null;
    let params = {};

    for (const [path, viewClass] of Object.entries(this.routes)) {
        // Convert route pattern to regex
        // #course/:catIdx/:routeIdx/:courseIdx -> ^#course/([^/]+)/([^/]+)/([^/]+)$
        const regexPath = '^' + path.replace(/:[^\s/]+/g, '([^/]+)') + '$';
        const regex = new RegExp(regexPath);
        const found = hash.match(regex);

        if (found) {
            match = found;
            route = viewClass;
            // Extract param names and values
            const paramNames = (path.match(/:[^\s/]+/g) || []).map(n => n.slice(1));
            paramNames.forEach((name, index) => {
                params[name] = decodeURIComponent(found[index + 1]);
            });
            break;
        }
    }

    if (!route) {
        // Default to home
        window.location.hash = '#home';
        return;
    }

    this.renderView(route, params);
}

async renderView(ViewClass, params) {
    this._stopAllMediaPlayback();  // Clean up video elements

    if (this.currentView && this.currentView.destroy) {
        this.currentView.destroy();  // Lifecycle cleanup
    }

    // Show loading
    this.appContainer.innerHTML = `
        <div class="loading">
            <div class="loading-spinner"></div>
        </div>
    `;

    try {
        this.currentView = new ViewClass(params);
        const html = await this.currentView.render();
        this.appContainer.innerHTML = html;

        if (this.currentView.mounted) {
            this.currentView.mounted();  // Post-render lifecycle
        }
    } catch (error) {
        console.error('Error rendering view:', error);
        // ... error UI
    }

    window.scrollTo(0, 0);
}

class StateService {
    coursesData = null;        // Bootstrap catalog
    progress = {};             // Class completion status
    listeners = [];            // Progress subscribers
    _courseDetailLoads = new Map();  // In-flight detail requests
    initWarnings = [];         // Non-fatal bootstrap errors
}

getClassKey(catIdx, routeIdx, courseIdx, modIdx, classIdx) {
    return `${catIdx}|${routeIdx}|${courseIdx}|${modIdx}|${classIdx}`;
}

markClassComplete(classKey) {
    this.progress[classKey] = {
        status: 'complete',
        completedAt: new Date().toISOString()
    };
    this.saveProgress();
}

markClassInProgress(classKey, time = 0) {
    const current = this.progress[classKey];
    if (!current || current.status !== 'complete') {
        this.progress[classKey] = {
            status: 'in_progress',
            lastWatched: new Date().toISOString(),
            watchTime: time
        };
        this.saveProgress();
    }
}

queueServerSync() {
    if (this._syncTimer) {
        clearTimeout(this._syncTimer);
    }

    this._syncTimer = setTimeout(() => {
        this._syncTimer = null;
        this.saveServerProgress();
    }, 400);  // Debounced sync (400ms)
}

async saveServerProgress() {
    try {
        await ApiService.saveProgress(this.progress);
    } catch (e) {
        console.warn('Error saving server progress:', e?.code || e);
    }
}

async ensureCourseDetail(catIdx, routeIdx, courseIdx = 0) {
    const course = this.getCourse(catIdx, routeIdx, courseIdx);
    const route = this.getRoute(catIdx, routeIdx);
    if (!course || !route) return null;
    if (this.isCourseDetailLoaded(course)) return course;

    const key = `${catIdx}|${routeIdx}|${courseIdx}`;
    if (this._courseDetailLoads.has(key)) {
        return this._courseDetailLoads.get(key);  // Dedup concurrent requests
    }

    const loadPromise = (async () => {
        const payload = await ApiService.getCourseDetail(catIdx, routeIdx, courseIdx, 2);
        const detail = payload?.course;
        if (!detail) throw new Error('course_detail_invalid_payload');

        // Merge detail into in-memory cache
        if (route.isCourse) {
            cat.routes[routeIdx] = detail;
        } else {
            courses[courseIdx] = detail;
            cat.routes[routeIdx].courses = courses;
        }

        return this.getCourse(catIdx, routeIdx, courseIdx);
    })();

    this._courseDetailLoads.set(key, loadPromise);
    try {
        return await loadPromise;
    } finally {
        this._courseDetailLoads.delete(key);
    }
}

static _buildError(code, cause = null) {
    const error = new Error(code);
    error.code = code;
    if (cause) error.cause = cause;
    return error;
}

static async _fetchWithTimeout(url, options = {}, timeoutMs = DEFAULT_TIMEOUT_MS) {
    const controller = new AbortController();
    const timer = window.setTimeout(() => controller.abort(), timeoutMs);
    try {
        return await fetch(url, {
            ...options,
            signal: controller.signal,
        });
    } catch (error) {
        if (error?.name === 'AbortError') {
            throw this._buildError('request_timeout', error);
        }
        throw error;
    } finally {
        window.clearTimeout(timer);
    }
}

static async getBootstrap(retries = 8) {
    let lastError = null;
    for (let i = 0; i < retries; i++) {
        try {
            const response = await this._fetchWithTimeout(
                `${API_URL}/api/bootstrap`,
                { cache: 'no-store' },
                10000
            );
            if (!response.ok) throw this._buildError(`bootstrap_http_${response.status}`);

            const data = await response.json();
            if (data?.categories?.length > 0) {
                console.log('🚀 Bootstrap loaded:', data.stats);
                return data;
            }

            lastError = this._buildError('bootstrap_empty');
            await this._wait(RETRY_DELAY_MS);  // 1200ms delay
        } catch (error) {
            lastError = error?.code ? error : this._buildError('bootstrap_network', error);
            if (i === retries - 1) break;
            await this._wait(RETRY_DELAY_MS);
        }
    }
    throw lastError || this._buildError('bootstrap_unavailable');
}

class ExampleView {
    constructor(params) {
        // Initialize with route params
        this.catIdx = parseInt(params.catIdx);
    }

    async render() {
        // Fetch required data
        const course = await state.ensureCourseDetail(...);
        
        // Return HTML string
        return `<div>...</div>`;
    }

    mounted() {
        // Post-render: attach event listeners, start video, etc.
        this.attachEventListeners();
    }

    destroy() {
        // Cleanup: remove listeners, stop timers, etc.
        clearInterval(this.timer);
    }
}

export default class PlayerView {
    constructor(params) {
        this.catIdx = parseInt(params.catIdx);
        this.routeIdx = parseInt(params.routeIdx);
        this.courseIdx = parseInt(params.courseIdx);
        this.modIdx = parseInt(params.modIdx);
        this.classIdx = parseInt(params.classIdx);

        this._videoEl = null;
        this._isCompatibilityModeActive = false;
        this._syncIssueResyncHits = 0;
        // ... extensive state for A/V sync detection
    }
}

export const Navbar = {
    render() {
        return `
            <nav class="navbar">
                <a href="#home" class="nav-link">🏠 Inicio</a>
                <a href="#explore" class="nav-link">🔍 Explorar</a>
                <a href="#learning" class="nav-link">📚 Aprendiendo</a>
            </nav>
        `;
    },

    updateActive() {
        document.querySelectorAll('.nav-link').forEach(link => {
            const href = link.getAttribute('href');
            const isActive = window.location.hash.startsWith(href);
            link.classList.toggle('active', isActive);
        });
    },

    init() {
        window.addEventListener('hashchange', () => this.updateActive());
    }
};

// Examples:
'bootstrap_http_500'        // Server returned 500
'bootstrap_empty'           // Response had no categories
'bootstrap_network'         // Network failure
'course_detail_not_found'   // 404 from API
'request_timeout'           // AbortController timeout

try {
    await state.init();
} catch (error) {
    const code = error?.code || 'bootstrap_unavailable';
    const endpoint = inferEndpointFromErrorCode(code);
    app.innerHTML = `
        <div class="loading">
            <div style="font-size: 3rem">⚠️</div>
            <p>Error al conectar con el servidor</p>
            <p style="font-size: 0.85rem">
                Código: <code>${code}</code>
                • Endpoint: <code>${endpoint}</code>
            </p>
            <p>Verifica diagnóstico en: <code>/api/cache-meta</code></p>
        </div>
    `;
    return;
}