OpenClaw Bot
210 lines
3.7 KiB
Markdown
210 lines
3.7 KiB
Markdown
# 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
|
|
|
|
```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
|
|
|
|
### 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:
|
|
|
|
```text
|
|
Appwrite project: freecastle
|
|
Database: freecastle
|
|
Collection: runtime
|
|
Document: buildpulse_state
|
|
```
|
|
|
|
### Future File-Backed Mode
|
|
|
|
Later, the same data can be saved as:
|
|
|
|
```text
|
|
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:
|
|
|
|
```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`
|
|
- `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.
|