docs: rewrite README with humanised copy and accurate CAT scoring des…#45
docs: rewrite README with humanised copy and accurate CAT scoring des…#45dakshhhhh16 wants to merge 1 commit intoKathiraveluLab:experimental-dakshhhhh16from
Conversation
|
/gemini review |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request significantly overhauls the README.md to provide a more comprehensive and user-friendly overview of the TENeT project. Key updates include a more detailed project description, expanded setup instructions, a new section explaining the scoring methodology, and a list of key API endpoints. A review comment correctly identified that the documented API endpoints for telehealth priority and affordability were missing required path parameters, which should be corrected to match the backend implementation.
| | `GET /api/cat/telehealth-priority` | Telehealth priority rankings per community | | ||
| | `GET /api/cat/performance` | Measured broadband speeds (Ookla data) | | ||
| | `GET /api/cat/affordability` | Internet cost burden per community | |
There was a problem hiding this comment.
The API endpoints for telehealth priority and affordability are missing the required <region_code> path parameter. Based on the implementation in backend/routes/cat_routes.py, these routes are defined as /telehealth-priority/<region_code> and /regions/<region_code>/affordability respectively.
| | `GET /api/cat/telehealth-priority` | Telehealth priority rankings per community | | |
| | `GET /api/cat/performance` | Measured broadband speeds (Ookla data) | | |
| | `GET /api/cat/affordability` | Internet cost burden per community | | |
| | GET /api/cat/telehealth-priority/<region_code> | Telehealth priority ranking for a specific community | | |
| | GET /api/cat/performance | Measured broadband speeds (Ookla data) | | |
| | GET /api/cat/regions/<region_code>/affordability | Internet cost burden for a specific community | |
There was a problem hiding this comment.
Code Review
This pull request significantly refactors the README.md to provide a more detailed and professional overview of the TENeT project, including updated project descriptions, a more granular tech stack breakdown, and comprehensive setup instructions. The review feedback identifies several areas for improvement: correcting API endpoint documentation to align with the actual backend routes, removing hardcoded developer branches from the setup guide to ensure long-term maintainability, and standardizing the terminology for the project's core scoring metrics to improve clarity for new contributors.
| | `GET /api/cat/telehealth-priority` | Telehealth priority rankings per community | | ||
| | `GET /api/cat/performance` | Measured broadband speeds (Ookla data) | | ||
| | `GET /api/cat/affordability` | Internet cost burden per community | |
There was a problem hiding this comment.
The API endpoints listed for telehealth-priority and affordability do not match the current backend implementation in backend/routes/cat_routes.py. The existing routes for these features require a specific <region_code> (see lines 766 and 1197 in the route file). If these entries are intended to represent bulk data endpoints for all communities, they should be updated to point to the correct paths, such as /api/cat/healthcare-necessity and /api/cat/telehealth-status/all respectively.
| ```bash | ||
| git clone https://github.com/KathiraveluLab/TENeT.git | ||
| cd TENeT | ||
| git checkout experimental-dakshhhhh16 |
There was a problem hiding this comment.
Hardcoding a specific developer's experimental branch (experimental-dakshhhhh16) in the main setup instructions is a maintenance risk. Once this branch is merged or deleted, the instructions will break for new contributors. It is recommended to point to the main branch or use a generic placeholder.
| git checkout experimental-dakshhhhh16 | |
| git checkout main |
There was a problem hiding this comment.
I have made the setup guidance as per my own branch for now, the main branch is empty currently, to view the current TENeT prototype made by me user has to checkout my experimental branch created
| | **Community Access Tiers (CAT)** | Every community is color-coded by its Telehealth Need Score (0-100) - a composite of healthcare access gaps, broadband quality, transport limitations, and seasonal effects | | ||
| | **Healthcare Desert Score (0–100)** | How far people are from clinics, how many providers exist nearby, whether specialists are reachable, and how transport disruptions make things worse | |
There was a problem hiding this comment.
There is inconsistency in the naming of the primary metric. It is referred to as "Telehealth Need Score" (lines 26, 162, 171), "Healthcare Desert Score" (lines 27, 149), and "Telehealth Necessity Score" (implied by the code's necessity_score). Standardizing this terminology across the documentation and code will improve clarity.
There was a problem hiding this comment.
Pull request overview
This PR rewrites README.md to provide a more narrative, contributor-friendly introduction and a clearer onboarding path for running TENeT locally.
Changes:
- Replaces the README intro with “humanized” project framing and a “Why This Exists” section.
- Converts key sections into tables (features, tech stack, prerequisites, data sources) and expands scoring explanations.
- Expands “Getting Started” with step-by-step backend/frontend run instructions and adds a “Key API Endpoints” section.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | **Community Access Tiers (CAT)** | Every community is color-coded by its Telehealth Need Score (0-100) - a composite of healthcare access gaps, broadband quality, transport limitations, and seasonal effects | | ||
| | **Healthcare Desert Score (0–100)** | How far people are from clinics, how many providers exist nearby, whether specialists are reachable, and how transport disruptions make things worse | |
There was a problem hiding this comment.
The "Community Access Tiers (CAT)" row is describing a composite "Telehealth Need Score" and says communities are color-coded by it. In the current API/UI, CAT is a 1–4 transport tier (tier_level), while the 0–100 value shown in the UI is necessity_score (healthcare necessity/desert score). Please rewrite this row to describe CAT tiers (1–4) and, if you want to document map coloring, add a separate row/statement for the 0–100 necessity/need score (or the combined_priority from /api/cat/telehealth-priority/<region_code>).
| | **Community Access Tiers (CAT)** | Every community is color-coded by its Telehealth Need Score (0-100) - a composite of healthcare access gaps, broadband quality, transport limitations, and seasonal effects | | |
| | **Healthcare Desert Score (0–100)** | How far people are from clinics, how many providers exist nearby, whether specialists are reachable, and how transport disruptions make things worse | | |
| | **Community Access Tiers (CAT)** | Each community is assigned a transport/access tier from **1-4** (`tier_level`) based on how reachable it is and how transportation constraints affect access | | |
| | **Healthcare Necessity / Desert Score (0–100)** | Communities can also be color-coded by a **0-100 necessity score** (`necessity_score`) showing healthcare access need based on distance to care, provider availability, specialist reachability, and transport disruption impacts | |
| | Endpoint | What it returns | | ||
| |----------|-----------------| | ||
| | `GET /api/cat/regions?season=summer` | All communities with tier levels, adjusted for season | | ||
| | `GET /api/cat/telehealth-priority` | Telehealth priority rankings per community | |
There was a problem hiding this comment.
GET /api/cat/telehealth-priority is not a valid route as written. The backend defines GET /api/cat/telehealth-priority/<region_code> (with optional season and road_quality query params). Update the README endpoint to include the required region_code path parameter (and document the supported query params if helpful).
| | `GET /api/cat/telehealth-priority` | Telehealth priority rankings per community | | |
| | `GET /api/cat/telehealth-priority/<region_code>?season=<season>&road_quality=<road_quality>` | Telehealth priority rankings for a specific community/region; `season` and `road_quality` are optional query params | |
| | `GET /api/cat/regions?season=summer` | All communities with tier levels, adjusted for season | | ||
| | `GET /api/cat/telehealth-priority` | Telehealth priority rankings per community | | ||
| | `GET /api/cat/performance` | Measured broadband speeds (Ookla data) | | ||
| | `GET /api/cat/affordability` | Internet cost burden per community | |
There was a problem hiding this comment.
GET /api/cat/affordability does not exist in the backend routes. The available affordability endpoints are GET /api/cat/performance/affordability (ZCTA-level affordability analysis) and GET /api/cat/regions/<region_code>/affordability (region-specific affordability). Please update the README to list the correct endpoint(s).
| | `GET /api/cat/affordability` | Internet cost burden per community | | |
| | `GET /api/cat/performance/affordability` | ZCTA-level affordability analysis | | |
| | `GET /api/cat/regions/<region_code>/affordability` | Region-specific affordability analysis | |
| The API will be live at **http://localhost:5001**. You should see: | ||
|
|
||
| ``` | ||
| Database initialized successfully | ||
| Starting TENeT Backend on http://localhost:5001 | ||
| ``` |
There was a problem hiding this comment.
The "You should see" backend startup output is missing the additional log line printed by backend/app.py ("CAT API available at http://localhost:5001/api/cat"). Consider either including that line or wording this as "You should see output similar to" to avoid confusing new contributors.
Summary
Taking README.md as a dynamic document and as a face of the complete project. This PR proposes the latest version of README.md including complete file structure, project description and everythinf else which a new contributor would require to start studying/contributing to the project