--- a/doc/Arch-design	Wed Dec 20 03:50:06 2023 +0000
+++ b/doc/Arch-design	Wed Dec 20 09:27:05 2023 +0000
@@ -332,3 +332,137 @@
   objective, themwi-smsc-dump must make it easy to look at only technically
   necessary information, without throwing unnecessary private info into the
   operator's eyeballs.
+
+2.3. themwi-smsc-core daemon operation
+
+The core daemon (long-lived process) of ThemWi-SMSC is named themwi-smsc-core.
+Aside from themwi-smsc-dump read-only tool, themwi-smsc-core will be the only
+software component that accesses pms.bin directly - all other components of
+ThemWi-SMSC will connect to a UNIX domain local socket provided by
+themwi-smsc-core.  In more detail, the core daemon will perform the following
+functions:
+
+* Read the potentially-active (not marked as historical-only) tail portion of
+  PMS on startup, catch all still-active SMs and hold them in RAM-based data
+  structures;
+
+* Listen on a UNIX domain local socket of type SOCK_SEQPACKET, meaning
+  connection- and message-oriented;
+
+* Accept message submission (or entry) commands from other ThemWi-SMSC
+  components connecting to this socket;
+
+* Allow those socket-connecting SMSC components to register themselves as
+  performing special roles (GSM network interface, IMSI resolver, uplink and
+  downlink SMPP connection handlers), and send notification packets to those
+  role-handlers when an active SM needs that type of processing;
+
+* When these just-described role-handlers respond with success or failure of
+  message handling, discharge the SM into historical state (either delivered or
+  failed), or in one special case (successful completion of MSISDN-to-IMSI
+  lookup) promote the SM from need-IMSI-lookup state into GSM-MT-delivery state.
+
+The key feature of themwi-smsc-core daemon is that it can stay up and running
+even when all other ThemWi-SMSC daemon processes are shut down.  It won't be
+particularly useful in this state, and won't be able to bring any outstanding
+active SMs any closer toward delivery, but the key point is that dependency
+graph arrows between sw components point in only one direction.
+
+2.4. Message entry paths
+
+Every new SM enters the SMSC by way of one of our sw components making a local
+socket connection to themwi-smsc-core and sending it a "submit new message"
+command packet.  The following ThemWi-SMSC sw components will be able to enter
+new SMs in this manner:
+
+* A special command line utility named themwi-smsc-submit will perform just
+  this function and nothing else;
+
+* GSM network interface daemon themwi-smsc-gsmif will submit SMs received from
+  GSM subscribers as MO messages;
+
+* Upstream SMPP link handler themwi-smsc-uplink will submit SMs received from
+  the upstream connection, i.e., from the outside world;
+
+* Downstream SMPP link handlers will submit SMs received from downstream peers.
+
+Most of the common processing functions, such routing and validation steps,
+will be performed by themwi-smsc-core.  Once all admission-time checks pass,
+the new SM will be written into PMS, and if the destination is anything other
+than write-into-PMS-only, the new active SM will also be added to the core
+daemon's in-RAM data structures.  Further delivery steps will happen if and when
+the appropriate role-handler connects to themwi-smsc-core and accepts messages
+for processing.
+
+2.4.1. Routing of Short Messages
+ 
+For every incoming SM, themwi-smsc-core will apply routing based on the
+destination address in addr_to_orig member of the submitted struct sm_record.
+Referring to the general principles of section 1.1, this step is very specific
+to the numbering plan (NANP) for which ThemWi-SMSC is designed.  The following
+routing rules will be applied:
+
+* If the destination number is international (TON=1) and the country code is
+  anything other than +1, the destination is set to SME_CLASS_UPSTREAM.
+
+* If the destination number is NANP, entered in international TON=1 format or
+  in one of local-culture formats (10-digit NPANXXXXXX or 11-digit 1NPANXXXXXX,
+  TON=0), NANP validation rules are applied and outright-invalid numbers are
+  rejected.  The validated NANP number is looked up in themwi-nanp database of
+  locally owned phone numbers; if the number is locally owned, the destination
+  is either SME_CLASS_LOCAL or SME_CLASS_GSM, depending on how the number is
+  assigned, or the message may be rejected if the locally-owned number is of a
+  type that cannot receive SMS.  If there is no hit in the database of locally
+  owned numbers, another number database gets a lookup, the one for numbers of
+  downstream peers - a hit in that database will set the destination to
+  SME_CLASS_DOWNSTREAM.  Finally, if the NANP destination number doesn't hit
+  anywhere, the destination is SME_CLASS_UPSTREAM.
+
+* If the destination number is a USA SMS short code of form NXXXX or NXXXXX,
+  the destination is SME_CLASS_UPSTREAM.
+
+* In the case of locally originated SMs only (coming from GSM MO or from
+  themwi-smsc-submit command line utility), special 4-digit numbers may be
+  defined in the number database of themwi-nanp that are meaningful only
+  locally.  If one of those numbers matches, the destination is SME_CLASS_LOCAL
+  or SME_CLASS_GSM according to the exact number type.
+
+* If none of the above conditions match, the message is rejected as unroutable.
+
+What is the difference between SME_CLASS_LOCAL and SME_CLASS_GSM destinations?
+Answer: SME_CLASS_LOCAL means that writing the SM into PMS constitutes final
+delivery, and nothing more needs to be done.  OTOH, destination of SME_CLASS_GSM
+means that an MSISDN-to-IMSI lookup needs to be performed, followed by GSM MT
+delivery.
+
+There is one additional routing mode that is available only via
+themwi-smsc-submit, or perhaps future specialized network sw components that
+incorporate the same function: if a locally generated MT message needs to be
+sent to a local GSM MS addressed by IMSI, with no destination phone number
+existing at all, themwi-smsc-submit can instruct themwi-smsc-core to skip the
+routing step, with the destination preset to SME_CLASS_GSM and dest_imsi
+prefilled.
+
+2.4.2. Permission to send to the uplink
+
+To be described.
+
+2.4.3. PID and DCS constraints
+
+To be described.
+
+2.4.4. Validity period and expiry time
+
+To be described.
+
+3. SMS communication via direct shell access
+
+To be filled.
+
+4. Interface to local Osmocom GSM network
+
+GSUP and separate MSISDN-to-IMSI lookup, to be described.
+
+5. SMPP connection handlers and outside-world SM exchange
+
+To be filled.