lazysite is a deliberately small engine, but it is built and maintained as a commercial product. It is assessed against an eight-dimension non-functional standard - correctness, code quality, testing, performance, reliability, security, documentation and compliance - under a declared Commercial regime. This page is a factual summary of the architecture and the measures in place, as of the 0.15 line (October 2026): 0.15.16 on the beta channel, with 0.14.4 the most recent stable release.

How it is built

At its core, lazysite does one job: it turns Markdown and a template into an HTML page. That renderer is the whole of what runs when a visitor asks for a page, and it is deliberately small.

Everything else lazysite can do - authoring content, managing domains and themes, the API, WebDAV, accounts and the manager interface - lives in separate components. Those components write files; the renderer reads them, and the one thing it writes is its own output, the cached page. They share a common set of core libraries, and management code runs only in those separate components. The result is that most of the functionality sits outside the render path.

One render path, a separate write plane

What runs when a visitor asks for a page

A request is answered by a single component, the renderer. It reads the content, theme and layout files for the site, runs the Markdown and the template, and returns HTML; two libraries do that work. The renderer also holds the page-level access check - whether a page is public or open to signed-in members of named groups - and runs no management code. What else it loads depends on how it is run:

  • Plain CGI. Each request is a fresh process that starts without the engine's own library. An engine module is loaded at the point a request needs it: the identity reader for a protected page, address lists, data tables, language sets, Odoo. ADR 0001 keeps the CGI render path this way.
  • The FastCGI pool (the one-rule template). Since 0.15.12 the pool parent preloads those same modules, the session and identity readers among them, and every worker inherits them. The worker decides who a signed-in request is, once, with the same function the auth wrapper uses, and renders the page itself; a manager API request is decided the same way and then handed to the API program. Before 0.15.12 these requests went through a separate auth program started for each request, and the split FastCGI templates still work that way.

This is the only part of lazysite that is always on, public and unauthenticated, and it is kept as lean as possible on purpose.

What runs when a site changes

Changing a site is a different path entirely. An operator or an AI agent authenticates, and the request is handled by one of the write components - the MCP connector, the control API, WebDAV, OAuth, the login service, the manager interface or the command-line tools. Each checks the caller's capabilities and then writes the relevant files. These surfaces are off by default and gated by capability, and once they have written their files they step out of the way. The next visitor is served by the renderer reading the files they left behind.

The filesystem is the interface between the two planes. The write side produces files; the read side consumes them. Management code runs in its own programs: in the FastCGI pool the front door hands a manager API request to the API program, which runs its own gate, CSRF and capability checks.

Why it is built this way

  • Reduced security surface. The only always-on, unauthenticated, publicly reachable path is the renderer, which reads files and renders them. The code that changes a site - management, write capability checks, everything that writes content - sits in the write components, away from the path between a visitor and a page. The renderer's own security code is the page-level access check and, for a signed-in visitor, the identity decision.
  • Better performance. The renderer loads only what a request needs, and in the pool it loads that once per worker, so there is less to do on every request.
  • Easier to maintain. Each feature grows in its own component against the shared libraries, without touching the renderer. The renderer stays stable while the rest of the system evolves, and a change to the authoring tools cannot affect how a page is served.

1. Correctness

  • Compile integrity, enforced. Every production Perl file compiles under perl -c, guaranteed by a committed gate (t/lint/04-compile.t) so a non-compiling file cannot pass the suite.
  • One capability resolver. Account capabilities resolve through a single source-of-truth reader consulted identically by the manager, the API, MCP and WebDAV; the deliberate module-free copy on the render hot path is recorded in an architecture decision record (ADR 0001).
  • Path safety. Every filesystem path derived from request input is passed through realpath and verified to sit inside the document root before any file operation.
  • Grounded features. Shipped behaviour is exercised by the test suite, and plugin discovery is honest - each discovered script answers a --describe contract.

2. Code quality

  • Static analysis at severity 3, zero violations (perlcritic), enforced by the suite - plus a separate security-themed pass at the strictest severity 1, also zero.
  • Formatting gate. A house .perltidyrc with a changed-code-only gate: new and edited lines must match the style, without churning the existing tree.
  • Every deviation documented. Each relaxed rule carries a written rationale in the profile and the architecture docs - deliberate, not silently suppressed.
  • Consistent structure. use strict; use warnings everywhere, with shared logic living once in a 97-module library the CGIs consult. Since 0.15.3 the processor itself is a main script and 20 parts beside it, each loaded by absolute path.
  • Shell held to the same bar. Every shipped shell script passes shellcheck with errors forbidden, and a retired-terms lint fails the build if any doc teaches a mechanism the engine has retired.

