Introduction to PuppyPad
Relevant source files
The following files were used as context for generating this wiki page:
PuppyPad hosts free static homepages in an "old-web" style. It provides each member with a unique subdomain for their site. The system includes a file manager, an in-browser code editor, and built-in community features like hit counters and guestbooks.
Sources: README.md:3-6, PLAN.md:3-6
System Architecture
PuppyPad uses a standard web stack centered on Node.js and SQLite. It operates as a single Express application behind a Caddy reverse proxy. The proxy handles TLS certificates via Cloudflare DNS challenges.
Core Infrastructure Components
The system architecture consists of four primary layers:
- Proxy Layer: Caddy manages HTTPS and routes traffic to the correct subdomain.
- Application Layer: An Express server handles routing, logic, and view rendering.
- Data Layer: SQLite stores user data, while the local filesystem holds member site files.
- Worker Layer: A headless Playwright instance generates screenshots for site previews.
Sources: PLAN.md:12-32, src/server.js:108-115
Request Routing Flow
The Express application differentiates between requests to the main domain and member subdomains. The main router manages account actions, explore pages, and admin tools. The site router serves static files and widgets for individual member pages.
This diagram illustrates how PuppyPad routes incoming traffic based on the Host header to either the primary service or individual member sites.
Sources: PLAN.md:12-25, src/server.js:108-125
Key Features and Functional Modules
PuppyPad organizes its functionality into several modules that support site creation, serving, and community interaction.
Site Building and Management
Members build sites using standardized templates or custom HTML. The dashboard provides tools for file manipulation and site styling.
| Component | Description | Source |
|---|---|---|
| Code Editor | In-browser CodeMirror editor with live sandboxed preview and tag autocomplete. | README.md:19-21, src/views.js:464-500 |
| File Manager | Supports drag-and-drop uploads, folder creation, zip imports, and full site exports. | README.md:14-17, src/server.js:338-375 |
| Style Editor | Generates puppypad.css to manage colors, fonts, borders, and backgrounds without manual CSS. | src/style.js:37-60, README.md:22-23 |
| Starter Layouts | Four base templates (Sky, Shrine, Notebook, Arcade) used at signup or for new pages. | src/views.js:364-375, README.md:11-13 |
Integrated Widgets
The system provides dynamic functionality through SVG-based widgets and sandboxed iframes.
This sequence shows the interaction between a member's static page and the server's dynamic widget endpoints.
Sources: src/server.js:145-155, src/widgets.js:12-40
Security and Moderation
PuppyPad implements specific security measures to protect the host domain and manage member content.
Protection Mechanisms
- Session Security: Uses
__Host-sidcookies to prevent member subdomains from reading or overwriting session data. - Resource Isolation: Serves member sites on subdomains and runs editor previews in sandboxed iframes.
- Content Safety: Automatically flags HTML containing password or card fields into a moderation queue.
- Rate Limiting: Limits signups, logins, and API requests per member and IP.
Sources: PLAN.md:40-60, README.md:80-88, src/server.js:255-270
Operational Limits
The system enforces limits defined in the environment configuration to maintain server stability.
| Limit | Default Value | Purpose |
|---|---|---|
QUOTA_MB | 500 MB | Maximum storage space per member site. |
MAX_FILE_MB | 5 MB | Maximum size allowed for a single file upload. |
BANDWIDTH_MB | 1024 MB | Daily bandwidth serving limit per site. |
RENAME_DAYS | 30 Days | Cooling period between site name changes. |
Sources: src/server.js:25-35, README.md:24-28
Conclusion
PuppyPad provides a complete environment for hosting and discovering static personal websites. By combining simple architecture with robust management tools and community features, it offers a functional modern platform for old-web aesthetics. The system prioritizes security through host isolation and content moderation while remaining accessible via lightweight deployment models.
Sources: README.md:95-105, PLAN.md:310-320