Why I rebuilt offline web archiving to bypass CORS (The PWAA Format)

Filipe Lunfuankenda — Fri, 17 Jul 2026 14:09:11 +0000

The industry has systematically failed at modern offline web portability for the last two decades.If you want to distribute a complex, interactive manual or a heavy React dashboard for pure offline use, what are your options?

Historically, we had Microsoft's .CHM, which was great for documentation but turned into a malware nightmare and was abandoned. Then we got EPUB 3, which theoretically supports HTML5/JS, but in practice, e-readers aggressively sandbox it, block JS, and break CORS, making it useless for modern web apps. Single-file formats like .MHTML or browser extensions only work for a single flat page, instantly breaking when you have complex Single Page Application (SPA) routing.

Wrapping it in Electron? Now you are shipping a 150MB executable just to read a document. Out of absolute necessity, I built PWAA (Portable Web Application Archive).

The big problem was: 'How do we archive today’s rich Web?' Classic formats like PDF freeze static documents, completely destroying any interactivity, videos, or smooth navigation of Single Page Applications (SPA). EPUB is designed strictly for text and structured e-books, choking on heavy JavaScript. WARC (Web ARChive) is the gold standard for institutional preservation, but it's scarily complex for the average user and requires dedicated playback servers (Replay Servers).

What was missing in the market was a universal container: a file capable of storing all the complexity of modern frameworks (React, Vue, WebGL) and delivering a fast, interactive, and encapsulated experience with a simple double-click, supported by the native technologies of modern operating systems. This is where the PWAA format was born.

Currently, any interactive dashboard in React or document system requires a hosting server (Vercel, AWS, Netlify). PWAA frees engineers from the Cloud. The developer writes the code, packages it in a PWAA, sends it by email or USB drive, and the end user gets an exact and smooth experience, regardless of server shutdowns or connection drops.

Because the code thinks it's running on a real server, it completely bypasses CORS restrictions. Heavy manuals and heavy media work natively offline from a single double-clickable file. It even includes an SPA Fallback mechanism so virtual routing never hits a 404.

What is PWAA? PWAA is a new format engineered to pack an entire web app (HTML, CSS, JS, heavy media) into a standard PKZIP container. But here is the magic: the native reader never extracts it to the disk.

Instead of using file:/// protocols (which instantly trigger CORS blocks for fetching local JSON or ES6 modules), the PWAA reader maps the ZIP contents to memory and spins up an ephemeral in-memory HTTP server on 127.0.0.1.

Because your web code thinks it's running on a real cloud server, it completely bypasses CORS restrictions. Heavy SPAs (React, Next.js, Vue) work natively offline from a single double-clickable file.

The Architecture

I built the reference reader and builder in Go (Golang). Here are the core problems I had to solve:

1. The SPA Routing Problem (404s)
In a React/Vue app, navigation is virtual. If you refresh on /about, a static server throws a 404. I built an SPA Fallback algorithm into the in-memory server: if a file isn't found inside the ZIP, it instantly returns the bytes of index.html, letting the internal JS router take over.

2. The Video Streaming Problem (HTTP 416)
Browsers require Accept-Ranges: bytes to play .mp4 files. A standard on-the-fly ZIP extractor cannot easily jump to random bytes. I implemented a RAM-Buffering strategy that loads the requested media into physical RAM, transforming it into a bytes reader. This allows instant scrubbing on heavy video files with zero latency.

