The ESLint configuration in Uptime Watcher is not small. With dozens of plugins and custom rules, understanding what is actually enabled can be painful.

To solve that, we integrated a static build of the ESLint Config Inspector directly into the Docusaurus site, so you can browse the current ESLint config as a web UI.

This post summarizes how that integration works and where to look if you want to extend or regenerate it.

High-level flow​

The data flow is documented in detail in docs/docusaurus/src/pages/engineering-tooling.mdx, but the core idea is simple:

1. Run @eslint/config-inspector against eslint.config.mjs.
2. Emit a static inspector site into docs/docusaurus/static/eslint-inspector/.
3. Let Docusaurus serve it under /Uptime-Watcher/eslint-inspector/.

The relevant commands live in package.json:

{
  "scripts": {
    "build:eslint-inspector": "npx @eslint/config-inspector build --outDir \"docs/docusaurus/static/eslint-inspector\" --base \"/Uptime-Watcher/eslint-inspector/\"",
    "build:eslint-inspector:local": "npm run build:eslint-inspector"
  }
}

The integration itself is driven by a dedicated script and a Docusaurus page.

Build script and verification​

The implementation summary is captured in docs/docusaurus/src/pages/ESLINT-INSPECTOR-DEPLOYMENT-SUMMARY.md, but the key artifacts are:

• scripts/build-eslint-inspector.mjs — orchestrates the inspector build.
• scripts/verify-eslint-inspector.mjs — sanity-checks the generated files.

The build script:

• Invokes npx @eslint/config-inspector build with the correct base URL.
• Copies the output into docs/docusaurus/static/eslint-inspector/.
• Writes a small redirect/loader page so navigation feels seamless.

The verification script checks that:

• The static directory exists.
• index.html and redirect assets are present.
• The expected _nuxt/, api/, and fonts/ assets exist.

When everything is wired correctly, you can run:

npm run build:eslint-inspector
npm run docusaurus:build

and the inspector will be part of the generated docs site.

Docusaurus integration​

On the Docusaurus side, the integration is intentionally light:

• Static files live under docs/docusaurus/static/eslint-inspector/.

• The Docusaurus config adds a link in the footer:

  {
    href: "https://nick2bad4u.github.io/Uptime-Watcher/eslint-inspector/",
    label: "🧪 ESlint Config",
  }
  

• The engineering tooling page includes a section describing the inspector and how it fits into npm run docs:build.

No special plugin is required; it is just a static SPA mounted at a well-known path.

Why this matters​

The ESLint config is a critical part of the project's quality gates. Having an inspector UI baked into the docs site provides concrete benefits:

• Discoverability — contributors can quickly see which rules are enabled without reading a large flat config.
• Reviewability — changes to eslint.config.mjs can be inspected in a UI before/after running the build script.
• Documentation — the Docusaurus pages and deployment summary explain exactly how the inspector is produced and where it lives.

How to regenerate the inspector​

If you change ESLint rules or want to refresh the inspector after a dependency update:

1. Update eslint.config.mjs as usual.

2. Run:

   npm run build:eslint-inspector
   

3. Optionally verify the output:

   node scripts/verify-eslint-inspector.mjs
   

4. Rebuild or redeploy the docs site:

   npm run docs:build
   

That is it — the inspector will reflect the new configuration.

For more detail, see the full

page in the docs.

Electron IPC is a common place where apps quietly rot: ad-hoc channels, mismatched payloads, and copy-pasted handlers that drift over time.

Uptime Watcher takes a different route. IPC contracts are treated as shared types, and we have scripts that fail the build when main and renderer drift apart.

This post explains how the IPC layer is structured, how static guards work, and how that shows up in the git history.

Shared contracts first​

IPC contracts live in the shared layer so both the Electron main process and the React renderer agree on channel names and payload types.

Key pieces:

• shared/types/ipc.ts — maps channels to request/response payloads.
• shared/ipc/rendererEvents.ts — typed event payloads emitted from main to renderer.
• shared/types.ts and related monitor/site types — domain objects used in IPC payloads.

