Skip to content

Architecture.md

Latest commit

 

History

History
131 lines (101 loc) · 5.86 KB

Architecture.md

File metadata and controls

131 lines (101 loc) · 5.86 KB
Raw

MagicFrame Architecture

This document explains the technical architecture and code flow of MagicFrame.

System Overview

MagicFrame is a single HTML file that creates a full-page iframe with enhanced functionality. The system is designed to be simple, lightweight, and dependency-free.

┌─────────────────────────────────────────┐
│              MagicFrame                 │
│                                         │
│  ┌─────────────────────────────────┐    │
│  │                                 │    │
│  │                                 │    │
│  │                                 │    │
│  │           iframe                │    │
│  │      (Target Website)           │    │
│  │                                 │    │
│  │                                 │    │
│  │                                 │    │
│  └─────────────────────────────────┘    │
│                                         │
└─────────────────────────────────────────┘

Code Structure

The entire solution consists of a single HTML file with three main components:

  1. HTML Structure: Defines the iframe element
  2. CSS Styling: Ensures the iframe fills the entire viewport
  3. JavaScript Logic: Handles URL parameter passing and title synchronization

HTML Structure

<body>
  <iframe id='forwardFrame' name='forwardFrame' src='' width='100%' height='100%' 
          marginheight='0' marginwidth='0' scrolling='auto' frameborder='0'>
    <p>Your browser does not support iframes.</p>
  </iframe>
  <!-- JavaScript code here -->
</body>

CSS Styling

html, body {
  margin: 0px;
  padding: 0px;
  overflow: hidden;
  height: 100%;
}

JavaScript Logic

The JavaScript component has two main responsibilities:

  1. URL Construction and Loading:

    var url = 'http://example.com'; // Target URL (configurable)
frame.src = url + window.location.search + window.location.hash;

  2. Title Synchronization:

    frame.onload = function() {
  document.title = document.getElementById('forwardFrame').contentWindow.document.title;
}

Flow Diagram

The following diagram illustrates the execution flow of MagicFrame:

┌──────────────┐     ┌───────────────────┐     ┌───────────────────┐
│  User visits │     │ MagicFrame loads  │     │ iframe loads with │
│  MagicFrame  ├────►│ iframe with       ├────►│ target content    │
│  URL         │     │ constructed URL   │     │                   │
└──────────────┘     └───────────────────┘     └─────────┬─────────┘
                                                         │
                     ┌───────────────────┐              │
                     │ Browser displays  │◄─────────────┘
                     │ content & updates │
                     │ page title        │
                     └───────────────────┘

URL Parameter Flow

One of MagicFrame's key features is preserving URL parameters and hash fragments. Here's how it works:

Original URL: https://yourdomain.com/magicframe/?user=123&view=dashboard#settings
                                                └───────────┬──────────┘ └──┬───┘
                                                            │               │
                                                Query Parameters         Hash Fragment
                                                            │               │
                                                            ▼               ▼
Target URL: https://example.com/?user=123&view=dashboard#settings
             └─────┬─────┘ └───────────┬──────────┘ └──┬───┘
                   │                   │               │
             Base Target URL    Query Parameters   Hash Fragment

Title Synchronization

The title synchronization process occurs after the iframe content has fully loaded:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│ iframe content  │     │ onload event    │     │ Page title      │
│ finishes        ├────►│ handler         ├────►│ updated to      │
│ loading         │     │ triggered       │     │ match iframe    │
└─────────────────┘     └─────────────────┘     └─────────────────┘

Technical Limitations

  1. Same-Origin Policy: The title synchronization will only work if the target URL is on the same origin or has appropriate CORS headers.

  2. X-Frame-Options: If the target site sets X-Frame-Options: DENY or X-Frame-Options: SAMEORIGIN, it cannot be displayed in an iframe.

  3. Content Security Policy: Some websites implement CSP rules that prevent them from being loaded in iframes.

For more information on these limitations, see the Security Considerations page.