Technical Architecture

Pre-implementation specification for the Daybook and Common Work systems. This document defines constants, data schema, state machines, business logic, and cross-system bindings. It is technology-agnostic — no database engine, API protocol, or language is assumed.

These two systems form the cooperative's accounting layer: Common Work tracks what the group is doing and how work flows; the Daybook records what individuals have done and observed. Together they produce the audit trail needed for patronage accounting under Subchapter K and RegenHub's member capital account rules.

System map

The Daybook records individual events. Common Work tracks collective work items. A Contribution entry links a person's action to a work item. A Clearing entry closes a matter or resolves a work item. The systems share no tables but reference each other by ID.

Shared primitives

Both systems use these base types. Implementations may alias these to native types; the semantics are fixed.

// Scalar types shared across both systems
type UUID      = string  // RFC 4122 v4; canonical form with dashes
type Timestamp = string  // ISO 8601 UTC, e.g. "2026-06-26T17:30:00Z"
type MemberId  = UUID    // references a registered cooperative member
type EntryId   = UUID    // primary key for a Daybook entry
type MatterId  = UUID    // primary key for an open Daybook matter
type WorkId    = UUID    // primary key for a Common Work item

// Ripe score: integer percentage, 0 = just opened, 100 = ready to land
type RipeScore = number  // constrained to 0 ≤ n ≤ 100; integer only

Constants

DaybookKind

Four kinds. Three require membership. One is open to observers.

const DAYBOOK_KINDS = [
  'reflection',    // witness and perception; open to observers
  'contribution',  // labor, skill, resource given; members only
  'exchange',      // goods or services traded; members only
  'clearing',     // debt / credit resolved; members only
] as const

type DaybookKind = typeof DAYBOOK_KINDS[number]

Visibility states

const VISIBILITY_STATES = ['private', 'public'] as const
type Visibility = typeof VISIBILITY_STATES[number]

// Transition: private → public is one-way and requires a human action.
// There is no mechanism to move a public entry back to private.
// (Correction: a new Clearing entry supersedes; the original stays.)

Membership gate

const MEMBERSHIP_GATE: Record<DaybookKind, boolean> = {
  reflection:   false,  // observer may write
  contribution: true,   // member required
  exchange:     true,   // member required
  clearing:     true,   // member required
}

// "Member" means: registered, dues current, no suspension.
// "Observer" means: registered with name, not yet a member, or
//   not logged in (read-only view of public entries only).

Ripe threshold

const RIPE_THRESHOLD = 100  // score at which a matter is ready to land
const RIPE_FLOOR     =   0  // minimum; newly opened matters start here

// Ripe score is an integer. Non-integer inputs must be floored.
// Score may not decrease once set (matters do not un-ripen).
// Score reaching RIPE_THRESHOLD does not auto-land the matter —
//   it only signals readiness. A human must still act.

Schema

Entry

The atomic unit of the Daybook. Every recorded event is an entry.

interface Entry {
  id:            EntryId                // required; system-generated on create
  kind:          DaybookKind            // required; immutable after creation
  author:        MemberId               // required; who wrote this
  created_at:    Timestamp              // required; system-set on create
  body:          string                 // required; the content of the entry
  visibility:    Visibility             // required; starts 'private', may go 'public'
  published_at:  Timestamp | null       // set when visibility flips to 'public'
  published_by:  MemberId  | null       // must equal author (self-publish only)
  matter_ref:    MatterId  | null       // if this entry addresses an open matter
  work_ref:      WorkId    | null       // contribution entries should reference work
  supersedes:    EntryId   | null       // if correcting a prior entry
}

Matter

An open question that must be decided by a named person. Matters exist in the Daybook's second layer — visible as outline petals in the bloom until landed.

interface Matter {
  id:              MatterId             // required; system-generated
  kind:            DaybookKind          // required; sets bloom petal color
  heading:         string               // required; the open question
  ripe:            RipeScore            // required; starts 0, rises toward 100
  awaits:          string               // required; the decision or action needed
  face:            string               // required; name of person who must land
  face_member_id:  MemberId             // required; machine-readable identity of face
  cite:            string               // optional; bylaw / PRD / agreement reference
  act:             string               // required; describes the landing action
  opened_at:       Timestamp            // required; system-set
  opened_by:       MemberId             // required; who raised this matter
  landed_at:       Timestamp | null     // set when landed
  landed_by:       MemberId  | null     // must equal face_member_id
  landing_entry:   EntryId   | null     // the Clearing entry that closed it
}

Logic

Entry state machine

Landing rule

Ripening

Ripe score expresses how close a matter is to being ready to land. The mechanism for advancing it is deliberately left open — different matters may ripen by different signals (votes, time elapsed, entries added). What is fixed:

Bloom rendering constants

