SHA256

Files

docs: split context into layered, agent-oriented files

Replace the single file-structure.md with a stratified layout designed
for AI/agent skill consumption: tables and concrete identifiers over
prose, files loaded on demand, content separated by churn rate.

Layers:
- architecture/  stable structural reference (overview, source-map,
                 test-map, data-flow)
- patterns/      memory, commands, autocomplete, events, xmpp,
                 encryption, ui, plugins
- testing/       unit-tests, stubs, functional-tests, bench
- build/         local, docker, ci
- playbooks/     add-command, add-test, add-autocomplete,
                 add-event-handler, add-encryption
- gotchas.md     append-only dated entries (seven seed entries)
- wip/           branch-specific notes; deleted on merge to master

Stable layers describe cproof on master only. In-flight feature
branches (currently feat/ai) get a single file under wip/.

INDEX.md is the entry map with churn labels; SKILL.md is the
always-loaded skill hint pointing to it.

2026-04-30 20:52:06 +03:00

2.7 KiB

Raw Permalink Blame History

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.

2.7 KiB Raw Permalink Blame History