openclaw/buildpulse
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: wire BuildPulse to Appwrite-backed persistence

Browse Source
This commit is contained in:
OpenClaw Bot
2026-05-07 00:31:33 +02:00
parent bdf8773797
commit 63c5a23b48
19 changed files with 1427 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/AI_DEVELOPER_HANDOFF.md
+8 -13
View File
@@ -2,7 +2,7 @@
## Mission
Build a tiny local-first app called BuildPulse.
Build a tiny Appwrite-backed app called BuildPulse.
BuildPulse v0.1 is a single-project planning cockpit for AI-assisted development.
It must allow the user to:
1. Manage a simple feature plan.
@@ -66,7 +66,6 @@ Pulse event fields:
- Agent ID
- Pulse type
- Message
- Structured payload
- Confidence score
- Evidence refs
- Trace ID, optional
@@ -104,14 +103,11 @@ Markdown package:
## Storage
Use local-first browser persistence unless explicitly told otherwise.
Preferred:
- LocalStorage or IndexedDB
Use Appwrite on the Unraid server for canonical persistence.
Also keep a local cache fallback so the app remains usable if the backend briefly flakes out.
Do not add:
- Database
- Auth
- Backend
## Initial Seed Data
@@ -121,7 +117,7 @@ Project name:
BuildPulse
One-line pitch:
A local-first planning cockpit for AI-assisted product building.
A calm planning cockpit for AI-assisted product building.
Current goal:
Ship v0.1 with Feature Plan, Parking Lot, Pulse Log, and Export.
@@ -203,7 +199,7 @@ If tempted, add the idea to Parking Lot instead.
1. Create React/Vite app.
2. Define TypeScript types matching `docs/DATA_SCHEMA.md`.
3. Implement local storage.
3. Implement Appwrite-backed persistence with local cache fallback.
4. Implement project summary.
5. Implement Feature Plan.
6. Implement Parking Lot.
@@ -266,7 +262,7 @@ Read these files before doing anything:
Your task:
Build BuildPulse v0.1 exactly as scoped.
BuildPulse v0.1 is a local-first, single-project planning cockpit for AI-assisted development.
BuildPulse v0.1 is an Appwrite-backed, single-project planning cockpit for AI-assisted development.
Required v0.1 views:
1. Feature Plan
@@ -279,7 +275,7 @@ Required behavior:
- Feature cards in Now / Next / Later / Done
- Parking Lot for distracting ideas
- Manual Pulse Log with future-compatible Pulse event schema
- Local persistence
- Appwrite-backed persistence with local cache fallback
- JSON export/import
- Pulse JSONL export
- Markdown export including CLAUDE_CONTEXT.md
@@ -292,7 +288,6 @@ Hard constraints:
- Do not add local/cloud router
- Do not add real agent integration
- Do not add backend auth
- Do not add database
- Do not add WebSockets
- Do not add GitHub/OpenClaw/Hermes integration
@@ -317,7 +312,7 @@ After coding:
## The shortest version of the project direction
BuildPulse v0.1 is a single-project, local-first feature cockpit with Parking Lot, manual Pulse Log, and AI-context export.
BuildPulse v0.1 is a single-project, Appwrite-backed feature cockpit with Parking Lot, manual Pulse Log, and AI-context export.
It must help me see what I am building, what is active now, what is parked, what happened, and what to hand off to an AI coder next.
Do not build the full Agent Pulse framework yet.
docs/ARCHITECTURE.md
+17 -19
View File
@@ -2,7 +2,7 @@
## Architecture Goal
Keep v0.1 boring, local-first, and easy to understand.
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
@@ -11,19 +11,11 @@ Preferred simple stack:
- React
- Vite
- TypeScript if practical
- LocalStorage or IndexedDB
- 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
Optional if file-backed storage is explicitly wanted:
- Tiny Node/Express backend
- Files:
- `data/project.json`
- `data/features/*.json`
- `data/parking_lot/*.json`
- `data/pulses.jsonl`
Do not add a database in v0.1.
## Design Principle
BuildPulse is pulse-compatible, not pulse-dependent.
@@ -139,17 +131,21 @@ src/
## Storage Strategy
### Fastest v0.1
### v0.1 Canonical Persistence
Use browser storage.
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.
Example key:
Current runtime shape:
```text
buildpulse.appState.v1
Appwrite project: freecastle
Database: freecastle
Collection: runtime
Document: buildpulse_state
```
### Future File-Backed Mode
@@ -160,12 +156,16 @@ Later, the same data can be saved as:
data/
project.json
features/
parking_lot/
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:
@@ -189,7 +189,6 @@ v0.1 Pulse events should already include:
- `agent_id`
- `pulse_type`
- `message`
- `structured_payload`
- `confidence_score`
- `evidence_refs`
- `trace_id`
@@ -201,7 +200,6 @@ Even if many fields are optional or manually filled.
Do not introduce:
- Redux unless needed
- Complex state machines
- Backend services
- Event buses
- WebSockets
- Plugins
docs/DATA_SCHEMA.md
+15 -2
View File
@@ -27,7 +27,7 @@ Current schema version:
{
"id": "project_buildpulse",
"name": "BuildPulse",
"one_line_pitch": "A local-first planning cockpit for AI-assisted product building.",
"one_line_pitch": "A calm planning cockpit for AI-assisted product building.",
"description": "BuildPulse helps capture features, park distracting ideas, log progress as Pulse events, and export clean context for AI coding agents.",
"current_goal": "Ship v0.1 with Feature Plan, Parking Lot, Pulse Log, and Export.",
"notes": "",
@@ -113,6 +113,7 @@ Allowed `risk_level` values:
## Pulse Event
Pulse events are append-friendly and future-compatible with Agent Pulse.
In v0.1, Pulse events are intentionally simple and human-readable.
```json
{
@@ -124,7 +125,6 @@ Pulse events are append-friendly and future-compatible with Agent Pulse.
"agent_id": "jimmi",
"pulse_type": "INTENT",
"message": "Start implementing the Feature Plan screen.",
"structured_payload": {},
"confidence_score": 0.9,
"evidence_refs": [],
"trace_id": "session_001"
@@ -186,6 +186,19 @@ Later form may become:
]
```
## Future Agent Pulse Fields
The full Agent Pulse framework may later add:
- `structured_payload`
- `event_version`
- `parent_event_id`
- `agent_capability`
- `tool_call_refs`
- `artifact_refs`
- `safety_classification`
These are intentionally out of scope for v0.1.
## Settings
Minimal v0.1 settings:
docs/DECISIONS.md
+7 -6
View File
@@ -30,7 +30,8 @@ Reason:
This allows future autonomous agents to emit the same event shape without a major data model rewrite.
Consequences:
- Pulse schema includes future-friendly fields such as `agent_id`, `trace_id`, `confidence_score`, `structured_payload`, and `evidence_refs`.
- Pulse schema includes future-friendly fields such as `agent_id`, `trace_id`, `confidence_score`, and `evidence_refs`.
- Richer Agent Pulse fields such as `structured_payload` are intentionally parked until later versions.
- v0.1 UI may not use all fields deeply.
## Decision 003 — Single Project in v0.1
@@ -79,21 +80,21 @@ Consequences:
- Session view may come later.
- Trace IDs allow grouping session-related pulses later.
## Decision 006 — Local-First Storage
## Decision 006 — Appwrite Canonical Storage with Local Cache Fallback
Date:
2026-05-06
Decision:
BuildPulse v0.1 uses local-first storage.
BuildPulse v0.1 stores canonical state in Appwrite on the Unraid server, with a local cache fallback in the browser.
Reason:
This keeps the first version simple, fast, private, and easy to run.
This keeps the first version durable across sessions while still feeling fast and forgiving in the browser.
Consequences:
- No database.
- No auth.
- No custom auth.
- Export/import is important to avoid lock-in.
- The browser cache is a fallback, not the source of truth.
## Decision 007 — Export Is a Core Feature
docs/EXPORT_FORMATS.md
+2 -2
View File
@@ -55,8 +55,8 @@ Rules:
Example:
```jsonl
{"id":"pulse_001","timestamp":"2026-05-06T00:00:00+02:00","project_id":"project_buildpulse","feature_id":"feature_plan_screen","source":"manual","agent_id":"jimmi","pulse_type":"INTENT","message":"Start implementing Feature Plan.","structured_payload":{},"confidence_score":0.9,"evidence_refs":[],"trace_id":"session_001"}
{"id":"pulse_002","timestamp":"2026-05-06T00:30:00+02:00","project_id":"project_buildpulse","feature_id":"feature_plan_screen","source":"claude_code","agent_id":"claude_code","pulse_type":"RESULT","message":"Feature card creation implemented.","structured_payload":{},"confidence_score":0.8,"evidence_refs":["Manual test passed"],"trace_id":"session_001"}
{"id":"pulse_001","timestamp":"2026-05-06T00:00:00+02:00","project_id":"project_buildpulse","feature_id":"feature_plan_screen","source":"manual","agent_id":"jimmi","pulse_type":"INTENT","message":"Start implementing Feature Plan.","confidence_score":0.9,"evidence_refs":[],"trace_id":"session_001"}
{"id":"pulse_002","timestamp":"2026-05-06T00:30:00+02:00","project_id":"project_buildpulse","feature_id":"feature_plan_screen","source":"claude_code","agent_id":"claude_code","pulse_type":"RESULT","message":"Feature card creation implemented.","confidence_score":0.8,"evidence_refs":["Manual test passed"],"trace_id":"session_001"}
```
## Markdown Package
docs/PRODUCT_BRIEF.md
+2 -1
View File
@@ -6,7 +6,7 @@ BuildPulse
## One-Line Description
BuildPulse is a local-first planning cockpit that helps a solo builder capture features, park distracting ideas, log progress as Pulse events, and export clean context for AI coding agents.
BuildPulse is a calm planning cockpit that helps a solo builder capture features, park distracting ideas, log progress as Pulse events, and export clean context for AI coding agents.
## Problem
@@ -48,6 +48,7 @@ BuildPulse v0.1 lets the user manage one active project with:
- A simple feature plan
- A parking lot for distracting ideas
- A manual Pulse log
- Appwrite-backed persistence on the Unraid server
- Exportable project context
## Core Workflow
docs/SCOPE.md
+8 -9
View File
@@ -94,16 +94,16 @@ Markdown exports:
- PULSE_LOG.md
- CLAUDE_CONTEXT.md
### 6. Local Persistence
### 6. Appwrite Persistence
The app persists data locally.
Acceptable v0.1 storage:
- LocalStorage
- IndexedDB
The app stores its canonical state in Appwrite on the Unraid server.
It may also keep a local cache for fast reloads and temporary offline/failure fallback.
Required v0.1 behavior:
- Appwrite-backed read/write persistence
- Local cache fallback if the backend is temporarily unavailable
- JSON file export/import
No database required.
## Out of Scope for v0.1
Do not implement:
@@ -119,7 +119,6 @@ Do not implement:
- GitHub/Gitea integration
- WebSockets
- Backend authentication
- Database
- Multi-user collaboration
- Notifications
- Advanced analytics
@@ -143,7 +142,7 @@ BuildPulse v0.1 is done when:
6. The user can manually add Pulse events.
7. Pulse events can be linked to features.
8. Pulse events display in chronological order.
9. The app persists data locally after refresh.
9. The app persists data through Appwrite after refresh, with local cache fallback if Appwrite is temporarily unavailable.
10. The user can export JSON.
11. The user can export Pulse events as JSONL.
12. The user can export Markdown context.