Architecture

Commerce Learning Hub is a pure static, client-side web application. There is no backend, no database, and no build pipeline. Everything runs in the user's browser.

Core Principles

• Zero backend: All logic runs in JavaScript in the browser.
• No build tools: No npm, Webpack, Vite, or transpilers.
• Static hosting: Deployable on any static host (Cloudflare Pages, GitHub Pages, Netlify).
• Offline-first: Service Worker caches critical assets.
• Privacy-first: User data stays in localStorage; nothing is sent to servers.

Layered Architecture

1. Presentation Layer: HTML + CSS (semantic, accessible, responsive).
2. Design System: CSS variables in base.css, component styles in components.css.
3. Application Layer: app.js provides global services (theme, storage, toasts, navigation).
4. Module Layer: Each module in /modules/<name>/ is self-contained (HTML + CSS + JS).
5. Configuration Layer: config/config.js holds API keys and feature flags.

Data Flow

User input → Module JS validates → Calculation performed → Result rendered + chart updated → Optionally persisted to localStorage or exported.

Dependency Strategy

Libraries are loaded from CDN only when a module needs them. URLs are defined centrally in config/config.js under cdn. A small loader in each module's JS fetches the library on demand.

Folder Structure

commerce-learning-hub/
├── index.html              # Homepage
├── 404.html                # Custom 404
├── robots.txt              # Search engine rules
├── sitemap.xml             # XML sitemap
├── _headers                # Cloudflare Pages headers
├── config/
│   └── config.js           # API keys + feature flags
├── assets/
│   ├── css/
│   │   ├── base.css        # Reset, variables, typography
│   │   ├── layout.css      # Grid, header, sidebar, footer
│   │   ├── components.css  # Buttons, cards, forms, modals
│   │   ├── utilities.css   # Helper classes
│   │   └── themes.css      # Dark/light + animations
│   ├── js/
│   │   └── app.js          # Global framework
│   └── images/             # Static assets
├── modules/                # One folder per module
│   └── <module-name>/
│       ├── index.html
│       ├── style.css
│       └── script.js
└── docs/                   # This documentation site
    ├── index.html
    └── *.md

Naming Conventions

• Folders: kebab-case (e.g., financial-calculator)
• Files: kebab-case for assets, camelCase for JS modules
• CSS classes: BEM-like (.block__element--modifier)

Deployment

Commerce Learning Hub is designed for Cloudflare Pages but works on any static host.

Cloudflare Pages Setup

1. Push the project to a private GitHub repository.
2. In Cloudflare Dashboard → Workers & Pages → Create → Pages → Connect to Git.
3. Select your repository.
4. Configure:
   • Framework preset: None
   • Build command: (leave empty)
   • Build output directory: / (root)
5. Click Save and Deploy.

Custom Domain

In Cloudflare Pages → Settings → Custom domains, add your domain and follow DNS instructions.

Environment Variables

For API keys, use Cloudflare Pages environment variables and inject them at build time, or edit config/config.js before pushing.

User Guide

Getting Started

Open the homepage and browse modules by category or use the search bar.

Using a Module

1. Select a module from the sidebar or homepage grid.
2. Fill in the required inputs (validated in real time).
3. Click Calculate to see results, interpretation, and charts.
4. Use toolbar buttons to Export, Print, Copy, or Reset.

Features

• Bookmarks: Click the star icon on any module to save it.
• History: Recent modules appear in the sidebar.
• Themes: Toggle dark/light mode with the moon/sun icon.
• Offline: Once loaded, the site works without internet.

Developer Guide

Adding a New Module

1. Create /modules/<module-name>/ with index.html, style.css, script.js.
2. Register the module in config/config.js under modules.
3. Add a navigation entry in the header mega menu and sidebar.
4. Update sitemap.xml.
5. Write module-specific docs in /docs/.

Coding Standards

• Semantic HTML5 elements only.
• Use CSS variables from base.css — never hardcode colors.
• Modular JavaScript with clear function responsibilities.
• Comment complex logic; document public APIs with JSDoc.
• Test in Chrome, Firefox, Safari, and Edge.

Testing Checklist

