inboxer/README.md

# inBOXER

AI-powered email classification and organization tool. Connects to your
IMAP mailbox, classifies incoming emails via DeepSeek AI, and moves them
into organised folders automatically.

## One-Line Install

```bash
curl -sSL https://git.lohmar.co.uk/cclohmar/inboxer/raw/branch/main/install.sh | sudo bash
```

This will:
- Download the binary, config, and prompt file from the repository
- Create the `inboxer` system user
- Install everything under `/opt/inboxer/`
- Create and start a systemd service

After install, edit the configuration to set your credentials:

```bash
sudo nano /opt/inboxer/bin/config.yaml
```

Required settings:
- `ai.api_key`  --  your DeepSeek API key
- `smtp.host`, `smtp.port`, `smtp.username`, `smtp.password`  --  SMTP credentials for sending OTP login emails
- `server.session_secret`  --  change from the default

Then start the service:

```bash
sudo systemctl start inboxer
```

## Manual Install

### Prerequisites

- Go 1.21+ (for building from source)
- A DeepSeek API key ([platform.deepseek.com](https://platform.deepseek.com/))
- SMTP credentials for sending OTP emails

### Build from Source

```bash
git clone https://git.lohmar.co.uk/cclohmar/inboxer.git
cd inboxer
make build
```

The binary is written to `bin/inboxer`. Copy the entire `bin/` directory
to your target machine or deploy via `install.sh`.

### Run Directly

```bash
cp .env.example .env
# edit .env with your credentials

make run
```

The web interface will be available at `http://localhost:8080`.

### Deploy Manually to /opt/inboxer

```bash
sudo mkdir -p /opt/inboxer/{bin,data,logs}
sudo cp bin/inboxer     /opt/inboxer/bin/
sudo cp bin/config.yaml /opt/inboxer/bin/
sudo cp bin/prompt.txt  /opt/inboxer/bin/
```

Edit `/opt/inboxer/bin/config.yaml` to set credentials and adjust paths:
- `database.path: /opt/inboxer/data/db.sqlite`
- `logging.file: /opt/inboxer/logs/inboxer.log`

Create the systemd service at `/etc/systemd/system/inboxer.service`:

```ini
[Unit]
Description=inBOXER - AI-Powered Email Classifier
After=network-online.target

[Service]
Type=simple
User=inboxer
Group=inboxer
WorkingDirectory=/opt/inboxer
ExecStart=/opt/inboxer/bin/inboxer
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
```

Enable and start:

```bash
sudo systemctl daemon-reload
sudo systemctl enable inboxer
sudo systemctl start inboxer
```

## Configuration

All configuration lives in a single file: `bin/config.yaml`.

| Section | Key | Description |
|---------|-----|-------------|
| `server` | `port` | Web interface port (default: 8080) |
| `server` | `host` | Bind address (default: 0.0.0.0) |
| `server` | `session_secret` | Session encryption key  --  change in production |
| `database` | `path` | SQLite database file path |
| `smtp` | `host` | SMTP server hostname |
| `smtp` | `port` | SMTP server port (typically 587 for STARTTLS) |
| `smtp` | `username` | SMTP login username |
| `smtp` | `password` | SMTP login password |
| `ai` | `api_key` | DeepSeek API key |
| `ai` | `model` | DeepSeek model (default: deepseek-chat) |
| `ai` | `prompt_file` | Path to classification prompt template |
| `folders` | `*` | IMAP folder names for classified emails |

## Service Management

```bash
sudo systemctl status  inboxer    # check status
sudo systemctl restart inboxer    # restart after config change
sudo systemctl stop    inboxer    # stop the service
sudo journalctl -u     inboxer -f # follow the logs
```

## Features

- **Email + OTP Authentication**: Login with just your email address
- **AI-Powered Classification**: DeepSeek LLM sorts email into 7 categories
- **7 Classification Folders**: Important, eCommerce, Notifications, Finance,
  Social, Other, Spam
- **Mobile-First Web Interface**: Responsive design for all devices
- **Test Mode**: Preview AI decisions without moving emails
- **Empty-Inbox Guarantee**: Every email is processed unconditionally

## Architecture

```
src/
  cmd/         - Entry point (main.go)
  pkg/config/  - Configuration loader
  internal/
    auth/      - OTP authentication & SMTP sender
    imap/      - IMAP client (fetch, move, create folders)
    ai/        - DeepSeek API client & classifier
    db/        - SQLite database (GORM)
    web/       - HTTP handlers & templates
    worker/    - Background email processing
  web/
    templates/ - Go HTML templates (mobile-first)
bin/           - Pre-built binary & configuration files
```

See `PROJECT_PLAN.md` for detailed architecture and development phases.

## License

See `docs/LICENSE.md` for license information.