# Alloy Development Notes

## Quick Start

```bash
# Make sure Rust is in your PATH (after fresh install)
source $HOME/.cargo/env

# Install dependencies
npm install

# Run in dev mode
npm run tauri dev
```

## Project Structure

```
alloy/
├── src/                      # React frontend
│   ├── components/           # UI components
│   │   ├── ChatInterface.tsx # Main chat UI
│   │   ├── RiffView.tsx      # Draft note editing
│   │   ├── Sidebar.tsx       # Conversation list & search
│   │   └── Settings.tsx      # Settings panel
│   ├── services/             # Business logic
│   │   ├── vault.ts          # File system operations
│   │   ├── riff.ts           # Draft integration logic
│   │   ├── background.ts     # Background orchestrator
│   │   ├── providers/        # AI provider implementations
│   │   ├── skills/           # Skill loading and execution
│   │   ├── tools/            # Built-in tool implementations
│   │   ├── triggers/         # Trigger scheduling and execution
│   │   └── context/          # Context window estimation
│   ├── contexts/             # React contexts
│   ├── hooks/                # Custom hooks
│   ├── types/                # TypeScript types
│   ├── mocks/                # Tauri API mocks for web mode
│   └── App.tsx               # Main app component
│
├── src-tauri/                # Rust backend
│   ├── src/
│   │   └── lib.rs            # Tauri app setup
│   ├── Cargo.toml            # Rust dependencies
│   └── tauri.conf.json       # Tauri configuration
│
└── package.json              # Node dependencies

```

## Key Technologies

- **Frontend**: React 19 + TypeScript + Vite
- **Backend**: Tauri 2 (Rust)
- **AI**: Anthropic, OpenAI, Google Gemini, xAI (Grok), Ollama
- **Storage**: YAML/Markdown files (js-yaml)
- **Styling**: Plain CSS

## Development Flow

1. **Frontend changes**: Hot-reloaded automatically by Vite
2. **Rust changes**: Requires rebuild (Tauri watches and rebuilds)
3. **Config changes**: May require restart

## Dual Runtime Modes

The app runs in two modes:

- **Tauri mode** (`npm run tauri dev`): Native desktop app. Uses `@tauri-apps/plugin-http` for external requests.
- **Server mode** (`npm run dev:web`): Web browser mode, no Rust required. Tauri plugins are swapped for HTTP-based mocks via Vite aliases.

When adding features that use Tauri APIs or make HTTP requests, ensure they work in both modes.

## API Integration

The app supports multiple AI providers. API keys are:
- Stored in `config.yaml` in the user's vault
- Never sent to any server except the respective provider
- Loaded at startup if vault exists

## File Formats

### Conversation (YAML)
```yaml
id: 2025-06-15-1750012200-bike-kickstand
created: 2025-06-15T11:30:00Z
model: anthropic/claude-opus-4-6
messages:
  - role: user
    timestamp: 2025-06-15T11:30:00Z
    content: Hello!
  - role: assistant
    timestamp: 2025-06-15T11:30:05Z
    content: Hi there!
```

### Config (YAML)
```yaml
defaultModel: anthropic/claude-sonnet-4-6
ANTHROPIC_API_KEY: sk-ant-...
OPENAI_API_KEY: sk-...
GEMINI_API_KEY: ...
XAI_API_KEY: xai-...
OLLAMA_BASE_URL: http://localhost:11434
# Optional
SERPER_API_KEY: ...
SONIOX_API_KEY: ...
```

### Memory (Markdown)
```markdown
# Memory

## About me
- Your context here

## Preferences
- Your preferences here
```

## Building for Production

```bash
npm run tauri build
```

Output locations (macOS):
- DMG: `src-tauri/target/release/bundle/dmg/`
- App: `src-tauri/target/release/bundle/macos/`

## Debugging

### Frontend Console
Open DevTools in the Tauri window (right-click → Inspect Element)

### Rust Logs
Check terminal where you ran `npm run tauri dev`

### File Operations
All vault operations can be inspected by looking at the files in your vault folder

## Tips

- **Fast iteration**: Keep `npm run tauri dev` running
- **Test persistence**: Check your vault folder to verify files
- **Web mode**: Use `npm run dev:web` for faster frontend iteration without Rust
- **Search**: Works across all message content in all conversations
- **Memory**: Edit `memory.md` to customize AI context

## Common Issues

**Build fails**: Make sure Rust is installed and in PATH
**API errors**: Check your API keys in `config.yaml` or the Settings panel
**Files not saving**: Verify vault folder permissions
**Search not working**: Check that conversations have loaded

---

Built with lateral thinking & withered technology