# 📖 Documentation Reading Guide — Hashtag Orange GBP Dashboard

> **Purpose**: This guide tells you exactly what order to read the 20+ docs in the GMB project, why each one exists, and where you are in the journey.

---

## The Story in 4 Sentences

1. **We planned** a 3-tier GBP dashboard (Agency → Client → Dealer) for Hashtag Orange.
2. **We built** Phases 0–5 with mock data — login, all 3 dashboards (with 4-tab client view), JWT auth, and role-based access are fully working.
3. **We hardened** the system in Phase 5.1 — fixed 10 bugs, added password validation, XSS protection, and cascade deactivation.
4. **Next**, we connect real Google API data (Phase 6) once you provide Google Cloud credentials in `human_inputs.md`.

---

## 🔢 Reading Order (Chronological Flow)

### Layer 1: "What are we building?" (The Vision)

| # | File | What It Answers | Read Time |
|---|------|-----------------|-----------|
| 1 | `claude.md` | **Start here.** Project identity, tech stack, naming rules, and the 3-tier hierarchy. | 3 min |
| 2 | `architecture.md` | Database schema, API contracts, folder structure, and security model. | 8 min |
| 3 | `workflow.md` | Interaction flow: How Agency manages Clients, and Clients manage Dealers. | 3 min |

---

### Layer 2: "What is the status?" (Tracking)

| # | File | What It Answers | Read Time |
|---|------|-----------------|-----------|
| 4 | `roadmap.md` | The **master plan** (7 phases). Shows what's done (✅) and what's pending (⬜). | 5 min |
| 5 | `PROGRESS_TRACKER.md` | A granular checklist of every task completed so far. | 5 min |
| 6 | `phase_audit.md` | Verification that all rules and requirements for Phases 0-5 are met. | 3 min |

---

### Layer 3: "How do I run and use it?" (Operations)

| # | File | What It Answers | Read Time |
|---|------|-----------------|-----------|
| 7 | `running_steps.md` | **Setup guide**: Venv, database seeding, starting the server, and test credentials. | 3 min |
| 8 | `walkthrough.md` | A visual tour of the user experience for all three roles. | 3 min |
| 9 | `screen_by_screen_testing_guide.md` | **Full testing guide**: Every screen, every button, every expected result + test credentials. | 10 min |
| 10 | `step_by_step_testing_guide_result.md` | **Test results (v2)**: Bugs found → fixes applied → code changes → re-test results. | 5 min |
| 11 | `test.md` | Results of the latest simulation with screenshots of all dashboards. | 2 min |

---

### Layer 4: "How is it built?" (Implementation)

| # | File | What It Answers | Read Time |
|---|------|-----------------|-----------|
| 10 | `system_documentation.md` | **File-by-file breakdown**: Which file does what and its core functions. | 5 min |
| 11 | `FLASH_PROMPT.md` | The original instructions used to build the core system. | 7 min |
| 12 | `flash_build_roadmap.md` | Technical sequence followed during the initial rapid build. | 8 min |

---

### Layer 5: "What is required from me?" (Inputs)

| # | File | What It Answers | Read Time |
|---|------|-----------------|-----------|
| 13 | `human_inputs.md` | **Action Required**: Fill this in with your Google Cloud credentials to proceed. | 5 min |
| 14 | `google_login_guide.md` | Step-by-step instructions for setting up Google Cloud Console. | 5 min |

---

### Layer 6: "What is the next step?" (Future)

| # | File | What It Answers | Read Time |
|---|------|-----------------|-----------|
| 15 | `GEMINI_PHASE6_PLAN.md` | The technical blueprint for Phase 6 (Real Google API Integration). | 8 min |

---

## 📊 Visual Summary

```
   Vision & Plan       Execution & Code      Verification & Next
  ┌─────────────┐      ┌─────────────┐       ┌─────────────┐
  │ claude.md   │ ───> │ running_steps│ ───>  │ test.md     │
  │ roadmap.md  │      │ system_doc   │       │ phase_audit │
  └─────────────┘      └─────────────┘       └─────────────┘
         │                    │                     │
         ▼                    ▼                     ▼
  Provide Inputs       Understand Logic      Proceed to Ph 6
  ┌─────────────┐      ┌─────────────┐       ┌─────────────┐
  │ human_inputs│      │ architecture │       │ PHASE6_PLAN │
  └─────────────┘      └─────────────┘       └─────────────┘
```

---

## ⚡ Quick Paths

*   **Total Newcomers**: Read `claude.md` first.
*   **Developers**: Read `running_steps.md` and `system_documentation.md`.
*   **Ready to Finish?**: Complete `human_inputs.md` and read `GEMINI_PHASE6_PLAN.md`.