Secret Sauce

This document is a complete technical blueprint for reimplementing Hyperclay from scratch, covering every aspect of the system from frontend to backend. It reveals the three-dimensional state machine router, the HTML-as-database architecture, the custom attribute system, authentication, multi-tenancy, file storage, and deployment strategies.

With the code examples and architectural patterns documented here, a developer could build a fully functional Hyperclay clone in 15-20 weeks. We’re sharing this because we believe radical transparency and simplicity should be the foundation of modern web development.

The Core Innovation: Self-Modifying HTML as a Database

The Fundamental Insight

Hyperclay’s breakthrough is deceptively simple: What if the HTML file IS the database?

Instead of the traditional architecture where:

Frontend renders UI from data
Backend stores data in a database
API shuttles data between them

Hyperclay collapses this into:

The HTML file contains both UI and data
Changes to the DOM are changes to the database
Saving means sending the entire HTML file to the server

The Technical Magic

When a user interacts with a Hyperclay app:

DOM Manipulation = Data Mutation: Every checkbox checked, every text field edited, every element dragged modifies the DOM directly
Save Trigger: When the user saves (manually or auto-save), JavaScript serializes the entire document.documentElement.outerHTML
Server Storage: The HTML string is sent to the server and saved as a file
Instant Persistence: Next page load serves this modified HTML - the changes are now permanent


// The entire save mechanism in its beautiful simplicity
async function savePage() {
  const html = document.documentElement.outerHTML;
  await fetch('/save', {
    method: 'POST',
    body: html,
    headers: { 'Content-Type': 'text/html' }
  });
}

The Three-Dimensional State Machine Router

The Architecture Nobody Else Has

Hyperclay uses a unique routing system based on three dimensions:


userType : resourceType : action = handler

Every request is characterized by:

Who is making the request (no_auth, app_user, dev, admin)
What they’re accessing (main_app, regular_site, multi_tenant, instance, folder, upload)
What they’re doing (view, edit, save, delete)

Why This Matters

Traditional routers:


app.get('/sites/:id/edit', checkAuth, checkOwnership, serveEditor);

Hyperclay’s approach:


'dev:regular_site:edit': [
  state(s => s.user.isOwner).require(),
  serveCodeEditor
]

The magic: Security is declarative and visible. You can see at a glance that only developers who own a site can edit it.

The State Detection Pipeline

Before any route executes, seven middleware build a complete picture:


state__init      → Initialize empty state
state__meta      → Parse domain, method, path
state__user      → Load user from auth token
state__resource  → Detect what's being accessed
state__action    → Map URL to action name
state__key       → Build routing key
state__authcookies → Set ownership cookies

After detection, req.state contains everything:


{
  meta: { domain, path, method, body },
  user: { person, isOwner, canCreateSites },
  resource: { node, siteName, folderPath },
  action: 'edit',
  key: 'dev:regular_site:edit'
}

The File System as a Database

The Hybrid Approach

Hyperclay uses both a SQLite database and the file system:

Database stores metadata:

User accounts (Person table)
Site ownership (PersonNode table)
Domain mappings (CustomDomain table)
Version timestamps (SiteBackups table)

File system stores content:

