# Entrance Lobby — Screen-to-Screen Workflow Spec

> Build spec for **slides 5 & 6** of [`EarthTeam_UX_Redesign.md`](EarthTeam_UX_Redesign.md): the Entrance Lobby, where each of its four tiles leads, and the two supporting sub-flows (project smart-import, onboarding revamp).
>
> Visual companions (hostable review site in [`lobby-workflow-site/`](lobby-workflow-site/)): [`index.html`](lobby-workflow-site/index.html) review hub · [`workflow.html`](lobby-workflow-site/workflow.html) interactive map (commentable) · [`walkthrough.html`](lobby-workflow-site/walkthrough.html) tap-through prototype · [`deck.html`](lobby-workflow-site/deck.html) slide viewer · [`lobby-workflow.drawio`](lobby-workflow.drawio) hand-editable diagram
>
> Status legend used throughout: 🟢 **exists** in ETP3-mobile · 🟡 **exists, needs modification** · 🔵 **new screen** · ⚪ **external / backend service**

---

## 1. Entry Flow — how users reach the Lobby

```
Login / Register → OTP ─┬─ not onboarded ──→ Onboarding (revamped, §6) ──┐
                        │                                                ▼
                        └─ onboarded ────────────────────────────→ 🔵 LOBBY (new)
                                                                       │
                                                     "Go to Home feed" skip link
                                                                       ▼
                                                                 🟢 Home feed
```

- The Lobby **replaces Home as the default post-login landing** (`app/index.tsx` currently redirects to `/(tabs)`; it would redirect to `/lobby`).
- **Skip affordance:** "Go to Home feed" text link under the tiles (slide 6 calls for it once a default hallway is set).
- **Open decision (slide 11):** show Lobby every session vs. only until the user sets a default hallway. Recommendation: *every session until the user taps "make this my default"* on a hallway — cheap to build, honors both.

### Navigation variants

| | Variant A — **primary for now** | Variant B — full PDF model (slide 9) |
|---|---|---|
| Bottom bar | **Unchanged**: Home · Map · **gAia (center)** · Wallet · Verify | Home · **LOBBY (center)** · Map · Wallet · Verify |
| Lobby reached via | Post-login landing + new **"Lobby" item in hamburger menu** (and/or tapping the EarthTeam logo) | Center nav slot, one tap from anywhere |
| gAia | Keeps its center tab | Moves inside Learn & Network hallways as a guide |
| Why | Zero nav-bar rework; ships with build step 1 (slide 11 sequences nav restructure **last**) | End-state once Lobby + hallways are stable |

---

## 2. LEARN 🔷 → dedicated Learn hub (two sections)

