Architecture

Simple Page is a markdown-first publishing system built on ENS, IPFS, and Ethereum.

Overview

Simple Page has three main layers:

Layer	Role
Smart contracts	Track Simple Page subscriptions as NFTs and calculate subscription fees.
Browser frontend	Edits markdown, manages files/settings, stages content, reviews drafts, and publishes ENS contenthash transactions.
Simple Page Node	Pins and stages CARs, indexes Ethereum/ENS events, serves lightweight CARs and raw blocks, and syncs off-chain refs.

The permanent public pointer is always the ENS contenthash. Every publish changes that pointer on-chain to a new IPFS CID.

Browser Publish Flow

Edit markdown and files
-> build a new IPFS root locally
-> upload a CAR to a Simple Page Node
-> sign an ENS contenthash transaction
-> node indexes the event and finalizes the pin

The browser editor uses the @simplepg/repo package as the canonical content engine. It builds markdown pages, HTML pages, settings, theme CSS, manifests, RSS, sidebar navigation, and history links into one UnixFS root.

CLI Draft Flow

Clone or create local markdown repo
-> edit files locally
-> authorize CLI agent with the ENS owner wallet
-> push signed off-chain draft
-> review draft in browser
-> owner publishes selected CID on ENS

This separates contribution from publication. Agents can prepare drafts without holding the ENS owner key.

Static Site Flow

Build a static site locally
-> push output directory as a raw signed draft
-> preview CID in browser
-> owner publishes selected CID on ENS

Static builds use the same Node and ENS contenthash publication path, but they do not use Simple Page markdown rendering.

Read Flow

Visitor opens yourname.eth.link
-> gateway resolves ENS contenthash
-> gateway serves IPFS content
-> Simple Page frontend enhances the page when JavaScript is available

Published pages include static HTML, so content can render before the app hydrates.

Data Stored In A Published Root

Important paths in a Simple Page root include:

Path	Purpose
index.md, */index.md	Markdown source for pages.
index.html, */index.html	Rendered HTML for visitors.
_files/	Uploaded files and generated avatar/favicon artifacts.
_prev/0/	Previous published root, recursively preserving history.
_template.html	HTML template used to render pages.
settings.json	Site settings such as themes, search, and edit button style.
theme.css	Generated theme CSS from settings.
manifest.json, manifest.webmanifest	Web app metadata and icons.
rss.xml	Generated RSS feed when pages opt in.
sidenav.json	Generated left-sidebar navigation data.
_redirects	Gateway redirects, including /feed to /rss.xml.

Service Discovery

Frontend and CLI clients discover Simple Page Nodes through the dservice text record on new.simplepage.eth. Multiple endpoints can be listed. Clients randomize endpoint order and try available nodes.

Advanced users can override endpoints with query parameters:

?ds-new.simplepage.eth=https://your-node.example
?ds-rpc-1=https://your-mainnet-rpc.example
?ds-rpc-11155111=https://your-sepolia-rpc.example

The main editor currently supports RPC overrides for mainnet, Sepolia, and local development.

Next

• Components - what each package and contract does.
• Protocol - how content moves through the network.
• API - Node endpoints for content, refs, capabilities, and history.