3. Testing

  • 26,853 automated tests across 1,484 test files at the 0.15.16 release gate - the figures are prove's own summary of the full suite, recorded in the committed gate log, which gains a row only for a build whose gate passed.
  • A six-tier taxonomy: unit, integration, journey, smoke, lint and tools - the CGIs are exercised as real subprocesses in a real CGI environment.
  • Coverage floors of statement 75 and branch 62, held file by file. Since 0.15.5 the floors apply to each CGI and to every part split out of them - each processor part and each manager module, read from the tree so a new part is held when it lands. Seven files carry a named floor of their own: four with branch at 60, one with branch at 50, and two lower floors for the oEmbed fetch and the connector module, each held at what it measured and set to ratchet upward. The coverage stage runs at a stable or certified cut, and a build refuses either cut without it; edge and beta gates run the suite, the benchmark and the release-material checks. Coverage is measured in nine groups, each with the tests that reach its area. The groups start at the whole-suite floors, and until their one re-baseline a shortfall inside a group is recorded as movement; outside that window an unmeasured gated file fails the gate. Every release since 0.15.5 has been edge or beta, so the next stable cut is the first to apply the per-file floors.

4. Performance

  • Render-once, serve-cached. Each page is rendered to .html beside its source and served verbatim thereafter, regenerating only on change - fast by default, nothing recomputed per visit.
  • Persistent workers, same code. The processor also runs as a FastCGI worker pool: the same processor as CGI mode, with module load and startup paid once per worker rather than per request.
  • Benchmark gate, enforced at release. Key operations are timed against a provenance-stamped baseline (host, Perl version, date); the render benchmark is split into cache-hit and render-miss so the figure is honest.
  • Measured properties on record - token verification is materially cheaper than password verification; module-load floors and cache-hit concurrency speedups are documented and tuned.

5. Reliability

  • Backup and restore, tested. Pre-upgrade backups with configurable retention; content and full-system snapshots; in-manager restore takes a safety snapshot first and clears affected caches; full-system restore even supports cross-domain migration. The round trip is covered by tests.
  • Fail-closed writes. Manager and form writes check for the out-of-space/quota case and remove half-written files on failure - with disk-full injection and concurrent-writer races covered by a dedicated test. WebDAV PUT bodies stream in bounded chunks.
  • Concurrency and locking. Theme/layout activation snapshots under an artifact lock (validate -> snapshot -> flip); WebDAV honours a documented 423/429 retry contract.
  • Graceful degradation. Unparseable state falls back to safe defaults rather than failing; the audit reader is rotation- and truncation-aware.
  • Operational tooling. A health-check "doctor" reports OK/WARN/FAIL with remediation hints, evaluates every check as the web-server identity, offers safe --fix repairs and a DAV-endpoint probe; a logrotate snippet ships with the installer.

6. Security

Security is structured around a STRIDE threat model with OWASP ASVS L1 verification (docs/SECURITY.md), enumerating the assets and trust boundaries and pairing each threat category with a concrete control:

Threat category Control in place
Spoofing Two-signal trust gate enforced in the application, with edge-stripping of client X-Remote-* headers as a second layer; HMAC-signed session cookie
Tampering Template engine runs with Perl evaluation disabled; layout authoring gated by capability; content-vs-layout capability split
Repudiation Append-only audit trail (who / what / target / origin / outcome, including denied attempts), on by default, gated by an audit capability; switching it off is itself recorded, naming who and why
Information disclosure Protecting a section moves its content out of the document root; secrets server-denied under restrictive modes; analytics aggregated and IP-anonymised; error surface synthesised
Denial of service Per-IP login rate limiting; upload-size gate; bounded-chunk streaming; fail-closed writes; a bad-URL auto-blocker on by default
Elevation of privilege API/MCP token clients confined to a capability subset, never operators; per-file rules that bind every account, a sysop group included; domain confinement on every surface; manager/remote channel separation