The Electron side uses these contracts in services like electron/services/ipc/IpcService.ts, while the renderer consumes them via preload domain APIs under electron/preload/domains/ and src/services/*Service.ts.

Typed preload APIs​

Rather than calling ipcRenderer.send directly from React components, the preload script defines domain-specific APIs that wrap IPC calls.

Examples:

• electron/preload/domains/sitesApi.ts — site CRUD and monitoring operations.
• electron/preload/domains/monitoringApi.ts — monitor control surface.

Each API function:

• Uses a shared channel constant (e.g. SITES_CHANNELS.addSite).
• Accepts and returns typed payloads defined in @shared/types.
• Applies basic validation / shaping before invoking IPC.

On the renderer side, services like src/services/SiteService.ts consume those APIs, and stores such as src/stores/sites/useSitesStore.ts call the services, not IPC directly.

Static architecture guards​

The glue that keeps IPC contracts from drifting is a set of static checks run as part of CI and npm run lint:ci.

The core script is:

• scripts/architecture-static-guards.mjs

It validates things like:

• IPC channels referenced in Electron services are declared in the shared IPC types.
• Renderer services don"t talk directly to Electron modules; they go through the preload bridge.
• Event names used in the TypedEventBus correspond to entries in the shared event maps.

You can run these guards locally via:

npm run lint:architecture
npm run analyze:ipc
npm run check:ipc

These commands are wired into higher-level scripts like:

npm run lint:all:fix
npm run quality

If a new IPC channel is added only on one side, or if a handler starts returning the wrong shape, those scripts fail quickly.

Git history: when guards caught problems​

Multiple commits in the history reflect this IPC discipline.

IPC generation and checking​

The scripts that generate and verify IPC artifacts live under scripts/generate-ipc-artifacts.mts. Commits around that script tightened validation to ensure:

• All IPC channel enums are covered.
• Renderer event payload maps stay in sync with main-process emitters.

The npm run analyze:ipc and npm run check:ipc commands now run in CI (see lint:ci and quality scripts in package.json). That means changes to IpcService, preload domains, or shared types won"t silently break IPC contracts.

Event system and IPC alignment​

The TypedEventBus defined in electron/events/TypedEventBus.ts and electron/events/eventTypes.ts is wired into IPC so that:

• Internal events (e.g. monitor status changes) are raised with typed payloads.
• Renderer events are forwarded through a dedicated bridge that uses the shared renderer event payload map.

Architecture docs like docs/Architecture/ADRs/ADR_002_EVENT_DRIVEN_ARCHITECTURE.md and docs/Architecture/ADRs/ADR_005_IPC_COMMUNICATION_PROTOCOL.md are not free-form essays; they match real type definitions and the guards mentioned above.

When something drifts, the combination of TypeScript, the architecture script, and the IPC analyzer catches it.

Practical impact​

The IPC contract + static guard approach has concrete benefits:

• Safer refactors — you can rename a monitor field in the shared types, update the database mapping, and rely on the IPC checks to tell you where handler payloads need adjustment.
• Fewer runtime surprises — mismatched payloads or missing event subscriptions are caught at build time rather than during a 3am incident.
• Better documentation — the shared IPC types and ADRs serve as living docs; they are always under pressure from CI to stay honest.

How to extend IPC safely​

If you are adding a new IPC feature, the safe workflow looks like:

1. Define types first

   • Add or extend shared types in shared/types/ipc.ts and related domain types.

2. Wire Electron handlers

   • Implement handlers in electron/services/ipc/IpcService.ts or a domain-specific coordinator.
   • Emit typed events via the TypedEventBus where appropriate.

3. Expose preload APIs

   • Add domain functions under electron/preload/domains/*Api.ts that call the new channel.

4. Consume from renderer services

   • Call the preload APIs from src/services/*Service.ts.
   • Keep components and stores IPC-free.

5. Run the guards

   npm run analyze:ipc
   npm run check:ipc
   npm run lint:architecture
   

Following that pattern keeps main and renderer aligned and ensures that IPC remains a well-behaved, typed boundary instead of a global message bus.

Property-based testing is not just a buzzword in this repo; it has caught real bugs in core monitor logic that traditional example-based tests missed.

This post walks through how we introduced fast-check, where we wired it in, and specific bug classes it exposed in Uptime Watcher.

Where property-based testing fits in the stack​

Uptime Watcher uses fast-check across multiple layers:

• Shared validation – to stress-test helpers like normalizeHistoryLimit and isValidIdentifier with randomized inputs.
• Monitor operations – to generate randomized monitor definitions and ensure conversions between domain objects and database rows are round-trippable.
• Stores and components – to drive Zustand stores and React components with arbitrary site names, URLs, and identifiers, verifying they stay in a valid state even under noisy input.

You can see this in commits like:

• 0797d4d6f – introduces shared fast-check arbitraries and an assertProperty helper.
• acb498188 – expands coverage for site-related components using arbitraries for names, URLs, and IDs.
• c16d48e54 – tightens strict test directories and adds property-based tests to monitor operations and validation schemas.

Example: history normalization bugs​

One of the early wins came from property-based tests around normalizeHistoryLimit, which is responsible for clamping and sanitizing history retention settings.

A simplified property looked like this (adapted from the real tests):

import fc from "fast-check";

import {
  DEFAULT_HISTORY_LIMIT_RULES,
  normalizeHistoryLimit,
} from "@shared/constants/history";

fc.assert(
  fc.property(fc.integer({ min: -10_000, max: 10_000 }), (limit) => {
    const normalized = normalizeHistoryLimit(limit, DEFAULT_HISTORY_LIMIT_RULES);

    // Invariants
    expect(normalized).toBeGreaterThanOrEqual(0);
    expect(normalized).toBeLessThanOrEqual(
      DEFAULT_HISTORY_LIMIT_RULES.maxLimit,
    );
  })
);

That single property immediately exposed edge cases where:

• Negative values were not clamped correctly.
• Large values near the upper bound pushed us past intended limits.

Once the invariants were clear, the implementation was fixed to always return a value within the allowed range, and the property became a regression test that runs in every CI pass.

Example: monitor → database mapping​

The dynamic monitor schema in electron/services/database/utils/dynamicSchema.ts is powerful but easy to get wrong: it maps monitor objects to database rows and back using generated field definitions.

We use property-based tests to generate arbitrary monitor objects and exercise the mapping in both directions:

fc.assert(
  fc.property(monitorArbitrary, (monitor) => {
    const row = mapMonitorToRow(monitor);
    const roundTripped = mapRowToMonitor(row);

    // We don"t require deep equality because some fields are normalized,
    // but core identity must hold.
    expect(roundTripped.siteIdentifier).toBe(monitor.siteIdentifier);
    expect(roundTripped.type).toBe(monitor.type);
    expect(roundTripped.timeout).toBeGreaterThan(0);
  })
);

This kind of test surfaced issues where:

• Certain dynamic fields were not included in the generated column list.
• lastChecked could end up as NaN in the database when passed a malformed value.
• Boolean flags like enabled / monitoring were not consistently mapped to integer 0/1 values.

The fixes in dynamicSchema.ts and the associated helpers are now guarded by these properties.

Example: store invariants under random actions​

Zustand stores such as the site and monitor stores are also exercised with randomized actions.

A typical pattern:

fc.assert(
  fc.property(siteActionSequenceArb, (actions) => {
    const store = createSiteStoreTestHarness();

    for (const action of actions) {
      action.apply(store);

      // Invariants: no duplicate identifiers, selected site (if any) exists
      const state = store.getState();
      const identifiers = new Set(state.sites.map((s) => s.identifier));

      expect(identifiers.size).toBe(state.sites.length);
      if (state.selectedIdentifier) {
        expect(identifiers.has(state.selectedIdentifier)).toBe(true);
      }
    }
  })
);

This style of test flushed out subtle bugs where:

• Removing a site did not always clear selectedIdentifier.
• Certain actions could temporarily leave the store in a state where the selected site no longer existed.

Once fixed, the properties ensure those regressions never reappear.

How to run these tests locally​

All the property-based tests live alongside the rest of the Vitest suite. Useful commands:

# Run all standard tests (frontend default)
npm test

# Focus on fuzzing/property-based tests across projects
npm run fuzz
npm run fuzz:electron
npm run fuzz:shared

# Run coverage across all test projects
npm run test:all:coverage

If you are adding new monitor types, complex validation rules, or store behaviour, consider:

1. Defining a fast-check arbitrary for your domain object.
2. Writing at least one property that encodes an invariant you care about.
3. Running the fuzzing commands above to see what breaks.

Takeaways​

• Property-based testing caught bugs in history normalization, monitor mapping, and store invariants that would have required dozens of manual test cases to reproduce.
• Once the infrastructure (arbitraries, helpers, harnesses) was in place, adding new properties became cheap and paid for itself quickly.
• The tests now run on every CI pass, giving us confidence that changes to core monitor logic don"t silently corrupt data or state.

For a deeper dive into the overall testing approach, see the Testing Architecture & Strategy page and ADR_010_TESTING_STRATEGY.md in the Architecture docs.

Uptime Watcher started as a pragmatic way to watch a handful of URLs from a local machine. By the time we reached v19.0.0, it had grown into a heavily-tested, architecture-driven Electron app with a full documentation and tooling ecosystem around it.

This post walks through that journey using real commits from the git history, focusing on three themes:

• How the architecture solidified around repositories, events, and IPC
• How the testing strategy evolved into strict, property-based coverage
• How documentation and tooling caught up with the rest of the stack

All examples and commit references are taken from the main branch as of 2025-11-25.

Early focus: correctness and documentation​

One of the consistent patterns in this repo is that architecture and documentation are treated as first-class citizens.

A good example is the work captured in 4a0e1fdf1 (tagged as part of v19.0.0):

📝 [docs] Update TSDoc links for consistency

• Correct links in TSDoc-Home.md to point to the appropriate files
• Update TSDoc-Package-Tsdoc.md link to reflect the correct path
• Modify TSDoc-Spec-Overview.md to ensure accurate package reference
• Adjust comments in StatusSubscriptionIndicator.utils.ts for clarity
• Refine useAddSiteForm.ts documentation by removing unnecessary link syntax
• Enhance chartConfig.ts comments for better readability
• Add Stylelint config schema reference in stylelint.config.mjs

This change is representative of the repo's style: fix docs and comments as soon as they become stale, keep configuration files typed and schema-backed, and treat tooling as part of the product.

Another example is cb0e9ed86:

📝 [docs] Update documentation frontmatter and summaries

• Add frontmatter to multiple testing docs
• Update summaries and metadata for clarity and consistency

That work laid the groundwork for the documentation and Docusaurus site that now power the public docs.

Hardening the tooling and CI pipeline​

As the project grew, the CI and linting pipeline became a major focus. Changes like 32bba346a and 4c29fc698 show a pattern:

• Every major tool (ESLint, Stylelint, Mega-Linter, Checkov, Grype, Secretlint, etc.) is wired with explicit schemas.

• New configuration files get schema references immediately, so editors and CI can validate them.

• Linting and scanning are integrated with npm scripts like:

  npm run lint:ci
  npm run lint:all:fix
  npm run docs:check
  npm run docs:validate-links
  

That level of rigor is not just aesthetic; it means refactors in eslint.config.mjs, stylelint.config.mjs, or docs configs are caught early.

Architecting for a long-term Electron app​

Uptime Watcher is not a toy app. It has a service container, a repository layer, a TypedEventBus, and a typed IPC bridge between main and renderer. These ideas are formalized in the Architecture docs and in ADRs like:

• ADR_001_REPOSITORY_PATTERN.md
• ADR_002_EVENT_DRIVEN_ARCHITECTURE.md
• ADR_004_FRONTEND_STATE_MANAGEMENT.md
• ADR_005_IPC_COMMUNICATION_PROTOCOL.md

These aren't just documents; they are enforced in code by scripts like scripts/architecture-static-guards.mjs, which is wired into npm run lint:architecture and the lint:ci pipeline.

One of the commits that made the IPC story much harder to accidentally break is 542eb08db:

✨ [feat] Implement Docusaurus documentation backup workflow

• Add GitHub Actions workflow for building and backing up Docusaurus documentation
• Create backup-docusaurus.yml to automate documentation deployment
• Update package.json with commands for subtree backup and force push
• Add documentation style guide for Docusaurus setup

...

On the surface this looks like just a docs workflow improvement, but it cements the idea that docs and architecture are part of the app, not an afterthought.

The testing story: from unit tests to strict, property-based coverage​

The most striking arc in the git log is the evolution of the test strategy.

Step 1: Strict tests and shared arbitraries​

Commit 0797d4d6f introduced strict test directories and shared fast-check arbitraries:

✨ [feat] Introduce property-based testing for various components and utilities

• Add property-based tests for normalizeHistoryLimit
• Implement property-based tests for isNonEmptyString and isValidIdentifier
• Create property-based tests for useAlertStore
• Add property-based tests for dataValidation
• Add README for strict tests directory
• Introduce shared fast-check arbitraries and an assertProperty helper

This commit is where property-based testing stopped being an experiment and became part of the standard toolbox.

Step 2: Scaling property-based coverage​

The work continued in acb498188:

🧪 [test] Enhance comprehensive test coverage for site-related components

• Use arbitrary site names, URLs, and identifiers in tests
• Refactor multiple component tests to generate dynamic props
• Improve branch coverage for modal and settings flows

Here, the pattern is clear:

• First, establish shared arbitraries and helpers.
• Then, systematically roll them out across components, stores, and utilities.

Step 3: Tightening test configuration​

Most recently, c16d48e54 (paired with c45c0afef and ef6e0dc1a for the version bump) pushed testing further:

✨ [feat] Enhance testing configurations and add property-based tests

• Update tsconfig to include strict test directories for better coverage
• Introduce fast-check for property-based testing in monitor operations and validation schemas
• Add comprehensive property tests for monitor identifiers and status validation
• Improve test coverage for monitor operations with randomized input testing
• Extend Vitest configuration to include strict test directories

Combined with the testing ADR (ADR_010_TESTING_STRATEGY.md), Uptime Watcher now has:

• Dedicated Vitest configs for frontend, Electron, shared, and Storybook
• Strict test projects for cross-cutting concerns
• Property-based tests for core monitor logic, validation, and state stores

When you run:

npm run test:all:coverage

you are not just running unit tests; you are exercising a multi-project test matrix with coverage gates and mutation testing support via Stryker.

UX and UI polish in lockstep with tests​

The git history also shows that UI/UX improvements are usually paired with better tests.

For example, d6311ce2c added a new icon set and refined layout/animation behavior:

✨ [feat] Add new icon assets and improve UI styling

• Introduced new icon files for various sizes
• Updated CSS for layout responsiveness
• Improved scrollbar styles and card hover effects
• Enhanced modal animations and utility helpers for tests

Later, f14823e1e introduced density controls for the site table view:

✨ [feat] Enhance Site List and Card Components

• Add density options ("comfortable", "compact", "cozy")
• Wire density into the UI store
• Expand SiteList and SiteListLayoutSelector tests

The pattern is the same throughout:

• Add a UX feature.
• Wire it into the Zustand stores.
• Extend tests (often with property-based generators) to guarantee the new surface behaves under variation.

Docusaurus and docs as a first-class product​

The documentation site under docs/docusaurus/ is not an afterthought; it has its own build, lint, and backup story.

The commit 542eb08db introduced a Docusaurus backup workflow, new scripts, and a documentation style guide. Later commits like f6e2cb2a4 and c8930adb9 keep that documentation in sync with the main codebase and tooling.

Today, you can work entirely from the root via:

npm run docs:build
npm run docusaurus:start
npm run docusaurus:broken-links

and know that:

• TypeDoc is up to date.
• ESLint Inspector is regenerated.
• Architecture guides and ADRs match the actual code.

Lessons learned​

The following themes stand out from this journey:

1. Docs and tests are not optional — a significant portion of the most important commits are pure documentation or testing work; they are treated as features, not chores.

2. Property-based testing pays off quickly — once fast-check was adopted and shared arbitraries were in place, it became much easier to extend coverage without duplicating effort.

3. Tooling can be a competitive advantage — the investment in linting, schemas, and CI scripts means refactors are safer, documentation stays synchronized, and contributors get rapid feedback from the tooling alone.

4. Electron apps benefit from real architecture — the combination of a service container, repository pattern, TypedEventBus, and strict IPC boundaries makes Uptime Watcher feel more like a production backend than a desktop toy.

Where we go next​

Looking ahead, there are clear directions for Uptime Watcher:

• Expanding the plugin surface for custom monitor types and alert rules
• Deepening analytics and historical reporting
• Introducing new visualizations and dashboards into the Docusaurus site
• Continuing to push on testing rigor, especially around edge-case networking behavior

If you want to dive deeper into how everything fits together, the starting points are:

• System Architecture Overview
• Event System & TypedEventBus
• Testing Architecture & Strategy

Uptime Watcher has come a long way from a simple checker script. The git history tells the story: deliberate architecture, aggressive testing, and a commitment to documentation all the way down.