The bloom is a clock-face SVG with one petal per entry kind per time segment. Solid petals are public entries. Outline petals with a fill bar are open matters (fill % = ripe score). These are presentation constants only.

const BLOOM_PETALS    = 12      // clock positions, one per hour segment
const PETAL_RADIUS    = 80      // SVG units from center to petal tip
const PETAL_OPEN_PCT  = 35      // % of PETAL_RADIUS for open-matter fill base
const PETAL_COLORS: Record<DaybookKind, string> = {
  reflection:   '#2563eb',  // blue
  contribution: '#d97706',  // gold
  exchange:     '#9333ea',  // violet
  clearing:     '#16a34a',  // green
}

// Solid petal: fully colored, opacity 0.85, stroke none
// Open-matter petal: stroke only (1.5px), fill = color at (ripe/100)*opacity
// Current-time marker: thin radial line at clock position for current hour

Constants

Stages

const STAGES = [
  'captured',    // noticed; not yet offered to the group
  'offered',     // proposed for collective attention
  'held',        // assigned; someone is working it
  'standing',    // work done; standing for review
  'socialized',  // reviewed and acknowledged by at least one other
  'resolved',    // formally complete; human landing required
  'composted',   // intentionally retired without resolution
] as const

type Stage = typeof STAGES[number]

Stage colors

const STAGE_COLORS: Record<Stage, string> = {
  captured:   '#b45309',  // amber-700
  offered:    '#d97706',  // amber-500
  held:       '#ea580c',  // orange-600
  standing:   '#dc2626',  // red-600
  socialized: '#9333ea',  // violet-600
  resolved:   '#2563eb',  // blue-600
  composted:  '#52525b',  // zinc-600
}

WorkKind

const WORK_KINDS = [
  'task',       // discrete action to be done
  'decision',  // something the collective must decide
  'question',  // inquiry that needs resolution
  'project',   // multi-step container; may have child tasks
] as const

type WorkKind = typeof WORK_KINDS[number]

Schema

WorkItem

interface WorkItem {
  id:               WorkId                // required; system-generated
  title:            string                // required; short human-readable name
  description:      string                // required; full description of the work
  kind:             WorkKind              // required; immutable after creation
  stage:            Stage                 // required; current stage
  created_by:       MemberId              // required; original author
  created_at:       Timestamp             // required; system-set
  assignee:         MemberId  | null      // set when stage reaches 'held'
  parent_id:        WorkId    | null      // for child tasks within a project
  transitions:      StageTransition[]     // full stage history; append-only
  daybook_entries:  EntryId[]             // linked Daybook entries; audit trail
  resolved_at:      Timestamp | null      // set when stage reaches 'resolved'
  resolved_by:      MemberId  | null      // the human who landed it
  composted_at:     Timestamp | null      // set if composted instead of resolved
  composted_by:     MemberId  | null      // coordinator who retired it
  compost_reason:   string    | null      // required when composted
}

StageTransition

interface StageTransition {
  id:          UUID                  // required; system-generated
  work_id:     WorkId                // required; parent item
  from:        Stage | null          // null for initial capture (no prior stage)
  to:          Stage                 // required; target stage
  by:          MemberId              // required; who made this move
  at:          Timestamp             // required; system-set
  rationale:   string | null         // optional; required for compost transitions
  entry_ref:   EntryId | null        // Daybook entry accompanying this move
}

Logic

Stage state machine

Advancement rules

const ALLOWED_TRANSITIONS: Record<Stage, Stage[]> = {
  captured:   ['offered',    'composted'],
  offered:    ['held',       'composted'],
  held:       ['standing',   'composted'],
  standing:   ['held',       'socialized', 'composted'],
  socialized: ['resolved',   'composted'],
  resolved:   [],  // terminal
  composted:  [],  // terminal
}

Coordinator role

Certain transitions require a "coordinator." The coordinator role is not modeled as a static attribute — it is a capability check at transition time. Its definition is an open question (see below), but the required interface is:

interface CoordinatorCheck {
  isCoordinator(member: MemberId, context: WorkItem): boolean
}

// Implementations may define coordinator as: board role, sprint steward,
// designated work-item owner, or by bylaw resolution. Not specified here.

Bindings

The systems reference each other by ID. There is no foreign key enforcement at the data layer — binding integrity is a business logic concern.

Contribution → WorkItem

Clearing entry → Matter landing

Clearing entry → WorkItem resolution

Binding invariants

Invariants

These must hold at all times across both systems. An implementation that violates any of these is incorrect.

Open questions

These are architectural decisions deferred to implementation or board resolution. They are flagged here so they are not accidentally assumed.

Techne Studio · RegenHub, LCA · Boulder, Colorado
Pre-implementation architecture · Last revised 2026-06-26
Not a legal document. Schema and logic subject to board resolution before implementation.