**Tap → 🔵 `/learn` (new dedicated page)** with two sections — *not* straight into gAia. (An earlier draft opened gAia directly; that's now section 2b inside the hub.)

### 2a. Learn how to use the app
Two explainer entries:
- **⭐ How do I earn Stars?** → 🔵 `/learn/earn-stars` — lists every way to earn: add a project, verify, invite protectors, engage (comment/share), host/attend events. CTAs deep-link to Add Project and Verify.
- **🎁 How do I use my Stars?** → 🔵 Stars explainer (tiers, convert, redeem) — shares the `/stars-explainer` screen also used by EARN (interim: `/ets-token`).

### 2b. Learn what's happening around the world
- **🌍 Ask gAia** → 🟡 `/(tabs)/ai-chat?preset=learn` — opens the chat mid-conversation with a preset user message and a Gaia response full of curated links:

| Link group | Links | Destination |
|---|---|---|
| **Explore by cause** | Wildlife Protection · Habitat Protection · Regenerative Agriculture | 🟢 `/listview` with the matching Project Type filter pre-applied |
| **Manuals & guides** | App manual / how-tos | ⚪ `https://app-wiki.earth-team.org` (existing Help wiki, in-app browser) |
| **CTOC portal** | Counter-Trafficking portal link(s) | ⚪ external browser |
| **Featured Projects** | 2–3 curated project links | 🟢 `/post/[id]` |

From there the conversation is live. Suggested-question chips switch to conservation-relevant prompts (slide 4): *"Show me projects near me," "How do I become a verifier?"*

**Build notes**
- `/learn` and `/learn/earn-stars` are simple static content screens.
- `ai-chat.tsx` reads **no route params today** — add `?preset=learn` handling that injects the canned exchange locally (no server round-trip; instant, deterministic, zero Gaia-API cost). Keep canned content in config/remote-config. Swap the hardcoded `SuggestedQuestions.tsx` chips for the conservation set.
- `/listview` needs to accept a Project Type filter param (it currently manages filters in local state only).

---

## 3. EARN 🟡→ Earn hallway (focused quick-actions screen)

**Tap → 🔵 `/earn` (new, lightweight)** — essentially the Home quick-actions section given its own focused room, answering one question: *"How do I earn Stars?"*

Screen contents, top to bottom:

1. **Two primary CTA cards** (the two direct ways to earn):
   - **"Earn by adding a project"** → 🟢 `/post/create` (with the two-option add flow, §5)
   - **"Earn by verifying"** → 🟢 `/(tabs)/verify` (Verification Dashboard — Available / Your Tasks)
2. **"How do Stars work?"** link → 🔵 Stars explainer: a short **infographic video** explaining how adding projects and verifying earn Stars, and what Stars are for. *Interim:* extend 🟡 `/ets-token` (the existing Star explainer page) with the video at top; *end-state:* dedicated `/stars-explainer` screen.
3. **"Other ways to earn Stars"** section (**replaces** the Featured Projects strip):
   - **Invite other planet protectors** (referral — new capability)
   - **Engage** — comment & share projects (links to existing project actions)
   - **Host or participate in EarthTeam events in your locality** (local events — new capability)

**Build notes**
- CTAs + explainer are pure composition of existing pieces. The "Other ways" items link to existing engage actions where they exist; referral and local-events are new and can ship incrementally.
- Video hosting: Bunny CDN is already used for post videos — reuse.
- Optional header: current Stars balance chip → 🟢 `/(tabs)/wallet`.

---

## 4. SHARE 🟩 → straight into Add Project (the form)

**Tap → 🟢 `/post/create` — direct, single tap.** SHARE lands on the **existing 6-step form** (Intro → Basic Data → Action → Outcome → Impact → Risks). That form gains one addition: a **"⚡ Speed up with AI" toggle at the top** — see the two-option flow in §5.

- **Onboarding gate:** `useRequireOnboarding()` applies — a non-onboarded user is routed to onboarding (revamped, §6) and returned.
- After publish → 🟢 `/post/[id]` (their new project) — with a "View in My Projects" affordance → 🟢 `/(tabs)/my-posts`.

---

## 5. Sub-flow: Add Project — two options (new AI path on the existing form)

Applies **wherever** Add Project is entered — Share tile, Earn hallway, Home quick action. The default is the existing form; AI is an opt-in accelerator, not a separate wizard.

```
/post/create opens  →  the existing 6-step form, with a "⚡ Speed up with AI" toggle at the top
   │
   ├─ OPTION 1 · Fill the form yourself  (toggle OFF — default)
   │     Intro → Basic Data → Action → Outcome → Impact → Risks
   │     Only step 1 required · Submit Now anytime → publish → /post/[id]
   │
   └─ OPTION 2 · ⚡ Speed up with AI  (toggle ON)
         panel reveals:  📄 Upload PDF / image   |   🔗 Paste a link
                       │
                       ▼
         ⚪ Ingestion service  (new backend: /v2/projects/extract/ or Gaia)
            reads doc/page → extracts title, category, location, dates,
            description, activities, images
                       │
              ┌─ success ─▶ NEXT SCREEN: the SAME 6-step form, now PREFILLED
              │             banner "Prefilled by AI — review & edit every field"
              │             every field editable → user reviews → publish
              └─ failure ─▶ stay on the form + toast "Couldn't read that — fill it in"
```

**Build notes**
- Frontend: add the AI toggle + upload/link panel above the existing schema-driven form. On success, prefill = initial values into the SAME wizard (`useSchemaForm`; wizard flow unchanged). `post/create.tsx` must accept the prefill payload as initial state. The reference form is the current 6-step wizard — see `EarthTeam_UX_Redesign_assets/input-current-form-add-project.jpeg`.
- Backend (**new capability**): document/URL → structured `projectsSchema` fields (schema at `src/data/projectsSchema.ts`). LLM extraction (Gaia infra) is the natural fit; images found in the source get proposed as media attachments.
- Guardrails: user **always reviews before submit** (hard requirement); AI never auto-publishes; size/type limits on uploads; URL fetch server-side only (SSRF-safe allowlist, https-only).

---

## 6. Sub-flow: Onboarding revamp (new)

Today's `app/onboarding.tsx` is a monotonous multi-step manual form. Revamp = **prefill-first, one review screen**.

```
Register → OTP verified
   └─ 🟡 Onboarding, step 1: "Set up in seconds"
        ├─ 🔗 Paste LinkedIn profile/company URL
        ├─ 🌐 Paste website link
        └─ ✍️  "Fill manually" (skip link — always available)
                       │
                       ▼
        ⚪ Enrichment service (new backend: e.g. /v2/onboarding/enrich/)
           fetches PUBLIC data: name, org name, bio, website, logo, industry, team size
                       │
                       ▼
        🛡️ Security gate (see below)
                       │
   🟡 Single REVIEW screen — prefilled form, all fields editable,
      provenance banner: "Prefilled from <link> — please verify"
                       │
                       ▼
   POST /v1/organization/update/  (unchanged — creates Solana wallet, sets onboarded=True)
```

**🛡️ Security measures**
| Measure | Detail |
|---|---|
| **Domain match** | Compare link domain vs. the user's verified email domain (`jane@wwf.org` + `wwf.org` ✓). Mismatch ⇒ inline warning + org flagged for manual review server-side — not a hard block (people use gmail). |
| Public data only | Enrichment fetches public pages only; **never** asks for credentials or LinkedIn login. |
| https-only + sanitization | Server-side fetch, https-only, URL sanitization, SSRF-safe (no internal IPs), rate-limited per user. |
| Provenance + consent | Banner on the review screen; user must review before submit. Nothing auto-submitted. |
| Approval unchanged | Existing "pending approval" admin step stays as the final safety net. |

**Why this matters for the Lobby:** Share and Earn both funnel new users into onboarding-gated actions — the faster onboarding converts, the more the hallways actually get walked.

---

## 7. NETWORK ⬜ → Partners directory (new)

**Tap → 🔵 `/partners` (new screen)** — "Meet frontline teams and fellow protectors."

- **Partner cards**: logo, name, 1–2 line description, and key numbers:
  - Years active · Projects done · Total project area (ha) · Stars earned
- Tap a card → 🔵 Partner detail (bio, contact/website ⚪, stats) → **"Their projects"** → 🟢 `/listview` filtered to that org's posts.
- Optional: gAia embedded as a guide here in nav Variant B (slide 9).

**Build notes**
- **No partners endpoint exists.** Data path options: (a) interim — hardcoded list like `ets-token.tsx`'s Top Contributors leaderboard; (b) proper — new `/v2/partners/` aggregating org profiles + per-org post stats. Ship (a) behind the same UI, swap to (b).
- `listview` filter-by-organization param needed (same param work as §2).

---

## 7b. EXPLORE 🗺 → the Map (before we discuss the bottom bar)

Right now **the Map is only reachable from the bottom nav bar** — there's no Lobby entry point for it. And **Share and Earn both funnel into Add Project**, so there's a redundancy worth addressing. Two ways to give Explore a home:

### Layout A — Explore as a **block under the four tiles** (default)
Keep the four tiles (Learn / Earn / Share / Network) and add a wide **Explore block** beneath them.

> **🗺 Explore** — "Explore the various projects by fellow protectors."

- Pro: nothing is removed; every path stays one tap from the Lobby.
- Con: the Lobby is a little busier (4 tiles + 1 block).

### Layout B — Explore **replaces the Share tile** (alternate — see `assets/screens/lobby-alt-explore.png`)
Tiles become **Learn / Earn / Explore / Network**. Share is dropped as a top-level tile.

- **Why this works:** **Share and Earn both already lead to Add Project** — Earn's "Earn by adding a project" CTA covers the Share intent. Dropping the Share tile removes the duplication and frees a slot for Explore, keeping a clean 2×2 grid.
- Adding a project is still one tap from Earn; Explore gets a proper tile.

### A third option (mentioned, not recommended)
Replace the **Earn** tile with **Verify** instead. Rejected because **Verify already lives in the bottom nav bar** — putting it in the Lobby too would be repetitive, whereas the Map (Explore) currently has *no* entry point besides the nav bar, so surfacing it in the Lobby adds genuinely new reach.

**In all layouts:** Tap Explore → 🟢 `/(tabs)/map` (existing Map screen — see `EarthTeam_UX_Redesign_assets/map-page-screenshot.jpeg`). Tapping a pin → 🟢 `/post/[id]`. Reuses the Map entirely — no map changes; purely a new Lobby entry point.

---

## 8. Screen inventory delta (what this plan adds/changes)

| Screen | Route | Status | Effort driver |
|---|---|---|---|
| Entrance Lobby | `/lobby` | 🔵 new | Simple static screen; 4 tiles + Explore block + skip link |
| Learn hub (2 sections) | `/learn` | 🔵 new | Static screen |
| How to earn Stars (2a) | `/learn/earn-stars` | 🔵 new | Static content |
| Earn hallway | `/earn` | 🔵 new | Composition + "Other ways to earn" list |
| Stars explainer (video) | `/stars-explainer` (interim: `/ets-token`) | 🔵 new / 🟡 | Video asset production |
| Partners directory (+detail) | `/partners` | 🔵 new | Backend data source |
| Explore block → Map | Lobby block → `/(tabs)/map` | 🟡 modify (entry point only) | Trivial — reuses Map |
| gAia preset conversation | `/(tabs)/ai-chat?preset=learn` | 🟡 modify | Param handling + canned content config |
| Add Project — AI toggle + ingestion | `/post/create` | 🟡 modify + ⚪ new backend | Ingestion service |
| Prefilled form (AI result) | `/post/create` (prefilled) | 🟡 modify | Prefill into existing wizard |
| Onboarding revamp | `/onboarding` | 🟡 modify + ⚪ new backend | Enrichment service + security gate |
| List view filter params | `/listview?projectType=…&org=…` | 🟡 modify | Small |
| Post-login redirect | `app/index.tsx` → `/lobby` | 🟡 modify | Trivial |
| Hamburger "Lobby" item (Variant A) | `TopAppBar` menu | 🟡 modify | Trivial |

**Suggested build order** (aligned with slide 11): ① Lobby (tiles + Explore block) + redirect + hamburger entry → ② Learn hub, Earn hallway, Learn preset (pure frontend) → ③ Add Project AI option + onboarding revamp (backend pair) → ④ Partners directory → ⑤ Nav Variant B restructure, only once hallways prove out.

---

## 9. Open questions carried forward

1. Lobby every session vs. default-hallway skip (slide 11) — recommendation in §1.
2. gAia in-hallway vs. standalone tab — Variant A keeps the tab for now; revisit at step ⑤.
3. "Solutions" vs. "Miracles" vs. "Magic" naming — unresolved, affects Learn/listview labels.
4. CTOC portal: exact URL(s) to link from the Learn preset — needs content owner input.
5. Internships (Learn tile copy): source/portal for listings — none exists in-app today.