chore: seed BuildPulse v0.1 documentation package

2026-05-06 23:59:31 +02:00
commit 8f0ba43728
14 changed files with 2427 additions and 0 deletions
@@ -0,0 +1,211 @@
+# BuildPulse Architecture
+
+## Architecture Goal
+
+Keep v0.1 boring, local-first, 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
+- LocalStorage or IndexedDB
+- 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.
+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
+
+```text
+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
+
+### Fastest v0.1
+
+Use browser storage.
+- Store one serialized app state object.
+- Include a schema version.
+- Support export/import to avoid lock-in.
+
+Example key:
+
+```text
+buildpulse.appState.v1
+```
+
+### Future File-Backed Mode
+
+Later, the same data can be saved as:
+
+```text
+data/
+  project.json
+  features/
+  parking_lot/
+  pulses.jsonl
+```
+
+Do not build this unless explicitly requested for v0.1.
+
+## Migration Strategy
+
+Every stored state must include:
+
+```json
+{
+  "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`
+- `structured_payload`
+- `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
+- Backend services
+- Event buses
+- WebSockets
+- Plugins
+- Agent daemons
+- Multi-user permissions
+
+Keep it simple.