--- a/doc/Arch-design	Sat Dec 23 00:54:24 2023 +0000
+++ b/doc/Arch-design	Sat Dec 23 04:09:20 2023 +0000
@@ -312,15 +312,7 @@
 
 * One radical idea is to grant limited access (by way of a very strict wrapper)
   to themwi-smsc-dump to unprivileged users of the network served by the SMSC,
-  i.e., to end users.  The idea is that each individual user should be able to
-  give their ssh public key to the administrator of the community network, and
-  then ssh into a special restricted service on the SMSC that does not grant
-  any system shell access, but allows them to access services under their own
-  phone number.  Such an empowered end user should be able to submit SMS from
-  their own phone number using the power of a full-size computer (as opposed to
-  very painful text entry on the numeric keypad of a traditional GSM phone),
-  and to see a full log of all messages received by or sent from their own
-  phone number.
+  i.e., to end users.  Please see section 3.2 for the details.
 
 * By the nature of her job, the administrator of the SMSC (and of the community
   GSM network to which this SMSC belongs) necessarily has access to every
@@ -755,7 +747,82 @@
 
 3. SMS communication via direct shell access
 
-To be filled.
+In the context of Themyscira Wireless, local users of the SMSC are human
+members of our local community who have mobile telephone numbers (MTNs) on
+Themyscira Wireless network.  The conventional way to access Short Message
+Service is via a GSM phone handset with a Themyscira SIM card: send outgoing
+messages as MO and receive incoming ones as MT.  However, we (the Presiding
+Sisterhood of Themyscira) think outside the box, and we believe in maximal user
+empowerment - hence we aim to provide a second way for any of our users to
+access SMS at their personal MTN, via a novel ssh-based command line mechanism.
+
+The idea is that each individual user should be able to give their ssh public
+key to the administrator of the community network, and then ssh into a special
+restricted service on the SMSC that does not grant any system shell access, but
+allows them to access services under their own phone number.  Such an empowered
+end user should be able to submit SMS from their own phone number using the
+power of a full-size computer (as opposed to very painful text entry on the
+numeric keypad of a traditional GSM phone), and to see a full log of all
+messages received by or sent from their own phone number.
+
+Aside from allowing outgoing SMS to be composed on a real computer in vi instead
+of phone keypad text entry, ssh-based access to the SMSC works over the Internet
+and is thus available from everywhere in the world, far outside the coverage
+area of the local GSM network.  Enabling Themyscira citizens to send SMS from
+their own "home" number and see texts arriving at that same number while far
+away from home GSM service is expected to be a highly empowering feature.
+
+3.1. themwi-smsc-submit command line utility
+
+This shell utility takes two mandatory command line arguments (source and
+destination phone numbers) and reads SM body text from stdin.  The input
+language expected on stdin will be the same as output from sms-encode-text
+utility, described here:
+
+https://www.freecalypso.org/hg/sms-coding-utils/file/tip/doc/Tool-workflow
+
+themwi-smsc-submit will construct a new SM in the form of struct sm_record and
+inject it into the SMSC with SMSC_REQ_SUBMIT.  themwi-smsc-core needs to be
+running, but no other component daemons are needed.
+
+This utility is envisioned as having multiple uses:
+
+* During SMSC development, it is the easiest way to generate messages.
+
+* For end user access to the SMSC (the main topic of this chapter), there will
+  a wrapper that allows users to enter arbitrary destination number and message
+  body input, but the source phone number will be fixed to that of the
+  subscriber.
+
+* All "big" MNOs have "special" auto-generated SMS they send out for customer
+  notifications and whatnot, with message source address set to some special
+  number or even alphanumeric (TON=5), and they can also have special encodings
+  performing functions such as SIM OTA programming.  themwi-smsc-submit is one
+  way to generate such SMs; the other option is to have custom processes for
+  other MNO functions connect directly to themwi-smsc-core socket interface,
+  but in simpler and more casual environments the command line utility is
+  expected to be sufficient.
+
+3.2. Unprivileged user access to themwi-smsc-dump
+
+The principal operation of themwi-smsc-dump is described in section 2.2.3.
+When accessed directly, without going through restrictive wrappers, this tool
+has the power of reading every message that ever went through the local SMSC,
+going back to the beginning of PMS archive - such unrestricted access should be
+given only to trusted administrators.  However, themwi-smsc-dump will also have
+a lot of command line options that restrict what it displays, including an
+option to show only messages whose source or destination matches a certain phone
+number.  A restrictive wrapper that invokes themwi-smsc-dump with this specific
+number option, and strictly preens all other options, can be made available to
+unprivileged users who wish to use ssh access to read their SMS.
+
+If someone receives SMS at their phone number while away from ThemWi GSM
+coverage, the received SM will remain in the SMSC in the active state -
+themwi-smsc-gsmif will be retrying delivery attempts to the GSM MS.  If the
+human owner of that phone number uses ssh access to read their SMS while in
+this state, they will see the received message in the active state; if they get
+back home into coverage zone before the received SM expires, they will also
+receive the same SM on their GSM phone.
 
 4. Interface to local Osmocom GSM network