docs(architecture): document the local session geo lookup subsystem

Sync the architecture reference with the new opt-in, local-only session geo
lookup, in both the Markdown source and the rendered HTML:
- Authentication & Authorization: new entry describing GeoLocator, the
  Auth.geoLookupEnabled gate (default off), null-safe failure behavior, the
  ci4ms:geoip-update command, and DB-IP CC BY 4.0 attribution.
- CLI & Automation: new ci4ms:geoip-update table row.

Author: bertugfahriozer

docs/architecture.html

@@ -402,6 +402,21 @@ <h2>Authentication &amp; Authorization</h2>
             <code>Modules\Backend\Filters\BackendLogFilter</code> (IP, user
             agent, action, module).
           </li>
+          <li>
+            <strong>Session geo lookup (local, opt-in):</strong>
+            <code>Modules\Auth\Models\UserSessionModel::recordLogin()</code>
+            can enrich a session with approximate city/region/country, resolved
+            entirely against a <strong>local</strong> DB-IP City Lite database
+            (MMDB) via <code>Modules\Auth\Libraries\GeoLocator</code>
+            (<code>maxmind-db/reader</code>) — the IP address never leaves the
+            server. Gated by the <code>Auth.geoLookupEnabled</code> setting
+            (default <code>false</code>) and returns <code>null</code> on any
+            failure, so it never breaks login. The database is
+            downloaded/refreshed with <code>php spark ci4ms:geoip-update</code>
+            (atomic swap, <code>flock</code>-guarded, monthly cron) and lives
+            outside the web root under <code>writable/geoip/</code>. DB-IP data
+            is CC BY 4.0 and requires attribution.
+          </li>
         </ul>
       </section>
 
@@ -671,6 +686,13 @@ <h2>CLI &amp; Automation</h2>
               <td><code>php spark cache:clear</code></td>
               <td>Clear all application caches</td>
             </tr>
+            <tr>
+              <td><code>php spark ci4ms:geoip-update</code></td>
+              <td>
+                Download/refresh the local DB-IP City Lite database for session
+                geo lookup (monthly cron)
+              </td>
+            </tr>
           </tbody>
         </table>
         <p>

docs/architecture.md

@@ -40,6 +40,7 @@ Authentication is powered by **CodeIgniter Shield** (`codeigniter4/shield`):
   - `Modules\Methods` manages these tables and can auto-scan routes to populate permissions.
 - Backend activity is logged via `Modules\Backend\Filters\BackendLogFilter` (IP, user agent, action, module) for audit trail purposes.
 - Inactive administrative sessions are secured via `Modules\Auth\Controllers\LockController` which locks the session and sets a `locked_at` timestamp.
+- **Session geo lookup (local, opt-in):** `Modules\Auth\Models\UserSessionModel::recordLogin()` can enrich a session with approximate city/region/country. Lookups run entirely against a **local** DB-IP City Lite database (MMDB) via `Modules\Auth\Libraries\GeoLocator` (`maxmind-db/reader`) — the IP address never leaves the server. The feature is gated by the `Auth.geoLookupEnabled` setting (default `false`) and returns `null` on any failure, so it never breaks login. The database is downloaded/refreshed with `php spark ci4ms:geoip-update` (atomic swap, `flock`-guarded, monthly cron); the file lives outside the web root under `writable/geoip/`. DB-IP data is CC BY 4.0 and requires attribution.
 - Application-wide rate limiting is enforced via `ThrottleFilter` and `Modules\Backend\Filters\BackendThrottleFilter` (HTTP 429).
 - Maintenance mode is gracefully handled by `Modules\Backend\Filters\BackendMaintenanceFilter` and the `BackendMaintenance` library (HTTP 503).
 
@@ -135,6 +136,7 @@ Blog and Pages modules store SEO data as JSON (`coverImage`, `description`, `key
 | `php spark create:route` | Rebuild `app/Config/Routes.php` from the template |
 | `php spark migrate --all` | Run all pending migrations |
 | `php spark cache:clear` | Clear all application caches |
+| `php spark ci4ms:geoip-update` | Download/refresh the local DB-IP City Lite database for session geo lookup (monthly cron) |
 
 `Modules\Methods::moduleScan()` inspects the router to align routes with permission records.