3. Absolute Security (Zero-Leak)
WebViews love to cache data. The PWAA reader is forced to run in an ephemeral sandbox session folder. The exact millisecond the reader window is closed, a graceful shutdown command obliterates the temporary folder. No cookies, no localStorage, and no cache are left on the host machine. I also injected a global JavaScript bodyguard that intercepts external links (https://) and forces them to open in the user's default external browser, keeping the PWAA window strictly isolated.

How to create a PWAA?

The core CLI (pwaa-builder) acts as a universal chameleon. It has three modes:

Pack: Takes a static folder and wraps it into .pwaa.
Build: Automatically detects your framework (package.json, .csproj), runs the install/build commands (e.g., npm run build), finds the dist folder, and archives it.
Scrape: A recursive Web Crawler (built with Colly and GoQuery) that downloads a live website, rewrites the absolute DOM paths to relative offline paths, and generates an offline clone.

Open Core

The builder CLI is closed for now, but the full architectural spec, the VFS and reader logic, and the SDK are completely open-source. I want the community to see how the engine works, trust the security model, and even build their own native readers for macOS, Linux, or mobile. You can read the official Whitepaper and try the SDK here.

I’d love to hear your thoughts on this architecture. Is the era of static documentations finally over?

https://github.com/Filipe-Lunfuankenda/pwaa-core/blob/main/assets/Apresenta%C3%A7%C3%A3o-do-Formato-PWAA.gif

Hello, World! 👋 I'm Filipe Lunfuankenda | Software Developer

Filipe Lunfuankenda — Tue, 31 Mar 2026 09:06:25 +0000

Olá, Mundo! (Hello, World!) 🌍

I’m Filipe Lunfuankenda, a self-taught programmer, data analyst, and systems enthusiast. I was born in Angola 🇦🇴 and I am currently based in Portugal 🇵🇹, studying IT Management and Programming (TGPSI) at Escola Profissional de Penacova.

As I join the DEV community, I wanted to take a moment to introduce myself, share my stack, and connect with other amazing developers!

"Não basta saber, é preciso transformar conhecimento em impacto real." > (It is not enough to know; we must transform knowledge into real impact.) — Filipe Lunfuankenda

💻 What I Do & My Stack

I am passionate about creating robust software solutions, clean UI/UX interfaces, and tools that solve real-world logistical problems. I love dismantling complexity to understand how things work at their core.

My current toolkit includes:

Languages & Web: React, TypeScript, JavaScript, Python, C#, PHP, HTML5/CSS3.
Desktop Apps & Ecosystems: Tauri, Electron, Node.js.
Databases & Infra: SQL (MySQL), Linux Servers, Git/GitHub.
Design (UI/UX): Microsoft Office, Google Workspace, Adobe Creative Cloud (Premiere Pro, Photoshop), Canva.

🚀 Projects I'm Proud Of

I focus heavily on analytical tools and institutional solutions. Some of my recent work includes:

OrçaTech (Desktop Software): A smart budget management and invoicing desktop application built from scratch with React, TypeScript, and encapsulated in Tauri.
Pedagogical Feedback System: Developed a complete web platform utilizing dynamic QR Codes for a school's restaurant. It crosses real-time customer feedback with the specific student teams working that shift, generating automated analytical dashboards and PDFs for grading.
Polynomial Graphing Calculator: An analytical tool built with React, Tailwind, and Electron for visualizing extremes, roots, and inverse functions.

(I recently finished a great internship at **TUMO Coimbra, working with multimedia editing, robotics, and design sprints, and also had an amazing Erasmus+ mobility experience in Bilbao, Spain!)

🌌 Beyond the Code

When I'm not coding, my brain is usually fueled by:

Science & Logic: I am deeply fascinated by Physics, Mathematics, Electronics, and Artificial Intelligence.
Linguistics: My goal is to become a polyglot. I speak fluent Portuguese and English, but I'm also learning Spanish, French, Italian, German, Japanese, and even classical languages like Biblical Hebrew and Greek for theological and literary analysis.
Culture: Huge fan of Japanese anime (especially Naruto), European football (Hala Madrid!), and playing chess.

🤝 Let's Connect!

I joined DEV to share my journey, document the challenges I overcome in my projects, and learn from this incredible community.

Feel free to reach out, say olá, or check out my work:

💼 LinkedIn: Filipe Lunfuankenda
💻 GitHub: @Filipe-Lunfuankenda
🎥 YouTube: My Tech & Video Portfolio