Workpads: A Job Record System Designed for Real-World Constraints

Modern software for small teams often assumes ideal conditions—stable staffing, reliable connectivity, and time to manage accounts and tools before work begins. In practice, many field and trade environments operate without those guarantees.

Workpads is designed from the opposite starting point. It focuses on a single, durable unit: the job record—a compact, structured document that captures what happened, what needs to happen next, and why.

A Different Starting Assumption

Typical tools expect:

  • consistent teams
  • desktop-first workflows
  • always-on internet
  • upfront setup overhead

Workpads assumes:

  • work begins in the field
  • teams change frequently
  • devices may be limited
  • connectivity is unreliable
  • simplicity is non-negotiable

The result is a system optimized for immediacy and resilience, rather than feature depth.

The Core Idea: One Record That Carries Everything

Instead of spreading information across multiple systems, Workpads centers coordination around a single artifact.

A well-formed job record should:

  • capture the task clearly
  • guide execution
  • provide context for collaborators
  • remain useful after completion

If that unit is reliable, many secondary systems become optional.

The PADS Model

Workpads structures each record using a compact schema called PADS:

  • Processes — structured job fields
  • Actions — step-by-step instructions
  • Details — concise notes and context
  • Story — longer narrative or reflection

This model is intentionally constrained. It is broad enough to represent real work while remaining lightweight enough to function on low-end devices.

Product Principles

Simplicity as a Constraint

  • Built with plain HTML, CSS, and JavaScript compatibility
  • Minimal moving parts
  • Additional complexity is optional, not required

Local-First Operation

  • No account required for baseline use
  • Data can exist entirely on-device
  • Storage policies can favor ephemeral or persistent use

Frictionless Sharing

  • Records can be encoded into compact URLs
  • Recipients reconstruct the full record from the link
  • Payload size is visible and optimized

Compatibility-Driven Design

  • Designed to run on constrained environments (e.g., KaiOS-class devices)
  • Consistent behavior across CLI, browser, and future clients

Contract-First Architecture

  • One shared data model
  • Multiple clients consuming identical contracts
  • Reduced divergence as the system evolves

Who This Serves

Workpads is aimed at:

  • owner-operators in field businesses
  • dispatchers coordinating daily work
  • workers who need access without onboarding into full systems

Common tasks include:

  • quickly creating a job record
  • sharing instructions and context
  • coordinating without heavy tooling
  • preserving knowledge for future jobs

What a Good Workflow Looks Like

An effective Workpads interaction should be:

  • fast enough for field entry
  • clear enough for handoff
  • compact enough for link-based sharing
  • structured enough for later analysis

The emphasis is not on features, but on clarity under constraint.

System Architecture (Overview)

Workpads follows a service-oriented model with thin clients:

  • Gateway Service — central orchestration point
  • Template Registry — validates and normalizes templates
  • Record Service — manages workpad records
  • Storage Policy Service — resolves storage behavior
  • Comment Service — supports optional social interaction
  • Codec Service — handles encoding/decoding
  • Link Service — builds and parses shareable URLs

Clients—CLI, browser, or mobile—interact through the same contracts.

CLI as a First-Class Client

The command-line interface is not secondary. It defines the system’s behavior.

Design rule:

  • Any browser workflow must map to a CLI equivalent
  • Any CLI workflow must use the same request/response structure

This approach stabilizes the system early and simplifies future client development.

Data Model (Simplified)

A canonical record follows the PADS structure:

{
  "templateId": "svc-basic",
  "variant": "plain",
  "process": {},
  "actions": [],
  "details": "",
  "story": "",
  "comments": []
}

For sharing, this is compressed into a smaller payload suitable for URLs.

Templates and Flexibility

Templates define the shape of records and can be authored in:

  • simple key-value format
  • YAML

Both compile into a normalized runtime schema. This allows:

  • human-friendly editing
  • consistent execution

Storage and Sharing

Storage behavior is explicit and policy-driven:

  • ephemeral — short-lived, minimal persistence
  • stored — retained for later access

Sharing is based on encoded links:

  • records are portable
  • no account or system access is required
  • size is monitored to maintain efficiency

Social Mode (Optional)

Workpads supports two conceptual modes:

  • plain — core record only
  • social — record plus comments

Identity is minimal by design, with anonymous-first behavior and optional display names.

Current Capabilities

The CLI currently supports:

  • template validation and compilation
  • record creation, editing, sharing, and import
  • rendering and export
  • storage policy management
  • comment operations
  • size analytics (min, max, average payloads)

What’s Intentionally Deferred

To maintain focus, several features are paused:

  • multiple encoding strategies
  • encryption
  • strict size limits

These are not rejected—only delayed until the core system is stable.

Why This Approach Holds

Product Perspective

  • Small teams benefit from fewer dependencies
  • A portable, readable record improves coordination
  • A consistent structure compounds value over time

Technical Perspective

  • Contract-first services reduce fragmentation
  • Local-first improves reliability in poor conditions
  • Template normalization balances flexibility and consistency

Operational Perspective

  • CLI-first development strengthens system integrity
  • Additional clients can be built on proven contracts
  • Size tracking enforces discipline in data design

Repository

The project is available here: → workpads https://github.com/babbworks/workpads

Getting Started

From the project directory:

npm install
node ./workpads.js help

Example workflow:

node ./workpads.js template:validate --file ./templates/svc-basic.kv --format kv
node ./workpads.js create --template svc-basic --variant plain --set process.job="Replace faucet"
node ./workpads.js share --record loc_000001

Closing View

Workpads is built on a narrow premise:

If the job record is clear, portable, and complete, coordination becomes significantly easier.

Rather than expanding outward into complex systems, it focuses inward—on making that single unit reliable.