/sites/*.html - Live site files
/sites-versions/{sitename}/*.html - Every version ever saved
/uploads/{username}/ - User uploaded files

The dx.js File Utility

Hyperclay’s custom file system utility makes file operations chainable and error-resistant:


// Never throws errors, always returns safe values
await dx("sites", "mysite.html").exists() // returns true/false
await dx("sites", "mysite.html").getContents() // returns string or null
 
// Chainable operations
await dx("sites-versions", siteName)
  .copyFileFrom("sites", siteName + ".html")
  .renameTo(timestamp + ".html");

This abstraction means file operations never crash the app - missing files return null, failed writes return false.

Multi-Tenant Architecture Without Complexity

The Brilliant Simplicity

Any site can become a multi-tenant platform by setting enableSignups: true. That’s it.

When enabled:

The site gets a signup form at /signup
New users create “instances” - copies of the original site
Instances are accessed via subdomains: username-appname.hyperclay.com

How Instances Work


// Instance creation is just:
1. Copy source site HTML to new file
2. Create Node record with sourceNodeId pointing to parent
3. Create PersonNode ownership record
4. Set up subdomain routing

The instance URLs follow a pattern:

First instance: alice-myapp
Second instance: alice-2-myapp
Custom domains: alice.myapp.com

The Routing Magic

The state machine router handles multi-tenancy elegantly:


// Source app accessed by anyone
'*:multi_tenant:view': [serveSiteHTML],
 
// Only devs can edit source apps
'dev:multi_tenant:edit': [
  state(s => s.user.isOwner).require(),
  serveCodeEditor
],
 
// App users edit their instances
'app_user:instance:edit': [
  state(s => s.user.isOwner).require(),
  serveCodeEditor
]

The Edit Mode Magic

How Live Editing Works

Hyperclay apps have two modes: view and edit. The transition is seamless:

Edit Mode Toggle: Adds [editmode] attribute to <html>
Conditional Features: Elements with [edit-mode-*] attributes activate
Admin Elements: Special elements only visible to site owners
Save Preparation: Before saving, admin-only elements are removed


<!-- This input only works in edit mode -->
<input edit-mode-input type="text" value="Edit me">
 
<!-- This appears only in edit mode -->
<div save-ignore>
  <button onclick="hyperclay.savePage()">Save</button>
</div>

The hyperclay.js Framework

The global hyperclay object provides the API:


hyperclay = {
  isEditMode(): boolean,
  isOwner(): boolean,
  toggleEditMode(): void,
  savePage(): Promise,
  
  // Lifecycle hooks
  beforeSave: EventTarget, // Fires before save
  
  // File operations
  uploadFile(file, callback): void,
  createFile(name, content, path): Promise
}

The Custom Attribute System

Declarative Interactivity

Hyperclay extends HTML with custom attributes that add behavior without JavaScript:


<!-- AJAX form submission -->
<form ajax-form action="/save">
  <!-- Automatically submits via AJAX, shows loading state -->
</form>
 
<!-- Persistent input values -->
<input persist name="userName" value="Alice">
<!-- Value saved in HTML, survives page reloads -->
 
<!-- Sortable lists -->
<ul sortable>
  <li>Drag me</li>
  <li>Reorder me</li>
</ul>
 
<!-- Dynamic visibility -->
<div theme="dark">
  <style option:theme="dark">/* dark styles */</style>
  <style option:theme="light">/* hidden */</style>
</div>

The Initialization Magic

On page load:


initCustomAttributes() {
  // Scan DOM for special attributes
  document.querySelectorAll('[ajax-form]').forEach(initAjaxForm);
  document.querySelectorAll('[sortable]').forEach(initSortable);
  document.querySelectorAll('[persist]').forEach(initPersistence);
  // ... etc
}

Domain Routing Without DNS Management

The Subdomain System

Every site automatically gets a subdomain:

Sites: sitename.hyperclay.com
Instances: username-appname.hyperclay.com

The server detects the subdomain and routes accordingly:


// In state__resource middleware
const subdomain = extractSubdomain(req.hostname);
if (subdomain) {
  // Parse instance pattern: username-appname
  const [username, ...appParts] = subdomain.split('-');
  // Look up the instance or site
  const node = await findNodeByNamePattern(subdomain);
  req.state.resource.node = node;
}

Custom Domains

Users can point their own domains to sites:

User adds domain in dashboard
System provides DNS instructions
User updates their DNS
System verifies ownership via DNS check
SSL automatically provisioned
Domain mapped to site in database

The Version Control System

Every Save is a Commit

Hyperclay automatically versions every save:


async function saveHTML(req, res) {
  const timestamp = Date.now();
  const siteName = req.state.resource.siteName;
  const html = req.body;
  
  // Save version with timestamp
  await dx('sites-versions', siteName)
    .createFileOverwrite(timestamp + '.html', html);
  
  // Update live site
  await dx('sites')
    .createFileOverwrite(siteName + '.html', html);
  
  // Record in database
  await SiteBackups.create({
    nodeId: req.state.resource.node.id,
    filename: timestamp + '.html',
    createdBy: req.state.user.person.id
  });
}

