# Data flow

High-level paths through the codebase. Use this when reasoning about where a
change should land or where a bug originates.

## User input → action

```
keypress
  → src/ui/inputwin.c           (line editor, key dispatch)
  → src/command/cmd_ac.c        (autocomplete on Tab)
  → src/command/cmd_defs.c      (parse / lookup)
  → src/command/cmd_funcs.c     (handler: cmd_<name>)
  → side effects: src/xmpp/, src/config/, src/ui/, src/event/
```

- Tab triggers autocomplete via `cmd_ac.c` lookup in `ac_funcs` hash table
  (key: `/cmd`, value: per-command `_<cmd>_autocomplete` function).
- Enter parses input via `parse_args()` (`src/tools/parser.c`), looks up the
  `Command*` via `cmd_get()` (`src/command/cmd_defs.c`), invokes the handler
  declared with `CMD_MAINFUNC` or one of the `CMD_SUBFUNCS`.

## Outgoing chat message

```
cmd_msg / typing-into-chatwin
  → src/xmpp/message.c          (build message stanza)
  → src/xmpp/stanza.c           (assemble XML)
  → libstrophe                   (send)
  → src/chatlog.c               (persist locally)
  → src/ui/chatwin.c            (echo into window)
```

Encryption injects between message build and send:

- OMEMO via `src/xmpp/omemo.c` → `src/omemo/omemo.c` (libsignal-protocol).
- OTR via `src/otr/otr.c` (libotr).
- PGP / OX via `src/pgp/gpg.c` / `src/pgp/ox.c` → `src/xmpp/ox.c`.

## Incoming stanza

```
libstrophe callback
  → src/xmpp/{message,presence,iq,muc,roster}.c   (parse, validate)
  → src/event/server_events.c                      (sv_ev_*)
  → src/ui/{chatwin,mucwin,console,...}.c          (render)
  → src/chatlog.c                                  (persist)
```

`server_events.c` is the chokepoint — every inbound XMPP event flows through a
`sv_ev_*` function. UI updates and persistence fan out from there.

## Client-initiated events

`src/event/client_events.c` mirrors `server_events.c` for events that
originate locally (UI actions, command-driven state changes) but need the
same downstream fan-out.

## Connection state

- `src/xmpp/connection.c` owns the `jabber_conn_status_t` (declared in
  `connection.h`).
- `connection_get_status()` returns the current state. Many code paths gate
  on `JABBER_CONNECTED` — see `patterns/xmpp.md`.
- Tests must `will_return(connection_get_status, JABBER_CONNECTED)` (or the
  desired state) before exercising any code path that consults it. See
  `gotchas.md`.

## Plugin hook points

Plugin callbacks (`src/plugins/callbacks.c`) sit on:
- Pre/post message send and receive (around `src/xmpp/message.c` flow).
- Connection lifecycle (around `src/xmpp/session.c`).
- Window-switch events (around `src/ui/window_list.c`).

See `patterns/plugins.md`.