# MUDODO CHAIN
> **"Understand Markets. Practise with Confidence."**  
> *Explore global financial markets, understand crypto and develop your trading knowledge through realistic, risk-free practice.*

---

## 1. Project Overview & Architecture

**Mudodo Chain** is an institutional-grade, premium financial education and paper-trading platform engineered strictly using **pure vanilla HTML5, CSS3, and modern JavaScript (ES6+ Modules)**.

- **Zero React, Zero TypeScript, Zero Node.js runtime requirement.**
- **No Build Tools or Compilers Required:** You can unzip this folder on Windows, open it in Visual Studio Code, and run it directly using any static HTTP server.
- **Starting Virtual Capital:** Every new simulated paper account starts with **ZMW 50,000** (Zambian Kwacha).
- **Curriculum:** 20 interactive course modules across Forex and Crypto, with **exactly 200 distinct quiz questions** (10 questions per module) and badge achievements.
- **Real Market Feeds:** Aggregated from genuine live APIs with transparent status labeling (Live, Delayed, Market Closed).

---

## 2. Project Directory Structure

```text
mudodo-chain/
├── index.html            # Landing page with market radars, news preview, and curriculum highlights
├── login.html            # Firebase email/password & Google login with password reset
├── signup.html           # Account registration with ZMW 50,000 starting credit
├── dashboard.html        # Authenticated trader dashboard, portfolio equity, P&L, positions, CSV export
├── forex.html            # Forex terminal for 10 major currencies, candlestick chart, pip calculator
├── sp500.html            # S&P 500 benchmark index terminal, market hours tracker, constituents
├── crypto.html           # Crypto terminal with dedicated Stablecoin peg tracker & Top 5 Meme Coins
├── news.html             # Financial & business news hub with category filters (Forex, Central Banks, Zambia)
├── education.html        # 20 educational modules with reader modal and 200 interactive quiz questions
│
├── css/
│   ├── styles.css        # Master fintech design system (light theme default, dark theme overrides)
│   ├── charts.css        # Canvas chart styling, crosshair tooltips, OHLC candlesticks
│   └── responsive.css    # Responsive breakpoints for mobile phones, tablets, laptops, desktops
│
├── js/
│   ├── firebase-config.js # Official configuration for the authorized 'mudodobit' Firebase project
│   ├── firebase-auth.js   # Official Firebase v10 Modular SDK via CDN (Email/Password, Google, Reset)
│   ├── utils.js           # Safe DOM rendering (XSS protection), currency formatting, toast notifications
│   ├── storage.js         # User-namespaced localStorage engine (keyed by Firebase UID)
│   ├── market-api.js      # Real market data aggregation (Binance, Open Exchange Rates, GDELT)
│   ├── charts.js          # Pure vanilla HTML5 Canvas charting engine (Candlestick, Line, MA20/MA50)
│   ├── paper-trading.js   # Simulated order execution, ZMW 50k ledger, P&L, stop-loss, CSV export
│   ├── quizzes.js         # Complete content for all 20 modules & 200 multiple-choice questions
│   ├── education.js       # Module reader modal, quiz engine, scoring logic, achievement badges
│   ├── theme.js           # Light/Dark mode switcher with persistent preference
│   ├── navigation.js      # Session-aware navigation bar and mobile drawer controller
│   ├── app.js             # Global initialization, live ticker tape, and shared paper-trading modal
│   ├── forex.js           # Forex page logic, cross-rate calculations, and session clocks
│   ├── sp500.js           # S&P 500 page logic, point movements, and technical overlays
│   ├── crypto.js          # Crypto page logic, stablecoin depeg tracker, meme coin ranking
│   ├── news.js            # Financial news aggregation and category filters
│   └── dashboard.js       # User portfolio valuation, open positions, history, account reset
│
├── images/
│   ├── logo.svg           # High-resolution vector brand logo
│   ├── hero-artwork.svg   # Institutional trading terminal illustration
│   ├── badge-forex.svg    # Forex Master course achievement credential
│   └── badge-crypto.svg   # Crypto Pioneer course achievement credential
│
└── README.md              # Complete technical setup and architecture documentation
```

