--- a/doc/Arch-design	Fri Dec 22 06:38:16 2023 +0000
+++ b/doc/Arch-design	Fri Dec 22 09:29:21 2023 +0000
@@ -527,6 +527,145 @@
 desirable to be able to detect and suppress them.  The details remain to be
 worked out.
 
+2.5. Local socket interface between SMSC components
+
+There will be an ad hoc local UNIX domain socket interface between different
+components of ThemWi-SMSC.  themwi-smsc-core will be the single server for this
+local socket i/f, and all other components will connect to it as clients.
+Local socket clients will be able to function in two fundamental ways on this
+internal interface:
+
+a) Irrespective of any other function, each local socket client will be able to
+   execute "pure client" exchanges with themwi-smsc-core, such as
+   SMSC_REQ_SUBMIT and SMSC_REQ_CANCEL.
+
+b) Long-lived SMSC components that perform certain specific roles (IMSI lookup
+   role, GSM MT delivery role, SMPP peer delivery role for each upstream or
+   downstream peer) will register with themwi-smsc-core as role-handlers for
+   these specific roles.
+
+The architectural model of this internal socket i/f is that of request-response
+exchanges: each message is either a request or a response, with responses
+matched to requests.  There are two possible directions for such exchanges:
+
+* For "pure client" operations and role-handler (RH) registration exchanges,
+  requests flow from the connected client to themwi-smsc-core;
+
+* Once an RH has successfully registered and declared itself to be in "service
+  up" state, themwi-smsc-core will initiate certain requests toward this RH,
+  as detailed in this section.
+
+2.5.1. Pure client exchanges
+
+All exchanges listed in this section consist of a request issued by the client
+toward themwi-smsc-core and a response message in the reverse direction.  These
+commands will be sent by standalone clients like themwi-smsc-submit and also by
+role-handler components: the same process that acts as RH for GSM MT delivery
+will need to submit SMs coming from GSM MO activity, the same process that acts
+as RH for delivery to a given SMPP peer will need to submit SMs coming from
+that peer, etc.
+
+2.5.1.1. SMSC_REQ_SUBMIT
+
+This command submits or enters or injects a new SM into the SMSC.  The client
+will send a struct sm_record, and themwi-smsc-core takes over from there.  All
+processing described in section 2.4 happens upon this command; failure at any
+of the steps detailed there will result in an error response to the issuing
+client in this exchange.  A successful response indicates that the new SM has
+been written into PMS and accepted by the SMSC.
+
+2.5.1.2. SMSC_REQ_CANCEL
+
+This command requests that an active (not yet delivered or timed out) SM be
+canceled.  The SM to be canceled can be identified by its absolute index
+(0-based absolute position in PMS) or by a tuple of {OA, DA, MR} - the latter
+option is needed for implementation of cancel operation via SMS-COMMAND from
+GSM MO side.
+
+2.5.1.3. SMSC_REQ_CHANGE_SRR
+
+This command is similar to SMSC_REQ_CANCEL (supports the same ways of
+identifying the target message), but instead of cancelling the message, it
+changes the state of Status Report Requested flag.
+
+2.5.2. Role handler registration and service state
+
+These exchanges flow in the same direction as those listed in section 2.5.1
+(from the connected client to themwi-smsc-core), but are issued only by specific
+long-lived processes that serve as specific role-handlers.
+
+2.5.2.1. SMSC_RH_REGISTER
+
+The long-lived connected client process sending this request is asking to
+register for its specific role.  The following 3 roles are possible:
+
+* ROLE_IMSI_LOOKUP
+* ROLE_GSM_MT_DELIVERY
+* ROLE_PEER_DELIVERY
+
+If the role type is ROLE_PEER_DELIVERY, there is an additional argument naming
+the specific peer; non-empty names identify downstream peers and the special
+name "" (null string) identifies the upstream peer.  For the other two role
+types, there is no such extra argument: there is only one ROLE_IMSI_LOOKUP and
+only one ROLE_GSM_MT_DELIVERY.
+
+Only one client can be registered for each role: one for ROLE_IMSI_LOOKUP, one
+for ROLE_GSM_MT_DELIVERY and one for each peer.  Registration attempts for an
+already-claimed role will result in an error response.
+
+2.5.2.2. SMSC_RH_SERVICE_STATE
+
+The service state of a given RH may be up or down.  If the RH process is running
+but unable to perform its job (e.g., the upstream peer connection is down), its
+service state is down; in order for an RH to receive requests for processing
+from themwi-smsc-core, it needs to not only register for its role, but also
+declare itself to be in "service up" state.  The present exchange makes the
+declaration of service state being up or down.
+
+2.5.3. Exchanges with the IMSI resolver RH
+
+SMSC_MT_FIND_IMSI: request direction is from themwi-smsc-core to the registered
+IMSI resolver RH.  The request message carries an MSISDN; the matching response
+carries the corresponding IMSI or an error.
+
+2.5.4. Exchanges with the GSM MT delivery RH
+
+2.5.4.1. SMSC_MT_TRANSFER
+
+Request direction is from themwi-smsc-core to the registered GSM MT delivery RH.
+This exchange transfers a given SM (intended for GSM MT delivery) into temporary
+custody of themwi-smsc-gsmif process, which is the RH for this role.
+themwi-smsc-gsmif retains custody of this SM, and themwi-smsc-core regards this
+SM as being in the custody of themwi-smsc-gsmif, until one of the following two
+outcomes:
+
+a) The SM is discharged: delivered, canceled or times out as determined by
+   themwi-smsc-gsmif, with an attendant SMSC_MT_DISCHARGE exchange;
+
+b) The service goes down (socket client disconnects or declares itself down via
+   SMSC_RH_SERVICE_STATE).  In this case themwi-smsc-core retakes custody of
+   all still-active SMs that were previously handed over to themwi-smsc-gsmif
+   via SMSC_MT_TRANSFER.
+
+2.5.4.2. SMSC_MT_CANCEL
+
+Request direction is from themwi-smsc-core to the registered GSM MT delivery RH,
+which is themwi-smsc-gsmif.  themwi-smsc-core issues this request toward
+themwi-smsc-gsmif whenever it receives SMSC_REQ_CANCEL for an SM that has been
+handed over to themwi-smsc-gsmif via SMSC_MT_TRANSFER.
+
+2.5.4.3. SMSC_MT_DISCHARGE
+
+themwi-smsc-gsmif sends this request to themwi-smsc-core to indicate the
+discharge (successful delivery, cancellation or validity period expiry) of an
+SM that has previously been transferred via SMSC_MT_TRANSFER.
+
+2.5.5. Exchanges with peer delivery role handlers
+
+SMSC_DELIVER_TO_PEER: request direction is from themwi-smsc-core to the
+registered RH for this peer.  The request carries an SM (struct sm_record);
+the response carries success or failure.
+
 3. SMS communication via direct shell access
 
 To be filled.