--- a/doc/Arch-design	Fri Dec 22 09:29:21 2023 +0000
+++ b/doc/Arch-design	Sat Dec 23 00:54:24 2023 +0000
@@ -666,6 +666,93 @@
 registered RH for this peer.  The request carries an SM (struct sm_record);
 the response carries success or failure.
 
+2.6. Queueing architecture of ThemWi-SMSC
+
+2.6.1. Queueing in themwi-smsc-core
+
+While every SM, active or historical, is stored in PMS, only active ones are
+also held in RAM-based queues by themwi-smsc-core.  There are many queues,
+organized by SM destination:
+
+2.6.1.1. Queues of SMs waiting to be delivered to SMPP peers
+
+There will be a separate queue for each upstream or downstream peer, or more
+precisely, one queue for the single upstream peer and one for each downstream
+peer.  Each peer is another SMSC somewhere else in the world, and each queue
+holds messages which need to be transferred to that other SMSC.
+
+When the process that serves as the RH for delivery to a given peer is
+connected, the corresponding queue will be drained by themwi-smsc-core
+transferring the SM at the head of the queue to the RH via SMSC_DELIVER_TO_PEER
+request.  Only one such request will be outstanding at any given time to a
+single RH; once the RH responds to this SMSC_DELIVER_TO_PEER request, completing
+that elementary exchange, themwi-smsc-core will discharge the SM at the head
+and proceed to the next one in the queue, doing another SMSC_DELIVER_TO_PEER
+exchange on it, and so forth.
+
+2.6.1.2. Queues of SMs waiting for MSISDN-to-IMSI resolution
+
+There will be a hierarchical structure of queues for this function:
+
+* The top-level MSISDN-to-IMSI lookup queue will have one entry for each
+  _different_ target MSISDN in need of resolution;
+
+* Under each unique target MSISDN entry in the just-described queue, there will
+  be a subqueue of individual SMs addressed to that MSISDN.
+
+When the IMSI resolver RH is connected, themwi-smsc-core will take the MSISDN
+at the head of the to-be-resolved queue and send it to the RH in a
+SMSC_MT_FIND_IMSI request.  When the RH responds, all SMs that are queued under
+that MSISDN get their dest_imsi filled in, and are moved to the next queue
+described in section 2.6.1.4.
+
+2.6.1.3. Cache of recently completed MSISDN-to-IMSI lookups
+
+To avoid many repeated queries resolving the same MSISDN to IMSI rapidly back
+to back, particularly in the case of additional SMs to the same recipient (e.g.,
+segments of a long message) arriving just after the initial MSISDN-to-IMSI
+lookup completed and removed the target MSISDN from the queue, there will a
+cache of recently resolved MSISDN-to-IMSI mappings.  The time duration of how
+long a cached lookup result will be considered valid will be configurable - it
+is a trade-off between efficiency under high message load vs allowing
+administrative changes in the mapping of subscribers (association between phone
+numbers and physically issued SIM cards) and letting them take effect reasonably
+quickly.
+
+2.6.1.4. Queues of SMs waiting for final GSM MT delivery
+
+There will be two queues for messages in this state:
+
+* The first queue holds MT-intended SMs which are still officially in the
+  custody of themwi-smsc-core;
+
+* The second queue holds MT SMs that have been transferred into the custody of
+  themwi-smsc-gsmif via SMSC_MT_TRANSFER exchange, see section 2.5.4.1.
+
+themwi-smsc-core will actively manage the first queue, seeking to transfer each
+SM into the custody of themwi-smsc-gsmif and move it to the second queue.  Once
+a message has been placed on the second queue, themwi-smsc-core no longer
+actively manages it - the SM is now a responsiblity of themwi-smsc-gsmif.
+In good system operation, they get discharged when themwi-smsc-gsmif performs
+an SMSC_MT_DISCHARGE exchange.  However, if themwi-smsc-gsmif goes away, all SMs
+on the second queue will be moved back to the first queue.
+
+2.6.2. Queueing in themwi-smsc-gsmif
+
+themwi-smsc-gsmif is the sw component responsible for accepting MO SMs from GSM
+subscribers and for delivering MT SMs to them.  The former task is very simple
+(each received SMS-SUBMIT from GSM side turns into SMSC_REQ_SUBMIT), but the
+latter function (MT delivery) is where the real work lies.  Our design approach
+is that themwi-smsc-core will transfer all destined-for-MT SMs into the custody
+of themwi-smsc-gsmif as quickly as possible (without waiting for each SM to be
+delivered in turn, unlike transfers to peer SMSCs via SMPP), and then
+themwi-smsc-gsmif is responsible for the actual queueing strategy and scheduling
+of GSM MT delivery attempts.
+
+The details of queue structure and delivery attempt scheduling strategy in
+themwi-smsc-gsmif remain to be determined; the current plan is to implement
+other parts of ThemWi-SMSC first.
+
 3. SMS communication via direct shell access
 
 To be filled.