# 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.