buildpulse/docs/ARCHITECTURE.md

BuildPulse Architecture

Architecture Goal

Keep v0.1 boring, Appwrite-backed, and easy to understand. BuildPulse should be simple enough for AI coding agents to modify safely without losing context.

Recommended v0.1 Stack

Preferred simple stack:

• React
• Vite
• TypeScript if practical
• Tiny local API bridge to Appwrite on the Unraid server
• Appwrite document persistence for canonical state
• LocalStorage cache fallback in the browser
• Markdown/JSON export

Design Principle

BuildPulse is pulse-compatible, not pulse-dependent. That means:

• Pulse event shape exists from day one.
• Events can be manual in v0.1.
• Future agents can emit the same event shape later.
• No full event bus is required in v0.1.

High-Level Modules

App Shell

Responsible for:

• Navigation
• Layout
• Active view
• Global app state loading/saving

Views:

• Feature Plan
• Parking Lot
• Pulse Log
• Export

Project Store

Responsible for:

• Single project data
• Feature cards
• Parking Lot items
• Pulse events
• Import/export

Feature Plan Module

Responsible for:

• Feature CRUD
• Column movement
• Feature detail editing
• Acceptance criteria

Parking Lot Module

Responsible for:

• Parked idea CRUD
• Reason parked
• Future placement
• Risk

Pulse Log Module

Responsible for:

• Manual Pulse event creation
• Chronological event display
• Feature-linked filtering
• Trace ID grouping later

Export Module

Responsible for:

• Full JSON export/import
• JSONL Pulse export
• Markdown context export
• CLAUDE_CONTEXT.md generation

Suggested Source Structure

src/
  main.tsx
  App.tsx
  components/
    AppShell.tsx
    Navigation.tsx
    EmptyState.tsx
    Modal.tsx
    TextInput.tsx
    TextArea.tsx
    Select.tsx
  features/
    feature-plan/
      FeatureBoard.tsx
      FeatureCard.tsx
      FeatureDetail.tsx
      featureUtils.ts
    parking-lot/
      ParkingLotView.tsx
      ParkingLotItemCard.tsx
      ParkingLotItemDetail.tsx
    pulse-log/
      PulseLogView.tsx
      PulseEventForm.tsx
      PulseEventItem.tsx
      pulseUtils.ts
    export/
      ExportView.tsx
      exportMarkdown.ts
      exportJson.ts
    project/
      ProjectSummary.tsx
      projectDefaults.ts
  store/
    types.ts
    appStore.ts
    storage.ts
    migrations.ts
  utils/
    ids.ts
    dates.ts
    validation.ts

Storage Strategy

v0.1 Canonical Persistence

Use Appwrite on the Unraid server as the source of truth.

• Store one serialized app state object.
• Include a schema version.
• Mirror the latest good state into browser storage as a cache/fallback.
• Support export/import to avoid lock-in.

Current runtime shape:

Appwrite project: freecastle
Database: freecastle
Collection: runtime
Document: buildpulse_state

Future File-Backed Mode

Later, the same data can be saved as:

data/
  project.json
  features/
    feature_001.json
    feature_002.json
  parking_lot.json
  pulses.jsonl

Do not build this unless explicitly requested for v0.1.

For v0.1, do not build this file-backed mode unless explicitly requested. Export/import should still preserve this same logical structure.

Migration Strategy

Every stored state must include:

{
  "schema_version": "0.1.0"
}

Add migrations later if needed.

Future Agent Pulse Compatibility

v0.1 Pulse events should already include:

• id
• timestamp
• project_id
• feature_id
• source
• agent_id
• pulse_type
• message
• confidence_score
• evidence_refs
• trace_id

Even if many fields are optional or manually filled.

Explicit Non-Architecture

Do not introduce:

• Redux unless needed
• Complex state machines
• Event buses
• WebSockets
• Plugins
• Agent daemons
• Multi-user permissions

Keep it simple.