Alongside the model:

  • Adversarial review on the record. A versioned register in the repository records three review rounds with their coverage and root-cause themes: an eleven-agent review (static analysis plus black-box probing, 15 July 2026) with 29 findings, every critical, high and medium one fixed and regression-tested in the following release; a private report (21 July 2026) with four findings, all fixed in 0.9.9; and four parallel adversarial reviews (5 August 2026), run as a pre-release gate, with 35 findings closed for 0.10.5, two of them with recorded qualifications. Later reviews are filed beside it: an eight-dimension review of the background service before 0.13.1, two source-level reviews behind 0.13.9, and an adversarial review of the render path on 7 October 2026 whose findings were fixed.
  • Off by default. Every machine channel - MCP, OAuth, the control API, token exchange, WebDAV - ships disabled behind its own configuration switch, and every contract extension is born disabled; an operator turns on exactly the surfaces a site uses.
  • Controls added across the 0.10 to 0.15 lines - a Content-Security-Policy header with report-only (the default), enforce and off modes; protected content held outside the document root (0.10.8); domain confinement, so a confined caller reaches only its own domains (0.15.3); and a release manifest naming the commit its gate validated, mirrored in a committed gate log (0.10.16).
  • A single SSRF guard for outbound fetches (rejects loopback, private, link-local/metadata and CGNAT ranges), groups-only explicit capabilities, a strict SBOM gate (an undeclared dependency fails the release), secrets-lint (every pattern self-tested against a planted fixture) and security-perlcritic gates all green, and a published coordinated vulnerability disclosure policy.
  • Penetration testing declared honestly. The standard gates the security dimension on an external pentest. The first third-party engagement is deferred under a waiver recorded in ADR 0007, which expires before general-availability marketing begins or on 2026-12-31, whichever comes first; ADR 0010 places the pentest posture among the records a certified cut requires.

7. Documentation

  • Role-scoped for every audience - user, developer, implementor, operator and policy docs around a canonical feature reference, plus README, upgrade guide and security policy.
  • Ten architecture decision records - eight accepted, the stable compatibility freeze proposed and the plugin contract in draft - and architecture docs for security, code quality and performance.
  • Generated, drift-checked references - the capability map, quickstarts and host-dependency list are generated from a single source of truth and golden-tested against drift; CLI tools carry POD that renders to man pages at release.
  • Accessibility - a WCAG 2.1 AA self-assessment of the manager UI and default theme.
  • Ships inside every install - the reference docs (including AI-agent briefings) travel with the product; a commit-keyed CHANGELOG is the single source of truth for what changed.

8. Compliance and supply chain

  • Stable releases with a five-year support period. 0.7.0, the first stable release (July 2026), opened a declared five-year support window. The stable cuts since are 0.8.0, 0.9.10, 0.10.0, 0.11.0, 0.11.1, 0.11.7, 0.12.0, 0.12.1 and 0.14.0 to 0.14.4, and a compatibility freeze for the stable line is proposed in an ADR (ADR 0008).
  • Four release channels - edge, beta, stable and certified (ADR 0010) - with per-site channel selection. Edge is where every build starts, soaked on the operator's own sites; beta carries a stable candidate; stable is supported software, gated and bedded in, and the default for customer rollout; certified is a stable-quality build whose compliance records have been walked - the signed Declaration of Conformity, the restore rehearsal, current registers and the pentest posture. A site's update_channel names the minimum maturity it accepts, so a fleet can hold production sites to stable while trialling betas elsewhere. The releases cut so far are edge, beta and stable.
  • Posture of record - a documented Commercial-regime policy structured around licensing, supply chain, the EU Cyber Resilience Act status, support period and data protection; a Declaration of Conformity is kept as an unsigned draft, which the release manager signs at the certified cut.
  • Software bill of materials - a CycloneDX sbom.json in every release with per-component SHA-256 hashes and SPDX licence ids, behind a strict gate so it can never drift from the code.
  • Install classification and provenance - every shipped file is classified as code (overwritten) or seed (operator content, preserved), with a provenance stamp distinguishing the two.
  • MIT licensed, with per-component licence ids recorded in the SBOM.

At a glance (0.15 line, October 2026)

Measure State
Test suite 1,484 files, 26,853 tests, six tiers, green at the 0.15.16 gate
Compile sweep Enforced over all production files
Static analysis perlcritic severity 3 zero; security theme severity 1 zero
Formatting House profile, changed-code gate; shellcheck error-free
Coverage Statement 75, branch 62, per file across every CGI and its parts, seven named exceptions; run at stable and certified cuts
Benchmark Hot paths within tolerance of a provenance-stamped baseline
SBOM CycloneDX per release, strict gate
Decision records Ten ADRs
Threat model STRIDE + ASVS L1; versioned security-review register, three rounds
Release channels edge, beta, stable, certified; first stable 0.7.0 with five-year support; latest stable 0.14.4
Regime Commercial, MIT licensed

These are the disciplines that keep lazysite a small, auditable codebase you can run in production with confidence - and they are the same enforced rules an AI agent publishes through, exactly as a person would.