# Getting started

Sign in to the hosted app or run it locally, then take a guided tour of the core workflow.

## Open the app

LookAlike is hosted at [app.lookalikeiq.com](https://app.lookalikeiq.com). Access is invite-only: request a magic link with the email address that was invited, open the link, and you land in the workspace for the retail client you have been granted access to. You can register a passkey afterwards from the **/account** page so later sign-ins do not need email.

The rest of this page tours the interface. Everything in it applies to the hosted app.

## Run it locally (developers)

The repository also runs front-end-only, without accounts, against the committed data copy:

1.  **Enter the web directory and install dependencies:**
    
    ```
    cd webpnpm install
    ```
    
2.  **Start the development server:**
    
    ```
    pnpm dev
    ```
    
3.  **Open the app in your browser:** Navigate to `http://localhost:5180`. You will see the main interface loading 83,000 U.S. census tracts.
    

A compatibility copy of the national data is committed at `web/public/data/`, so the local app runs immediately. That copy is for development and tests only; the hosted app reads published releases from R2. See `web/public/data/RELEASE.md` for what it contains, and [Rebuilding the data](https://docs.lookalikeiq.com/operate/rebuild-data/) for how releases are built.

## Tour the interface

### 1\. Pick a brand

The top of the left panel holds a searchable brand picker: a single dropdown that lists the 11 built-in brands, any brands you have saved, and an action row to add a new one. The built-in brands, each with different store counts, are:

-   **Trader Joe’s** (603 stores)
-   **Whole Foods Market** (525 stores)
-   **Sprouts Farmers Market** (448 stores)
-   **Chipotle Mexican Grill** (3,068 stores)
-   **Starbucks** (10,984 stores)
-   **Costco Wholesale** (1,225 stores)
-   **Dollar General** (11,136 stores)
-   **Tractor Supply Co.** (1,554 stores)
-   **Sweetgreen** (167 stores)
-   **H Mart** (96 stores)
-   **Cracker Barrel** (639 stores)

These counts are the mapped OpenStreetMap store points after a 150 m dedup and a 1 km continental-US containment step. You can also add any other United States chain from OpenStreetMap by name (see step 7).

Open the picker and choose a brand to begin. You can type in the search box to filter the list, or move through it with the arrow keys and press Enter to select; pressing Escape or clicking outside closes it. Switching among the built-in brands is instant, because each brand’s national scores are computed once and then kept in memory, so returning to a brand you have already viewed does not re-score the country. Below the picker, you will see:

-   The number of store neighborhoods used to build that brand’s archetype (one observation per tract, so a Costco gas pump and warehouse do not double-count).
-   **Archetype coherence**: a validation badge showing whether the brand occupies a consistent kind of place. Distinctive chains like Sweetgreen (≈90th percentile) and Whole Foods (≈83rd) rank higher because they cluster geographically; ubiquitous ones like Starbucks rank lower (≈57th) because they operate almost everywhere.

Resemblance to a brand’s archetype does NOT predict revenue, foot traffic, or whether a store would succeed. It only measures observable neighborhood similarity. See [The method](https://docs.lookalikeiq.com/method/how-it-works/) for details on the weak correlation between location resemblance and actual sales.

### 2\. Read the colored map

The national choropleth shows census tracts colored by resemblance to the brand’s archetype:

-   **Brighter colors** = higher similarity percentile (closer to 100th).
-   **Dark gray areas** = median tracts and weaker matches — left uncolored intentionally so you focus on _where to look_.
-   **White dots ringed in the brand color** (if “Show stores” is toggled on) = existing store locations.

Each neighborhood is a **census tract** — a statistical geography unit of roughly 4,000 people. The color is computed live in the browser as you adjust filters and weights.

### 3\. Click a neighborhood

Click any tract on the map or pick one from the ranked candidate list (right panel). The detail panel opens with:

-   **Similarity percentile**: a within-brand rank (0–100, where ~100 is the closest match nationally for that brand).
-   **Absolute-fit band**: a Strong / Moderate / Weak chip measured against the brand’s own store neighborhoods — comparable across brands, unlike the percentile.
-   **Low ACS reliability badge** (when applicable): flags a small-population tract or a large income margin of error.
-   **Radar fingerprint**: a visual comparison of the tract vs. the brand archetype across all six feature themes.
-   **Closest features** (or “Why it matches”): the features where the tract most closely resembles the archetype.
-   **Where it differs**: features furthest from the brand’s typical profile, with the brand’s average values.
-   **Full feature table**: all 21 features grouped by theme, with the tract’s actual values and the brand’s averages.
-   **Plain-English assessment**: a summary of fit.
-   **Robustness badge**: whether the high rank is robust or hinges on one theme.
-   **Nearby chains**: which of the tracked brands have a store within 6 km.
-   **Existing store info**: whether the tract already has a brand location and distance to the nearest one.
-   **“Not a fit?” control**: flag a wrong lookalike to hide it and learn what your rejected tracts share.

### 4\. Try the filters

On the left:

-   **Open markets only**: hide tracts that already contain a store.
-   **Min. similarity**: show only tracts above a percentile threshold.
-   **State**: filter to a single state (the list re-pools and ranks within the state).
-   **Competition**: keep tracts at least a chosen distance from your own stores, or with no tracked competitor within 6 km.
-   **Focus a metro**: zoom to one of 383 Census metro areas and rank only that metro’s neighborhoods, or open **Top metros** to rank the metros against each other by open, high-rank neighborhood count.

All filters apply live. The map and candidate list re-rank instantly.

### 5\. Tune the factor weights (optional)

Expand **“Tuning the factors”** to reweight the six feature themes:

-   Income, wealth & housing cost
-   Education
-   Density & transportation
-   Age & household type
-   Race & ethnicity
-   Retail & dining context

Each slider ranges from 0 (off) to 2× (doubled). Presets include Balanced, Affluence-led, Urbanism-led, and Community-led. Each group also opens an **Advanced** per-feature layer for weighting a single feature within a group. The map and rankings re-score live as you drag.

Weights are your scenario assumptions, not learned or causal importance. They make explicit what variables matter most to _your_ definition of a good match — and how sensitive the results are to that choice.

### 6\. Compare two brands (optional)

Select a second brand from the **”⇄ Compare vs”** dropdown. The map shifts to a **diverging lean map**:

-   **Color hue** shows which brand a neighborhood leans toward, using a fixed, colorblind-safe blue-and-orange pair (blue for A, orange for B).
-   **Brightness** shows how strongly it resembles either.
-   The candidate list shows three rankings: Leans A / Resembles both / Leans B.

Click a tract to see side-by-side percentiles for both brands and which features drive the lean.

You can also compare a custom upload against a built-in brand; the compare view then uses your upload’s plain resemblance percentiles.

### 7\. Add your own brand (optional)

Open the brand picker and choose the **“Add a brand (CSV or OpenStreetMap)…”** row to bring in your own CSV of store locations:

-   CSV columns: `lat`, `lon` (required); `revenue` or `sales` or `value` (optional); `status` (optional, values like `closed`, `failed`, `low`).
-   Authenticated uploads are saved as private, versioned client datasets; quick unauthenticated Vite development remains browser-only.
-   National scoring is computed client-side using the same scoring logic as the pipeline.

Once added, the tool ranks all 83,000 tracts by resemblance to your winner stores, optionally weighted by performance and penalized by failure-store similarity. In the authenticated product, reopen a published version from **Saved customer datasets** in the upload dialog.

If you don’t have a store list but want a chain that isn’t built in, use the same **“Add a brand (CSV or OpenStreetMap)…”** row and switch to the OpenStreetMap tab: type the chain’s name and the tool fetches its United States store points live from OpenStreetMap and scores them the same way (subject to how completely that chain is mapped). A fetched brand is saved in your browser just like a CSV upload. See [custom upload](https://docs.lookalikeiq.com/guides/custom-upload/#add-a-brand-from-openstreetmap).

### 8\. Star and export neighborhoods

Click the star icon on any neighborhood to add it to your shortlist. From the **Shortlist** panel (right side), you can:

-   **Annotate** each neighborhood with notes.
-   **Export a PDF report** (per-tract stat tables vs. brand average, drivers, and a disclaimer).
-   **Export a CSV** (all saved neighborhoods and features, plus the fit band and reliability flag, formula-injection-safe). The separate ranked-list CSV export additionally carries the competition columns.

To keep several analyses side by side, save the current view (brand, weights, compare, metro, filters) as a **named scenario** and switch between them later. Use the **Copy link** button to put the current view on your clipboard to share.

## Next steps

-   **Understand the method**: Read [How it works](https://docs.lookalikeiq.com/method/how-it-works/) for a detailed explanation of the scoring, feature set, and validation.
-   **Data sources**: See [Data sources](https://docs.lookalikeiq.com/method/data-sources/) for URLs, licenses, and coverage caveats.
-   **Custom uploads**: [Upload your own stores](https://docs.lookalikeiq.com/guides/custom-upload/) for a fuller walkthrough with performance weighting and failure avoidance.
-   **FAQ**: Check [Frequently asked questions](https://docs.lookalikeiq.com/operate/faq/) for common questions about predictions, limitations, and data freshness.

Bookmark or share URLs: brand, filters, factor weights, compare brand, and selected tract are encoded in the URL hash. Send a link to a colleague to show them exactly what you are looking at.

Canonical URL: https://docs.lookalikeiq.com/guides/getting-started/