Instant Rollback

Restoring a previous version:


// Just copy the versioned file back to live
await dx('sites')
  .copyFileFrom('sites-versions/' + siteName, versionFile);

Authentication Without Sessions

Token-Based Auth

Hyperclay uses a simple token system:

Login creates token: Random secure ID stored in database
Cookie carries token: auth_token cookie with 30-day expiry
Every request validates: Token looked up, user loaded
Logout deletes token: Remove from database, clear cookie


// Token validation on every request
const token = req.cookies.auth_token;
if (token) {
  const loggedInToken = await LoggedInToken.findOne({ 
    where: { token } 
  });
  if (loggedInToken) {
    req.state.user.person = await Person.findByPk(
      loggedInToken.personId
    );
  }
}

Cross-Domain Authentication

The clever bit: cookies work across all subdomains:


function setCookieOnApexAndAllSubdomains(res, name, value) {
  res.cookie(name, value, {
    domain: '.hyperclay.com', // Note the leading dot
    httpOnly: true,
    secure: true,
    maxAge: 30 * 24 * 60 * 60 * 1000 // 30 days
  });
}

This means logging in on hyperclay.com also logs you in on mysite.hyperclay.com.

The CodeMirror Integration

In-Browser IDE

The code editor (/edit route) is a full IDE:


// Serve CodeMirror with the site's HTML
async function serveCodeEditor(req, res) {
  const siteName = req.state.resource.siteName;
  const html = await dx('sites', siteName + '.html').getContents();
  
  res.render('codemirror', {
    initialCode: html,
    saveUrl: '/save',
    siteName: siteName
  });
}

Smart Save Detection

The editor detects what type of file is being edited:


// Client-side in codemirror
function detectSaveEndpoint() {
  const cookie = getCookie('currentResource');
  if (cookie.includes('upload:')) {
    return '/upload/save';
  }
  return '/save';
}

File Uploads Without Complexity

Direct File System Storage

Uploads bypass the database entirely:


async function handleUpload(req, res) {
  const username = req.state.user.username;
  const file = req.files.upload;
  const folderPath = req.body.folderPath || '';
  
  // Direct save to file system
  await dx('uploads', username, folderPath)
    .createFileNoOverwrite(file.name, file.data);
  
  // Create Node record for tracking
  await Node.create({
    name: file.name,
    type: 'upload',
    parentId: req.state.resource.currentFolderId
  });
}

Serving Uploads

Uploads are served directly from the file system:


'*:upload:view': async (req, res) => {
  const filePath = req.state.resource.uploadPath;
  res.sendFile(filePath);
}

The Subscription Model

Stripe Integration Simplified

The payment flow:

Checkout: Create Stripe session, redirect to Stripe
Webhook: Stripe notifies of successful payment
Account Creation: Create Person with stripeCustomerId
Access Control: Check hasActiveSubscription flag


// Site limit based on subscription age
function calculateSiteLimit(person) {
  const baseLimit = 5;
  const monthsSinceSignup = getMonthsSince(person.createdAt);
  const bonusSites = Math.min(monthsSinceSignup, 12);
  return baseLimit + bonusSites;
}

The Deployment Story

PM2 Process Management

Production deployment is simple:


// ecosystem.config.js
module.exports = {
  apps: [{
    name: 'hyperclay',
    script: 'hey.js',
    instances: 4,
    exec_mode: 'cluster',
    env: {
      NODE_ENV: 'production',
      PORT: 80
    }
  }]
};

Zero-Downtime Updates

Code pushed to server
PM2 reload with graceful shutdown
New instances start before old ones stop
No requests dropped

The Performance Tricks

Static File Optimization

Static files bypass the state machine entirely:


// Catch static files early
app.get(/\.(css|js|jpg|png)$/i, (req, res) => {
  res.sendFile(path.join(__dirname, 'public-assets', req.path));
});

HTML Caching

Sites are served directly from disk - no rendering:


async function serveSiteHTML(req, res) {
  const siteName = req.state.resource.siteName;
  const html = await dx('sites', siteName + '.html').getContents();
  res.send(html); // No templating, no processing
}

