add comment and update README

spotlight-client/README.md

@@ -10,6 +10,8 @@ The site consumes views of aggregate population data produced by the Recidiviz d
 
 While Spotlight is developed and deployed as a single multi-tenant website, it is primarily consumed as separate single-tenant experiences, under `.gov` subdomains owned by our state partners (e.g. [dashboard.docr.nd.gov](https://dashboard.docr.nd.gov)). To keep our infrastructure simple, this "tenant lock" is implemented in application logic within the data models, based on the URL hostname at runtime. This is why the multi-tenant "homepage" is so plain; it is really only used internally, for convenience, in development and staging environments.
 
+We also lock the staging environment to a single tenant depending on how the logged-in user is configured. In the staging environment, a user logs in to view the site, and if their Auth0 account has a `state_code` set in their `app_metadata`, then they will be locked-in to the tenant that correspons with that `state_code`. This is so we can share a fully-functional but private version of the app with contacts of that associated agency, without exposing data to state actors that do not have permission to view other states’ data.
+
 ### Configuration and content
 
 At its core this application is driven by a set of configuration objects, which are JavaScript objects that determine which states (or "Tenants") are displayed; which Narratives and Metrics will appear for each Tenant and what copy will appear on each of those pages (all of which is collectively referred to here as "Content"); and various other settings that can be changed per Tenant.

spotlight-client/src/DataStore/TenantStore.ts

@@ -56,6 +56,13 @@ export default class TenantStore {
     }
   }
 
+  /**
+   * Whether or not the app is locked to a single state depends on the following factors:
+   * - If the app is deployed on staging, and `state_code` exists in the user account's `app_metadata`, the app should be locked to that state code.
+   *   - If the state_code doesn't exist on their account, the app is not locked and the user can see all states.
+   * - If the app is deployed to production, authentication is turned off, and the app should be locked to the domain of the state that it's deployed on.
+   * -
+   */
   get locked(): boolean {
     return !!this.rootStore.userStore.stateCode || !!getTenantFromDomain();
   }