• ✅ Responsive (mobile, tablet, desktop)
• ✅ Keyboard navigable
• ✅ Screen reader friendly
• ✅ No console errors
• ✅ Lighthouse ≥ 90
• ✅ Dark + Light mode look correct

Theme Guide

How Themes Work

Themes are driven by CSS custom properties on :root (light) and [data-theme="dark"] (dark). The ThemeManager in app.js toggles the data-theme attribute and persists the choice in localStorage.

Key Variables

Adding a New Theme

Add a new selector in themes.css, e.g. [data-theme="solarized"], and override the variables. Extend the toggle in app.js to cycle through themes.

Customization

Branding

Edit --color-primary and --color-secondary in base.css to rebrand the entire site.

Typography

Change --font-sans, --font-mono, and --font-serif in base.css. Update the Google Fonts link in index.html accordingly.

Layout

Adjust --header-height, --sidebar-width, and --container-max in base.css to reshape the layout.

Feature Flags

Toggle features on/off in config/config.js under features (e.g., enableToasts, enableOffline).

API Reference

Global Object: window.CLH

After app.js loads, a global CLH object exposes core services:

Configuration Object: window.APP_CONFIG

Read-only config object (frozen). Contains version, apiKeys, features, cdn, storage, and modules.

Loading External Libraries

// Example: load Chart.js on demand
function loadScript(url) {
  return new Promise((resolve, reject) => {
    if (document.querySelector(`script[src="${url}"]`)) return resolve();
    const s = document.createElement('script');
    s.src = url; s.onload = resolve; s.onerror = reject;
    document.head.appendChild(s);
  });
}
await loadScript(window.APP_CONFIG.cdn.chartjs);

Accessibility

Commerce Learning Hub targets WCAG 2.1 AA compliance.

Implemented Features

• Skip-to-content link
• Semantic landmarks (<header>, <main>, <nav>, <aside>, <footer>)
• ARIA labels on interactive controls
• Visible focus indicators (:focus-visible)
• Color contrast ≥ 4.5:1 for normal text
• Reduced-motion support
• Keyboard-only navigation throughout
• Form labels and error messages linked via aria-describedby

Testing

Use axe DevTools, Lighthouse, and manual keyboard testing. Verify with at least one screen reader (NVDA, VoiceOver, or JAWS).

SEO

• Unique <title> and meta description on every page.
• Open Graph and Twitter Card tags.
• JSON-LD structured data (WebSite, Organization).
• XML sitemap at /sitemap.xml.
• robots.txt allows all crawlers.
• Canonical URLs on every page.
• Descriptive alt text on all images.
• Breadcrumb schema on module pages.
• Semantic HTML for better content understanding.

Performance

Targets

Lighthouse score ≥ 95 across Performance, Accessibility, Best Practices, and SEO.

Optimizations

• No build tools — zero overhead.
• CSS split into logical files; browser caches aggressively via _headers.
• Libraries loaded on demand only when a module needs them.
• Service Worker caches critical assets for instant repeat loads.
• Images lazy-loaded where applicable.
• Minimal external dependencies.
• Cloudflare's global CDN serves all assets with optimal compression.

Troubleshooting

FAQ

Is it really free?

Yes. MIT licensed, no sign-up, no hidden costs.

Do I need to install anything?

No. Just open the site in a modern browser.

Is my data safe?

All data stays in your browser's localStorage. Nothing is sent to external servers except API calls you explicitly trigger.

Can I use it offline?

Yes. After the first visit, the Service Worker caches the site for offline use.

Can I contribute?

Absolutely. See CONTRIBUTING.md in the repository root.

Roadmap

Phase 1 ✅ — Foundation

Project structure, design system, navigation, documentation.

Phase 2 — Layout

Homepage polish, header mega menu, footer, responsive layout.

Phase 3 — CSS System

Animations, utilities, advanced theme variants.

Phase 4 — Global JS Framework

Storage manager, Fuse.js search, Chart.js wrapper, API manager with retry logic.

Phase 5+ — Modules (one per phase)

1. Financial Calculator Hub
2. Time Value of Money
3. Accounting Ratio Analysis
4. Financial Statement Generator
5. DuPont Analysis
6. Portfolio Optimizer
7. Stock Dashboard
8. Technical Analysis Playground
9. Derivatives Calculator
10. Risk Management Lab
11. … (30 modules total)