{"id":49642866,"url":"https://github.com/nikhil-thomas-a/solesearch","last_synced_at":"2026-05-05T20:05:13.301Z","repository":{"id":352624077,"uuid":"1207280339","full_name":"nikhil-thomas-a/solesearch","owner":"nikhil-thomas-a","description":"Data-driven shoe discovery — 9-signal biomechanics fit engine across 67 shoes in 14 categories. Built with Next.js + TypeScript.","archived":false,"fork":false,"pushed_at":"2026-05-05T11:53:14.000Z","size":230,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-05T13:39:52.236Z","etag":null,"topics":["nextjs","recommender-system","shoe-finder","tailwindcss","typescript","vercel"],"latest_commit_sha":null,"homepage":"https://solesearch-one.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nikhil-thomas-a.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-10T19:13:33.000Z","updated_at":"2026-05-05T11:53:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nikhil-thomas-a/solesearch","commit_stats":null,"previous_names":["nikhil-thomas-a/solesearch"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nikhil-thomas-a/solesearch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikhil-thomas-a%2Fsolesearch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikhil-thomas-a%2Fsolesearch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikhil-thomas-a%2Fsolesearch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikhil-thomas-a%2Fsolesearch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nikhil-thomas-a","download_url":"https://codeload.github.com/nikhil-thomas-a/solesearch/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikhil-thomas-a%2Fsolesearch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32665702,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-05T11:29:49.557Z","status":"ssl_error","status_checked_at":"2026-05-05T11:29:48.587Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["nextjs","recommender-system","shoe-finder","tailwindcss","typescript","vercel"],"created_at":"2026-05-05T20:05:11.680Z","updated_at":"2026-05-05T20:05:13.285Z","avatar_url":"https://github.com/nikhil-thomas-a.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SoleSearch\n\n\u003e Data-driven shoe discovery. Find your perfect shoe through biomechanics-aware fit matching, real lab data, and multi-currency price tracking.\n\n**🔗 Live site: [solesearch-one.vercel.app](https://solesearch-one.vercel.app)**\n\n| | |\n|---|---|\n| **Quiz** | [solesearch-one.vercel.app/finder](https://solesearch-one.vercel.app/finder) |\n| **Catalogue** | [solesearch-one.vercel.app/catalogue](https://solesearch-one.vercel.app/catalogue) |\n| **Compare** | [solesearch-one.vercel.app/compare](https://solesearch-one.vercel.app/compare) |\n\n---\n\n## What it does\n\nSoleSearch is a full-stack shoe discovery platform that matches users to shoes based on their foot shape, body weight, biomechanics, and use case — not brand sponsorships or paid placement.\n\n### The fit engine (9 signals, 0–100 match score)\n\n| Signal | Weight | What it measures |\n|--------|--------|-----------------|\n| Category fit | 25% | Does the shoe match the intended use? |\n| Toebox width | 18% | mm measurement vs user's foot width |\n| Cushioning | 15% | Midsole hardness (Shore C) + stack height vs preference + body weight |\n| Arch support | 12% | neutral / stability / motion-control vs foot type |\n| Budget | 10% | Price vs budget, 20% grace window |\n| Injury history | 8% | Per-condition rules (plantar fasciitis, Achilles, bunions, knee pain…) |\n| Durability | 5% | Durability score weighted by weekly km |\n| Weight | 4% | Grams vs activity intensity |\n| Heel drop | 3% | mm vs foot strike pattern |\n\nEach signal returns a plain-English reason if positive and a warning if it's a compromise. The full engine is in [`src/lib/recommend.ts`](src/lib/recommend.ts) — 394 lines, fully documented.\n\n---\n\n## Features\n\n- **6-step plain-English quiz** — no jargon, wet-foot-test arch guide, UK/US/EU sizing toggle\n- **67 shoes across 14 categories** — road running, trail, basketball, football, tennis, gym, hiking, walking, sneakers, boots, kids, work safety, healthcare, wide/orthopaedic\n- **Full shoe detail pages** — 12 lab metrics with visual bars, 7-month price chart, fit guide, construction breakdown, review sentiment, similar shoes\n- **Live catalogue** — filter by category, brand, price, min CoreScore; live search; sort by score/price/weight\n- **Side-by-side compare** — searchable picker across all 67 shoes, colour-coded score highlights, quick verdict cards\n- **Multi-currency** — USD (default), GBP, EUR, INR, AUD, CAD — all prices stored in USD, converted at display via React Context\n- **Zero dependencies on external APIs** — entire recommendation engine runs client-side, no backend required to demo\n\n---\n\n## Tech stack\n\n| Layer | Technology |\n|-------|-----------|\n| Frontend | Next.js 16 (App Router) + TypeScript |\n| Styling | Tailwind v4 + custom CSS design system (dark theme) |\n| State | React Context (RegionContext for currency), sessionStorage (quiz profile) |\n| Recommendation engine | Pure TypeScript, client-side, `src/lib/recommend.ts` |\n| Backend (scaffold) | FastAPI (Python 3.11+) — stubbed routes, ready to wire |\n| Database (ready) | PostgreSQL + pgvector schema in `backend/schema.sql` |\n| Hosting | Vercel (auto-deploys from `main` branch) |\n\n---\n\n## Project structure\n\n```\nsrc/\n├── app/\n│   ├── page.tsx                  Homepage (counts pull from real data)\n│   ├── catalogue/page.tsx        Browse + filter (live, client-side)\n│   ├── shoes/[slug]/page.tsx     Full shoe detail (6 sections)\n│   ├── compare/page.tsx          3-slot comparison with searchable picker\n│   ├── finder/page.tsx           6-step quiz\n│   └── finder/results/page.tsx  Live ranked results with explanations\n├── components/\n│   ├── layout/Navbar.tsx         Dark nav + region/currency dropdown\n│   └── ui/  CategoryCard, Pill, ScoreBar, ScoreRing\n├── data/\n│   └── shoes.ts                 67-shoe dataset across 14 categories\n├── lib/\n│   ├── recommend.ts              9-signal recommendation engine (394 lines)\n│   ├── regionContext.tsx         Global currency/region React Context\n│   └── utils.ts                 Helpers (scoreColor, heelDropLabel, softnessLabel)\n└── types/index.ts               Full TypeScript model (Shoe, FootProfile, Recommendation)\nbackend/\n├── main.py                       FastAPI scaffold (all routes stubbed, ready to wire)\n└── schema.sql                    PostgreSQL + pgvector schema\n```\n\n---\n\n## Getting started locally\n\n```bash\ngit clone https://github.com/nikhil-thomas-a/solesearch-app\ncd solesearch-app\nnpm install\nnpm run dev\n# → http://localhost:3000\n```\n\nNo environment variables required — the frontend works fully standalone.\n\n**Backend (optional):**\n```bash\npip install fastapi uvicorn psycopg2-binary python-dotenv\necho \"DATABASE_URL=postgresql://postgres:password@localhost:5432/solesearch\" \u003e backend/.env\npsql -U postgres -d solesearch -f backend/schema.sql\npython backend/main.py\n# → http://localhost:8000/docs\n```\n\n---\n\n## Deploying to Vercel\n\nThe site deploys automatically from the `main` branch via Vercel's GitHub integration.\n\n**First-time setup:**\n1. Push the repo to GitHub\n2. Go to [vercel.com](https://vercel.com) → New Project → Import your GitHub repo\n3. Vercel auto-detects Next.js — no configuration needed\n4. Click Deploy → live in ~60 seconds\n\n**Or via CLI:**\n```bash\nnpm i -g vercel\nvercel\n```\n\n**Custom domain:** Vercel dashboard → Settings → Domains → Add your domain.\n\nEvery push to `main` triggers an automatic redeploy. Pull request previews are created automatically.\n\n---\n\n## Data\n\nLab measurements (weight, drop, stack heights, midsole hardness, energy return %, toebox dimensions, breathability, grip scores) are sourced from:\n\n- Published brand spec sheets\n- Running Warehouse's independently measured specs\n- Aggregated expert review data from major shoe review publications\n\nScores are editorial aggregates. No brand payments influence any score.\n\n**Goal:** A data partnership with [RunRepeat](https://runrepeat.com) — their physical lab measurements (30+ metrics per shoe, cut-open testing, durometer readings) powering this recommendation engine.\n\n---\n\n## Roadmap\n\n- [x] Phase 1 — UI foundations (shoe detail, design system, dark theme)\n- [x] Phase 2 — Project scaffold (Next.js 16, TypeScript, Tailwind v4)\n- [x] Phase 3 — Recommendation engine (9-signal scoring, plain-English results)\n- [x] Phase 4 — Full dataset (67 shoes, 14 categories)\n- [x] Phase 5 — Multi-currency (USD/GBP/EUR/INR/AUD/CAD via React Context)\n- [x] Phase 6 — Vercel deployment with auto-deploy from GitHub\n- [ ] Phase 7 — Supabase integration (replace static data with live DB)\n- [ ] Phase 8 — RunRepeat data partnership (lab data licensing)\n- [ ] Phase 9 — Affiliate links (Nike, ASICS, Running Warehouse, Zappos)\n- [ ] Phase 10 — User auth + wishlists (NextAuth.js)\n- [ ] Phase 11 — AI match explanations (Claude API)\n\n---\n\n*Built by Nikhil Thomas A · [github.com/nikhil-thomas-a](https://github.com/nikhil-thomas-a)*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikhil-thomas-a%2Fsolesearch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnikhil-thomas-a%2Fsolesearch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikhil-thomas-a%2Fsolesearch/lists"}