---

## 3. How to Open and Run in Visual Studio Code (Without Node.js or npm)

Because Mudodo Chain is built purely in standard web technologies (HTML5/CSS3/JavaScript ES Modules):

1. **Extract the ZIP file** to a folder on your Windows computer (e.g. `C:\Users\YourName\Documents\mudodo-chain`).
2. Open **Visual Studio Code**.
3. Click **File > Open Folder...** and select the `mudodo-chain` folder.
4. **Running Locally:**
   - **Method A (Recommended — VS Code Extension):**
     Install the popular **Live Server** extension (by Ritwick Dey) from the VS Code Extensions tab (`Ctrl+Shift+X`).
     Right-click `index.html` and click **"Open with Live Server"**.
     Your browser will open automatically at `http://127.0.0.1:5500`.
   - **Method B (Python — built into Windows/Mac/Linux):**
     Open a terminal inside the project folder and type:
     ```bash
     python -m http.server 8000
     ```
     Then navigate to `http://localhost:8000` in your web browser.

> **Why you cannot double-click `index.html` via `file:///`:**  
> Modern browser security policies (CORS) and the official Firebase Authentication SDK block popup authentication (Google Sign-In) and ES module imports when loaded from the local `file:///` protocol. Running through an HTTP origin (`http://localhost` or `http://127.0.0.1`) ensures 100% functionality.

---

## 4. Real Firebase Authentication Setup (`mudodobit`)

The project is pre-configured with your exact Firebase Web credentials in `js/firebase-config.js`:

```javascript
export const firebaseConfig = {
  apiKey: "AIzaSyBBXBQkr1U3pkXYLnOY_n0NSnoqX5R6oJ0",
  authDomain: "mudodobit.firebaseapp.com",
  projectId: "mudodobit",
  storageBucket: "mudodobit.firebasestorage.app",
  messagingSenderId: "527781082639",
  appId: "1:527781082639:web:7785000dcf8e3880ccd57a"
};
```

