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.2 KiB

Raw Permalink Blame History

Events

src/event/ mediates between the XMPP protocol layer and consumers (UI, config, chatlog). Two main directions plus one common module.

Files

File	Purpose
`server_events.c/h`	`sv_ev_*` — events triggered by inbound stanzas.
`client_events.c/h`	`cl_ev_*` — events triggered locally (UI / commands).
`common.c/h`	Shared helpers used by both.

Server events (`sv_ev_*`)

Called from src/xmpp/ parsers (message.c, presence.c, iq.c, muc.c, roster.c) once a stanza has been validated and decomposed. Each sv_ev_*:

Updates persistent state (chatlog, roster, accounts).
Pushes UI updates (chatwin_*, mucwin_*, cons_*, console_*).
May invoke plugin callbacks (src/plugins/callbacks.c).

Examples (current symbols, grep sv_ev_ in server_events.c):

sv_ev_incoming_message — chat message arrived.
sv_ev_room_message — MUC message.
sv_ev_presence_update — presence change.
sv_ev_roster_received — roster pushed by server.

Client events (`cl_ev_*`)

Called from cmd_funcs.c and UI code when the user does something locally that needs the same downstream fan-out as a server event.

Examples:

cl_ev_send_msg — outgoing chat message.
cl_ev_send_presence — presence update from /status or autoaway.
cl_ev_disconnect — /disconnect initiated locally.

Adding an event handler

Decide direction: inbound (server) or outbound (client).
Add sv_ev_<name> or cl_ev_<name> in the matching .c and declare in the matching .h.
Call it from the trigger site (a parser in src/xmpp/ for server events; a command handler or UI input handler for client events).
Inside, perform the fan-out: state update → UI → plugin callback.
If unit-tested, add a stub for it in tests/unittests/event/stub_*.c (or extend the existing stub).

See playbooks/add-event-handler.md.

Conventions

Keep XMPP-protocol concerns in src/xmpp/. The event module is a dispatcher, not a parser.
Keep UI rendering decisions in src/ui/. The event module invokes UI functions but does not draw.
Plugin callbacks are the last step — state must already be consistent before they run, since plugins may re-enter the codebase.

2.2 KiB Raw Permalink Blame History