docs(readme): improve onboarding, FAQ, and structure (JhaSourav07#755)

* docs(readme): improve onboarding, FAQ, and structure

Signed-off-by: @Hima451 <himanishah123450@gmail.com>

* fix: resolve lint and CI issues

---------

Signed-off-by: @Hima451 <himanishah123450@gmail.com>

Author: Hima451

CONTRIBUTING.md

@@ -88,6 +88,59 @@ http://localhost:3000/api/streak?user=YOUR_GITHUB_USERNAME
 
 ---
 
+## 🤝 Contributor Onboarding
+
+### 📁 Project Structure
+
+```text
+app/api/streak/route.ts       → API route for SVG generation
+lib/github.ts                 → GitHub GraphQL API client
+lib/calculate.ts              → Streak calculation logic
+lib/svg/generator.ts          → SVG rendering engine
+lib/svg/themes.ts             → Theme configuration system
+utils/time.ts                 → UTC & timezone utilities
+types/index.ts                → Shared TypeScript interfaces
+```
+
+---
+
+### ⚠️ Local Setup Troubleshooting
+
+Common issues during setup:
+
+- **401 Unauthorized** → Invalid or missing `GITHUB_TOKEN`
+- **MongoDB errors** → `MONGODB_URI` is optional for local development
+- **Empty SVG output** → Ensure the GitHub username exists and has public contributions
+
+---
+
+### 🌱 Beginner-Friendly Contribution Areas
+
+Good first contributions:
+
+- Documentation improvements
+- New theme presets
+- SVG styling enhancements
+- UI polish and accessibility improvements
+
+---
+
+### 🔁 Simplified PR Workflow
+
+```text
+Fork Repository
+      ↓
+Create Branch
+      ↓
+Make Changes
+      ↓
+Run Tests & Lint
+      ↓
+Open Pull Request
+```
+
+---
+
 ## 🎯 What to Contribute
 
 We welcome contributions in three focused pillars. Staying within these areas ensures every PR adds clear, compounding value.

README.md

@@ -177,6 +177,20 @@ URL Parameter > Theme Default > System Fallback
 
 > **`auto` uses CSS `@media (prefers-color-scheme)`** inside the SVG so the badge switches between the `light` and `dark` palettes based on the viewer's OS setting — no JavaScript required. This is ideal for GitHub profile READMEs where visitors may use either mode.
 
+## 🎨 Theme Preview Gallery
+
+Explore some of the built-in CommitPulse themes and quickly copy the style you like.
+
+| Theme   | Usage Example    |
+| ------- | ---------------- |
+| Dark    | `?theme=dark`    |
+| Neon    | `?theme=neon`    |
+| Dracula | `?theme=dracula` |
+| Gruvbox | `?theme=gruvbox` |
+| GitHub  | `?theme=github`  |
+
+![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&theme=neon)
+
 ### Examples
 
 ```md
@@ -308,6 +322,23 @@ types/index.ts                →  TypeScript interfaces (StreakStats, BadgePara
 
 ---
 
+🏗️ Architecture Diagram
+GitHub GraphQL API
+↓
+Contribution Processing
+↓
+Streak Calculation Engine
+↓
+SVG Geometry Renderer
+↓
+Animation Layer
+↓
+Edge Cache/CDN
+↓
+Generated SVG Badge
+
+---
+
 ## 🚀 Self-Hosting in 4 Steps
 
 ```bash
@@ -378,6 +409,33 @@ This ensures maintainers aren't bottlenecks and the community moves incredibly f
 
 ---
 
+## ❓ FAQ
+
+### Why does my contribution count differ from GitHub?
+
+GitHub calculates contribution data using UTC timestamps. CommitPulse syncs cache invalidation with UTC midnight to ensure consistent results.
+
+### Why are my latest commits not visible immediately?
+
+Data is cached for performance. Use `&refresh=true` to force fresh data.
+
+### Can I use my local timezone?
+
+Yes. Use the `tz` parameter with any valid IANA timezone.
+
+Example:
+`?tz=Asia/Kolkata`
+
+### Do private contributions count?
+
+Yes — if private contributions visibility is enabled in your GitHub settings.
+
+### Are there GitHub API rate limits?
+
+Yes, but CommitPulse minimizes API usage using caching and optimized GraphQL queries.
+
+---
+
 ## 🤝 Contributing
 
 CommitPulse is an open project built for the Web3 and open-source community. Whether you want to design a new theme, refine the isometric geometry, or improve timezone edge cases — you are welcome here.