# Module Reference

siggy is organized into a flat module structure under `src/`.

## Source files

### `main.rs`

Entry point. Parses CLI arguments, runs the setup wizard if needed, opens the
database, spawns signal-cli, and runs the main event loop. Orchestrates the
startup sequence: setup wizard -> device linking -> app startup.

The event loop polls keyboard input (50ms timeout), drains signal events from
the mpsc channel, and renders each frame with `ui::draw()`.

### `app.rs`

All application state lives in the `App` struct. Owns conversations (stored in
a `HashMap` with an ordered `Vec` for sidebar ordering), the input buffer, and
the current mode (Normal / Insert).

Key entry point: `handle_signal_event()` processes all backend events -- incoming
messages, typing indicators, contact lists, group lists, and errors. This is the
single place where signal-cli events modify application state.

`get_or_create_conversation()` is the single point for ensuring a conversation
exists. It upserts to both the in-memory `HashMap` and SQLite. New conversations
append to `conversation_order`; existing ones are no-ops.

### `signal/client.rs`

Spawns the signal-cli child process and manages communication. Two Tokio tasks:

- **stdout reader** -- reads lines from signal-cli stdout, parses JSON-RPC into
  `SignalEvent` variants, and sends them through the mpsc channel
- **stdin writer** -- receives `JsonRpcRequest` structs and writes them as JSON
  lines to signal-cli stdin

The `pending_requests` map tracks RPC call IDs to correlate responses with their
original method (e.g., mapping a response ID back to `listContacts`).

### `signal/types.rs`

Shared types for signal-cli communication:

- `SignalEvent` -- enum of all events the backend can produce (messages, receipts, typing, read sync, system messages)
- `SignalMessage` -- a message with source, timestamp, body, attachments, group info, text styles
- `TextStyle` / `StyleType` -- text formatting ranges (bold, italic, strikethrough, monospace, spoiler)
- `Attachment` -- file metadata (content type, filename, local path)
- `JsonRpcRequest` / `JsonRpcResponse` -- JSON-RPC protocol structs
- `Contact` / `Group` -- address book and group info

### `ui.rs`

Stateless rendering. The `draw()` function takes an immutable `&App` reference and
renders the full UI: sidebar, chat area, input bar, and status bar.

Sender colors are hash-based (8 colors). Groups are prefixed with `#` in the sidebar.
OSC 8 hyperlinks are injected in a post-render pass (written directly to the terminal
after Ratatui's draw to avoid width calculation issues).

### `db.rs`

SQLite database layer with WAL mode. Four tables: `conversations`, `messages`,
`read_markers`, `reactions`. Schema migration is version-based (currently at v9,
see [Database Schema](database.md)).

Provides `open()` for disk-backed storage and `open_in_memory()` for incognito mode.

### `config.rs`

TOML configuration. The `Config` struct is serialized/deserialized with serde.
Fields: `account`, `signal_cli_path`, `download_dir`, `notify_direct`,
`notify_group`, `desktop_notifications`, `inline_images`, `native_images`,
`show_receipts`, `color_receipts`, `nerd_fonts`, `reaction_verbose`,
`send_read_receipts`, `mouse_enabled`, `theme`. All fields have defaults.

`Config::load()` reads from the platform-specific path (or a custom path).
`Config::save()` writes the current config back to disk.

### `input.rs`

Input parsing. Converts text input into an `InputAction` enum. Handles all
slash commands (`/join`, `/part`, `/quit`, `/sidebar`, `/bell`, `/mute`,
`/block`, `/unblock`, `/attach`, `/search`, `/contacts`, `/settings`,
`/disappearing`, `/group`, `/theme`, `/poll`, `/verify`, `/profile`,
`/about`, `/help`) and their aliases.

Also defines `CommandInfo` and the `COMMANDS` constant used for autocomplete.

### `setup.rs`

Multi-step first-run wizard. Handles signal-cli detection (searching PATH),
phone number input with validation, and triggers the device linking flow.

### `link.rs`

Device linking flow. Runs signal-cli's `link` command, captures the QR code URI,
renders it in the terminal, and waits for the user to scan it with their phone.
Checks for successful account registration afterward.