### Enabling Authentication Providers in the Firebase Console:
1. Go to the [Firebase Console](https://console.firebase.google.com/).
2. Select your project: **`mudodobit`**.
3. In the left sidebar, navigate to **Build > Authentication**.
4. Click on the **Sign-in method** tab:
   - **Email/Password:** Click **Email/Password**, toggle **Enable**, and click **Save**.
   - **Google:** Click **Google**, toggle **Enable**, enter your support email, and click **Save**.
5. Click on the **Settings** tab in Authentication:
   - Click **Authorized domains**.
   - Add your local testing domains if not already listed:
     - `localhost`
     - `127.0.0.1`
     - Any custom production domain or preview domain you deploy to.

---

## 5. Real Market Data APIs & Attribution

All prices and quotes displayed in Mudodo Chain originate from legitimate provider responses:

| Market | Primary Provider | Free Tier Details & Endpoints |
|---|---|---|
| **Cryptocurrency, Stablecoins & Meme Coins** | **Binance Public Market API** (`api.binance.com`) | Free, no API key required, zero authentication, ultra-fast CORS, 24-hour volume, high/low, and spot prices. Endpoint: `/api/v3/ticker/24hr`. |
| **Forex (10 Major Currencies + ZMW)** | **Open Exchange Rates / ER-API** (`open.er-api.com`) | Free public interbank reference rate feed for USD, EUR, GBP, JPY, CHF, CAD, AUD, NZD, CNY, ZAR, and ZMW. Updated regularly with zero API key required. |
| **S&P 500 Index (^GSPC)** | **Cboe / S&P Dow Jones via Public Chart API** | Official S&P 500 benchmark level, point movements, and day high/low. Accurately tracks US equity trading hours (9:30 AM - 4:00 PM EST). |
| **Financial & Business News** | **GDELT International Project & Yahoo RSS** | Real-world global headlines covering Forex, Central Banks, Stocks, Crypto, Stablecoins, African Markets, and Zambian Economic developments. |

---

## 6. Paper Trading Simulation (ZMW 50,000)

1. **Virtual Capital:** New simulated accounts are initialized with **ZMW 50,000.00**.
2. **Currency Conversion:** Crypto and US market instruments quoted in USD are automatically converted into Zambian Kwacha (ZMW) using the live exchange rate (`~27.50 ZMW/USD`).
3. **Execution Rules:** Supports BUY (Long) and SELL (Short), position sizing, optional Stop-Loss and Take-Profit orders, and margin checks.
4. **Data Privacy & Separation:** Private account records, open positions, and trading logs are namespaced in browser `localStorage` by the authenticated user's Firebase UID (`mudodo_paper_${uid}`). Separate users on the same machine never mix portfolios.
5. **Reset Capability:** The "Reset Paper Account" button in the dashboard restores virtual cash to ZMW 50,000 and clears positions after a double confirmation, while keeping Firebase login and course progress intact.
6. **CSV Export:** Allows exporting simulated transactions to a standard `.csv` file for external trade journal analysis.

---

## 7. Educational Curriculum (20 Modules & 200 Quizzes)

The platform features two 10-module tracks:

### Track 1: Forex Fundamentals (Modules 1 - 10)
- Module 1: Understanding Forex and Currency Pairs
- Module 2: Base Currency, Quote Currency and Exchange Rates
- Module 3: Pips, Lot Sizes, Leverage and Margin
- Module 4: Bid, Ask, Spread and Order Types
- Module 5: Forex Sessions and Liquidity
- Module 6: Candlesticks and Price Action
- Module 7: Support, Resistance and Trends
- Module 8: Stop-Loss, Take-Profit and Risk Management
- Module 9: Economic News, Interest Rates and Central Banks
- Module 10: Trading Plans and Common Mistakes

### Track 2: Crypto Fundamentals (Modules 11 - 20)
- Module 11: Blockchain Fundamentals
- Module 12: Coins, Tokens and Crypto Market Structure
- Module 13: Wallets, Private Keys and Public Addresses
- Module 14: Centralized and Decentralized Exchanges
- Module 15: Market Capitalization, Volume and Liquidity
- Module 16: Stablecoins and Peg Risks
- Module 17: Meme Coins, Speculation and Volatility
- Module 18: Candlesticks and Technical Analysis in Crypto
- Module 19: Crypto Security, Scams and Fraud Prevention
- Module 20: Risk Management, Research and Responsible Participation

Every module contains a comprehensive lesson, practical real-world examples, and **exactly 10 multiple-choice questions** (4 options each) with explanations for every correct answer. Users who pass with 70%+ earn the **Forex Master** and **Crypto Pioneer** achievement badges.

---

## 8. Deploying to Firebase Hosting (Without Node.js)

Because the site is 100% static HTML, CSS, and JavaScript:

1. Install the Firebase CLI (one-time global tool):
   ```bash
   npm install -g firebase-tools
   ```
2. Login to your account:
   ```bash
   firebase login
   ```
3. Initialize hosting inside the `mudodo-chain` folder:
   ```bash
   firebase init hosting
   ```
   - Select **Use an existing project**: `mudodobit`.
   - What do you want to use as your public directory? Enter `.` (current folder).
   - Configure as a single-page app? Select **No** (it is a clean multi-page site).
   - Set up automatic builds and deploys with GitHub? Select **No**.
4. Deploy instantly:
   ```bash
   firebase deploy --only hosting
   ```
Your site will be live immediately at `https://mudodobit.web.app`!

---

## 9. Contact & Support

**Mudodo Chain**  
Powered by **Syremex Technology**  
Lusaka, Zambia  
Support and Inquiries: [modecai600@gmail.com](mailto:modecai600@gmail.com)