# Dangerous Pi - Development Guide

## Quick Start

### 1. Install Dependencies

```bash
# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install Python dependencies
pip install -r requirements.txt
```

### 2. Run Tests

```bash
# Test backend components
python test_backend.py
```

### 3. Start Backend Server

```bash
# Development mode with auto-reload
python -m app.backend.main

# Or using uvicorn directly
uvicorn app.backend.main:app --reload --host 0.0.0.0 --port 8000
```

### 4. Test API Endpoints

```bash
# Health check
curl http://localhost:8000/api/health

# System info
curl http://localhost:8000/api/system/info

# PM3 status (uses mock when no hardware present)
curl http://localhost:8000/api/pm3/status

# Create session
curl -X POST http://localhost:8000/api/system/session/create \
  -H "Content-Type: application/json" \
  -d '{"force_takeover": false}'

# Execute PM3 command (mock)
curl -X POST http://localhost:8000/api/pm3/command \
  -H "Content-Type: application/json" \
  -d '{"command": "hw version", "session_id": "your-session-id"}'

# SSE events stream
curl -N http://localhost:8000/sse/events
```

## Project Structure

```
dangerous-pi/
├── app/
│   ├── backend/           # FastAPI backend
│   │   ├── main.py        # App entry point
│   │   ├── config.py      # Configuration
│   │   ├── api/           # REST endpoints
│   │   ├── sse/           # SSE endpoints
│   │   ├── workers/       # PM3 worker
│   │   ├── managers/      # Business logic
│   │   └── models/        # Database models
│   ├── frontend/          # Web UI (TBD)
│   ├── plugins/           # Optional plugins
│   └── scripts/           # Helper scripts
├── data/                  # SQLite database
├── logs/                  # Application logs
├── pi-gen/                # OS image builder
├── requirements.txt       # Python deps
├── test_backend.py        # Backend tests
└── claude.md              # AI dev guide
```

## API Documentation

Once the server is running, visit:
- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc

## Development Workflow

### Backend Development

1. **Add new endpoint**:
   - Create/edit router in `app/backend/api/`
   - Register router in `app/backend/main.py`
   - Test with curl or Swagger UI

2. **Add new manager**:
   - Create manager in `app/backend/managers/`
   - Use in API endpoints
   - Add tests

3. **Add SSE event**:
   - Add helper function in `app/backend/sse/events.py`
   - Call from managers/workers
   - Test with `curl -N`

### Testing on Raspberry Pi

1. **Transfer code**:
   ```bash
   rsync -avz --exclude 'venv' --exclude '__pycache__' \
     . dt@10.3.141.1:/home/dt/dangerous-pi/
   ```

2. **SSH into Pi**:
   ```bash
   ssh dt@10.3.141.1
   ```

3. **Install and run**:
   ```bash
   cd dangerous-pi
   pip3 install -r requirements.txt
   python3 -m app.backend.main
   ```

## Mock vs Real PM3

The backend automatically uses `MockPM3Worker` when the `pm3` module is not available. This allows development without Proxmark3 hardware.

To use real PM3:
- Ensure Proxmark3 client is installed with Python support
- The `pm3` module must be importable
- Set `PM3_DEVICE` environment variable to your device path

## Environment Variables

Copy `.env.example` to `.env` and customize:

```bash
cp .env.example .env
nano .env
```

See [claude.md](claude.md) for full list of environment variables.

## Next Steps

See [claude.md](claude.md) for:
- Detailed architecture
- Implementation roadmap
- PM3 API usage
- Integration guidelines

## Troubleshooting

### Port 8000 already in use
The existing pi-pm3 uses ttyd on port 8000. Either:
- Change PORT in config to 8001
- Stop ttyd: `sudo systemctl stop ttyd-bash`

### PM3 module not found
Expected during development. The mock worker will be used automatically.

### Database locked
Stop all running instances of the backend.