Rewind Developer Guide

Architecture

graph TD
    FE["Frontend<br/><small>SvelteKit + Svelte 5</small><br/><small>:5173</small>"]
    BE["Backend API<br/><small>Bun + Elysia</small><br/><small>:8000</small>"]
    CA["C++ Capture Agent<br/><small>PcapPlusPlus</small>"]
    DB["MongoDB<br/><small>Sessions, Alerts, Notifications</small>"]
    NOTIFY["Notification Channels"]
    EMAIL["Email<br/><small>SMTP</small>"]
    SLACK["Slack<br/><small>Webhook</small>"]
    DISCORD["Discord<br/><small>Webhook</small>"]

    FE <-->|"HTTP / WebSocket"| BE
    BE <-->|"Process I/O"| CA
    BE <--> DB
    BE --> NOTIFY
    NOTIFY --> EMAIL
    NOTIFY --> SLACK
    NOTIFY --> DISCORD

    style FE fill:#ff3e00,color:#fff
    style BE fill:#5e165d,color:#fff
    style CA fill:#00599c,color:#fff
    style DB fill:#47a248,color:#fff

---

Setup

Prerequisites

• Bun 1.0+
• MongoDB 7.x
• C++ build tools
• Admin/sudo access

Install

git clone https://github.com/sreekarnv/rewind.git
cd rewind
bun install

Build capture agent:

cd services/capture-agent
build.bat    # Windows
make         # Linux/macOS

Run

cd services/backend-api && sudo bun run dev    # Terminal 1
cd services/frontend && bun run dev            # Terminal 2

• Frontend: http://localhost:5173
• Backend: http://localhost:8000

---

Workspace

Bun workspaces manage the monorepo. Root package.json:

{
  "workspaces": ["packages/*", "services/*"]
}

Packages:

• @rewind/rql - Query language (used by backend and frontend)
• @rewind/sdk - Client library and CLI

---

Key Patterns

Svelte 5 Runes

Frontend uses Svelte 5 with runes ($state, $derived, $effect).

Notification Dispatcher

Alert notifications route through NotificationDispatcher which sends to all configured channels (Email, Slack, Discord) via the INotificationChannel interface.

graph LR
    A["Alert Triggers"] --> D["NotificationDispatcher"]
    D --> E["EmailChannelAdapter"] --> SMTP
    D --> S["SlackNotificationService"] --> SW["Slack Webhook"]
    D --> DC["DiscordNotificationService"] --> DW["Discord Webhook"]

RQL Compilation

RQL queries compile to either MongoDB queries (compileToMongo) or JavaScript filter predicates (compileToFilter).

Capture Filters

The C++ agent uses regex-based SessionFilter to match host and URI patterns, configured via YAML.

Export

Sessions export from the captures page in HAR 1.2, JSON, or CSV format. The export handles invalid timestamps gracefully.

---

Adding Features

New API Endpoint

1. Create route in services/backend-api/src/routes/
2. Register in services/backend-api/src/index.ts
3. Add frontend API call

New Alert Condition

1. Add type to AlertRule.ts model
2. Add evaluation logic in alert service
3. Update frontend types.ts and CreateAlertModal.svelte

New Notification Channel

1. Implement INotificationChannel interface
2. Register in NotificationDispatcher
3. Add env vars to config

---

Environment Variables

PORT=8000
MONGODB_URI=mongodb://localhost:27017/rewind
DATA_DIR=../capture-agent/output

# Rate limiting
RATE_LIMIT_MAX_REQUESTS=1000    # dev default, 100 in production

# Email
EMAIL_ENABLED=true
EMAIL_SMTP_HOST=smtp.gmail.com
EMAIL_SMTP_PORT=587
EMAIL_SMTP_USER=your-email@gmail.com
EMAIL_SMTP_PASS=app-password
EMAIL_RECIPIENT=admin@example.com

# Slack
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...

# Discord
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

FRONTEND_URL=http://localhost:5173

---

Code Style

• TypeScript throughout (except C++ agent)
• camelCase for variables/functions, PascalCase for types/classes
• Svelte 5 runes, TailwindCSS for styling
• Bun for runtime and package management
• Prefer async/await over raw promises