The Security Model

Ownership-Based Access

Security is enforced through the state machine:


// Can't edit without ownership
'dev:regular_site:edit': [
  state(s => s.user.isOwner).require(),
  serveCodeEditor
]
 
// Can't delete without ownership
'dev:regular_site:delete': [
  state(s => s.user.isOwner).require(),
  deleteSite
]

Rate Limiting


const attempts = {};
function loginRateLimiter(req, res, next) {
  const key = sha256(req.ip + req.body.email);
  attempts[key] = (attempts[key] || 0) + 1;
  
  if (attempts[key] > 20) {
    return res.status(429).send('Too many attempts');
  }
  
  // Reset after 15 minutes
  setTimeout(() => delete attempts[key], 15 * 60 * 1000);
  next();
}

The Scaling Strategy

Horizontal Scaling

The architecture scales horizontally:

Stateless servers: Any server can handle any request
Shared file system: NFS or S3 for sites/uploads
Database pooling: Multiple servers, one database
Cookie-based auth: No session state to sync

The Limits

Current architecture handles ~10,000 sites comfortably:

Each site is a file (fast to serve)
Database only stores metadata (stays small)
No complex queries (all lookups by ID)

The Competitive Advantages

What Makes This Hard to Copy

Conceptual Leap: Most developers can’t imagine HTML as a database
State Machine Complexity: The routing system takes time to understand
Edge Case Handling: Thousands of small decisions about when to save, what to persist
Custom Attribute System: Requires deep JavaScript knowledge to replicate
Multi-Tenant Routing: The subdomain parsing and instance creation is non-obvious

What’s Easy to Copy

Saving HTML to files: Basic concept is simple
Cookie auth: Standard pattern
File versioning: Just timestamp files
Stripe integration: Well documented

The Implementation Checklist

To build your own Hyperclay:

Phase 1: Core System (2-4 weeks)

Set up Express server
Implement file-based storage for HTML
Create save endpoint that accepts HTML
Build basic authentication with cookies
Add SQLite for user accounts

Phase 2: State Machine (2-3 weeks)

Build state detection middleware
Implement three-dimensional routing
Add ownership verification
Create routing table structure

Phase 3: Edit Mode (3-4 weeks)

Phase 4: Multi-Tenancy (2-3 weeks)

Add instance creation logic
Implement subdomain routing
Build signup flow for apps
Handle instance URLs

Phase 5: Advanced Features (4-6 weeks)

Phase 6: Production (2-3 weeks)

The Philosophy Behind It All

Why This Works

Hyperclay works because it embraces constraints:

Single file = single app: Limits complexity
DOM = database: No impedance mismatch
HTML-first: Works with the web, not against it
Direct manipulation: What you see is what you save

The Trade-offs

What Hyperclay sacrifices:

Complex queries (no SQL joins)
Real-time collaboration (last save wins)
Large datasets (entire HTML in memory)
Traditional security (users can edit their own HTML)

What it gains:

Radical simplicity
Instant persistence
Zero abstraction
True ownership

The Future Possibilities

Where This Could Go

Distributed Hyperclay: Each user runs their own instance
P2P Sync: Sites sync between users without central server
AI Integration: LLMs that modify HTML directly
WebAssembly: Compile other languages to Hyperclay apps
Federation: Hyperclay instances that talk to each other

The Philosophical Victory

Hyperclay proves that modern web development’s complexity is optional. You can build powerful, persistent applications with just HTML files and a simple server. The “backend” doesn’t need to exist as a separate concept.

The secret sauce isn’t the technology - it’s the courage to reject conventional wisdom and build something simpler.

Final Secret: It’s All Open Source

The ultimate secret is there are no secrets. The entire system is built on:

Standard Node.js/Express patterns
Regular HTML/CSS/JavaScript
SQLite database
File system storage

The innovation isn’t in proprietary technology - it’s in the arrangement of simple pieces into something that feels magical.

The real secret sauce is believing that software can be this simple.

This document reveals every technical detail needed to replicate Hyperclay. Use this knowledge wisely - to build simpler, more humane software that puts users in control of their digital lives.