--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/NANP-specifics	Mon Nov 13 18:20:57 2023 -0800
@@ -0,0 +1,165 @@
+North American Numbering Plan (NANP) specifics in ThemWi system sw
+==================================================================
+
+Themyscira Wireless system software, as currently written, is strongly tied to
+NANP.  More precisely, it thoroughly assumes that all local phone numbers are
+in +1 country code and follow NANP rules, and that all E.164 telephone numbers
+in country codes other than +1 are foreign - numbers which we can call and
+receive calls from, but which can never be local to us.
+
+Why does our software need to have these assumptions baked into it, why can't
+it be country-agnostic?  The present article answers this question, and this
+long answer needs to be thoroughly understood before there can be any meaningful
+discussion of how the software could possibly be adapted to other countries and
+their respective telephone numbering plans.
+
+In principle, there exists a standardized dialing format on all GSM phones that
+remains the same no matter which country you happen to be in.  If you always
+enter phone numbers (dialing, SMS manual entry, phone book entries) in full
+international format beginning with the '+' symbol (press and hold the '0'
+button before the number in most phone UIs), the phone handset firmware will
+capture the number with TON=1, NPI=1 attributes (signifying international number
+format in GSM call control and SMS protocols) and transmit it as such to the
+GSM network.  Every properly designed GSM network, upon seeing a number with
+these TON=1, NPI=1 attributes, must address the call or message to the country
+indicated by the country code at the beginning of the full E.164 number, whether
+that country is your local one or some other.  Thus if everyone were to always
+use only full E.164 numbers in full international format, network software could
+hypothetically be written in a country-agnostic way, treating full E.164 phone
+numbers as opaque strings without parsing.  However, there are two practical
+problems with such country-agnostic approach:
+
+1) Most human users of mobile phones dial local phone numbers (within their own
+   country) in a way that follows local dialing conventions, rather than in
+   international format beginning with '+' and their own country code.  For
+   example, in USA a given 10-digit NANP phone number can be dialed as just the
+   10 digits NPANXXXXXX, as 11-digit 1NPANXXXXXX, or as full international
+   +1NPANXXXXXX - and a proper cellphone network MUST accept all 3 formats as
+   equivalent.
+
+2) As explained further in this article, a network implementation must be able
+   to look at a telephone number and immediately tell if that number is locally
+   owned ("one of ours") or belongs somewhere outside of the local GSM network.
+   Practical implementation of this distinction requires a database of locally
+   owned phone numbers, and the implementation of that database in turn becomes
+   much easier when the local numbering plan is known and fixed.
+
+Supported dialing formats in ThemWi
+===================================
+
+When themwi-mncc processes a mobile-originated (MO) call from a GSM subscriber,
+it supports dialing the following classes of numbers:
+
+* NANP numbers in any of the 3 standard dialing formats;
+
+* International numbers in any country - an international number beginning
+  with +1 is enforced to be valid NANP, but E.164 numbers in all other country
+  codes are accepted as-is;
+
+* Local 4-digit numbers described in (to-be-written) Local-short-numbers
+  article;
+
+* Whatever special numbers are configured in themwi-sip-out, such as 511 and
+  911.
+
+Only NANP numbers and specially configured 4-digit numbers (see
+Local-short-numbers) can be local - all E.164 numbers in non-NANP country codes
+are sent to the outbound call gateway, and all other unrecognized number formats
+are likewise sent to themwi-sip-out so that the latter process can catch and map
+special numbers like 511, 911 etc.
+
+If a dialed number is recognized as NANP, themwi-mncc looks in the database of
+locally owned numbers to see if the dialed number is one of ours - and the
+outcome of this look-up determines if the call is handled locally or sent to
+the outside world via themwi-sip-out.
+
+No 7-digit dialing support
+==========================
+
+In the olden days of land lines, most localities in USA supported 7-digit
+dialing: to call Jenny, you would merely dial her local 7-digit number 867-5309,
+without needing to dial the local area code; full 10-digit numbers (or 11 digits
+with leading '1') had to be dialed only when calling someone in a different
+area code from your own.  However, this 7-digit dialing has now been disabled
+even for land lines in most localities, including the locality where ThemWi
+currently operates: per official rules, 7-digit dialing gets disabled (full
+10-digit numbers become mandatory) whenever an area code overlay is implemented,
+such as overlay of 760 and 442 area codes in our locality.
+
+In the case of mobile phones, 7-digit dialing never made much sense to begin
+with: if you dial only 7 digits, should the implicit area code be taken from
+your own number, or should it be the area code of the locality you happen to be
+traveling through at the moment?  The latter option is impossible in the case
+of localities with two or more overlaid NPA codes, and it appears that official
+rules once again call for simply disabling 7-digit dialing.
+
+Based on these considerations, ThemWi system sw was written from the outset to
+not support 7-digit dialing - it is no longer relevant in the current state of
+telecom culture in USA.  We do, however. provide optional support for
+abbreviated 4-digit local numbers - see (to-be-written) Local-short-numbers
+article.
+
+Database of locally owned numbers
+=================================
+
+The telecom culture in USA features full number portability - end users can take
+their phone numbers with them anywhere, from one telecom provider to another,
+and with mobile phones and VoIP services, from one geographic locality to any
+other, making the entire country effectively "flat" for local/non-local
+distinction purposes.  Therefore, the set of phone numbers "owned" (or rented
+in reality) by a small network operator such as Themyscira Wireless does not
+constitute any kind of clean-cut digit range partition in the numbering plan -
+instead we can have a small set of locally owned numbers (say, on the order of
+5 to 20 individual numbers), and each of these locally owned numbers can fall
+anywhere in the whole nationwide 10-digit numbering plan.  So how can we tell,
+by looking at an arbitrary NANP number, whether it is "one of ours" or not?
+
+The implemented solution is an explicitly maintained database of locally owned
+phone numbers, described in detail in (to-be-written) Number-database article.
+The format of this database (the way numbers are entered, the way the input
+format is parsed, and the compiled binary format used for fast look-ups) is
+specific to NANP - only NANP numbers can be local in the present design.
+
+Porting to other national telephone numbering plans
+===================================================
+
+If someone wishes to port ThemWi system sw for use in other countries with
+respective local phone numbers, the following aspects will need to be changed:
+
+* Based on the structure of your country's national numbering plan, you will
+  need to come up with an appropriate local number database format for your
+  country, or if the range of numbers belonging to your GSM network forms a
+  clean-cut digit range partition, implement that scheme instead.
+
+* You will need to modify MO call handling to recognize your country code
+  (rather than +1) as the one calling for parsing and closer scrutiny of the
+  dialed number, determining if it is local or not.
+
+* Handling of non-international dialing formats (numbers dialed without '+')
+  will need to be changed to whatever is appropriate for your country's telecom
+  culture and customs.
+
+* Handle all secondary fallout (throughout the code base) from the previous
+  essential and necessary changes.
+
+Using fake NANP numbers
+=======================
+
+If someone outside of North America wishes to merely play with ThemWi system sw
+on a casual basis, without actually interconnecting to your non-USA PSTN with
+non-NANP real phone numbers, the easiest way to bring the software up is to use
+fake NANP numbers.  There are two types of guaranteed-fake (can't collide with
+real ones) phone numbers in NANP:
+
+1) NPA-555-01XX, where NPA is some real area code for some (any) actual locality
+   in USA and XX can be any two digits.  This number range is specifically set
+   aside for use in movies etc, with realistic USA settings - the area code can
+   be any real one, but 555-01XX numbers are reserved for fake use in every
+   area code.
+
+2) Fake area codes of form N9X (290-299, 390-399, ..., 990-999) are also good
+   for guaranteed-fake numbers as the middle digit of NPA is not allowed to be
+   '9' per official NANP rules.  This method allows large ranges of fake NANP
+   numbers.
+
+See Fake-NANP-numbers article (to be written) for more info.