{"id":26369850,"url":"https://github.com/msparihar/globetrotter","last_synced_at":"2026-01-03T21:07:01.710Z","repository":{"id":280291178,"uuid":"941526636","full_name":"Msparihar/globetrotter","owner":"Msparihar","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-14T20:24:17.000Z","size":549,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-14T21:27:51.021Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://globetrotter.manishsingh.tech/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Msparihar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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}},"created_at":"2025-03-02T14:04:12.000Z","updated_at":"2025-03-14T20:24:20.000Z","dependencies_parsed_at":"2025-03-02T15:34:47.315Z","dependency_job_id":null,"html_url":"https://github.com/Msparihar/globetrotter","commit_stats":null,"previous_names":["msparihar/globetrotter"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Msparihar%2Fglobetrotter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Msparihar%2Fglobetrotter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Msparihar%2Fglobetrotter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Msparihar%2Fglobetrotter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Msparihar","download_url":"https://codeload.github.com/Msparihar/globetrotter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243945592,"owners_count":20372897,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2025-03-16T23:16:55.854Z","updated_at":"2026-01-03T21:07:01.663Z","avatar_url":"https://github.com/Msparihar.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🌍 Globetrotter\n\nA real-time geography quiz game that tests your knowledge of world cities through an engaging and interactive experience.\n\n## 🎮 Game Preview\n\n![Home Screen](assets/images/home.png)\n*Home screen where players can start their journey*\n\n![Game Start](assets/images/game_start.png)\n*Beginning of a new game session*\n\n![Correct Guess](assets/images/correct_guess.png)\n*Feedback when player makes a correct guess*\n\n## 🏗️ Architecture Overview\n\nGlobetrotter is built with a modern, scalable architecture using FastAPI for the backend, PostgreSQL for data persistence, and React with TanStack Query for the frontend.\n\n```mermaid\ngraph TB\n    subgraph \"Frontend Layer\"\n        UI[React UI]\n        RQ[TanStack Query]\n        UI --\u003e RQ\n    end\n\n    subgraph \"API Gateway\"\n        API[FastAPI Server]\n        Cache[Redis Cache]\n        RQ --\u003e API\n        API \u003c--\u003e Cache\n    end\n\n    subgraph \"Data Layer\"\n        DB[(PostgreSQL)]\n        API \u003c--\u003e DB\n    end\n```\n\n### Data Flow\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant Frontend\n    participant API\n    participant Cache\n    participant Database\n\n    User-\u003e\u003eFrontend: Start Game\n    Frontend-\u003e\u003eAPI: Create User\n    API-\u003e\u003eDatabase: Store User\n    Database--\u003e\u003eAPI: User Created\n    API--\u003e\u003eFrontend: User Details\n\n    loop Game Play\n        Frontend-\u003e\u003eAPI: Get Question\n        API-\u003e\u003eCache: Check Cache\n        alt Cache Hit\n            Cache--\u003e\u003eAPI: Return Cached Question\n        else Cache Miss\n            API-\u003e\u003eDatabase: Fetch Question\n            Database--\u003e\u003eAPI: Question Data\n            API-\u003e\u003eCache: Store in Cache\n        end\n        API--\u003e\u003eFrontend: Question Data\n\n        User-\u003e\u003eFrontend: Submit Answer\n        Frontend-\u003e\u003eAPI: Post Answer\n        API-\u003e\u003eDatabase: Update Score\n        API-\u003e\u003eCache: Invalidate Cache\n        API--\u003e\u003eFrontend: Result\n    end\n```\n\n## 🚀 Features\n\n- 🌐 Real-time geography quiz game\n- 🎲 Random city selection from a vast database\n- 📊 Score tracking and statistics\n- 🏆 Achievement system\n- 🔄 Instant feedback on answers\n- 📱 Responsive design for all devices\n\n## 🛠️ Tech Stack\n\n### Frontend\n\n- React with TypeScript\n- Next.js 13+ (App Router)\n- TanStack Query for data fetching\n- Tailwind CSS for styling\n- Shadcn UI components\n\n### Backend\n\n- FastAPI (Python)\n- PostgreSQL for data persistence\n- Redis for caching\n- Pydantic for data validation\n- SQLAlchemy ORM\n\n## 🏃‍♂️ Running Locally\n\n### Prerequisites\n\n- Docker and Docker Compose\n- Node.js 18+ (for local development)\n- Python 3.11+ (for local development)\n\n### Using Docker\n\n1. Clone the repository\n\n```bash\ngit clone https://github.com/yourusername/globetrotter.git\ncd globetrotter\n```\n\n2. Create environment files\n\n```bash\ncp backend/.env.example backend/.env\n```\n\n3. Start the application\n\n```bash\ndocker-compose up\n```\n\nThe application will be available at:\n\n- Frontend: \u003chttp://localhost:3000\u003e\n- Backend API: \u003chttp://localhost:8000\u003e\n- API Docs: \u003chttp://localhost:8000/docs\u003e\n\n### Local Development\n\n1. Frontend Setup\n\n```bash\ncd frontend\nnpm install\nnpm run dev\n```\n\n2. Backend Setup\n\n```bash\ncd backend\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\npip install -r requirements.txt\nuvicorn src.main:app --reload\n```\n\n## 📝 API Documentation\n\n### Core Endpoints\n\n1. `POST /api/v1/users`\n   - Create new user\n   - Returns user details and session token\n\n2. `GET /api/v1/game/question`\n   - Fetch random question\n   - Cached for 5 minutes\n\n3. `POST /api/v1/game/answer`\n   - Submit answer\n   - Updates user score\n   - Returns result with fun fact\n\n4. `GET /api/v1/users/{username}/stats`\n   - Fetch user statistics\n\nFor complete API documentation, visit `/docs` when running the backend server.\n\n## 🤝 Contributing\n\nContributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.\n\n## 📜 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- City data provided by [GeoNames](https://www.geonames.org/)\n- Icons from [Heroicons](https://heroicons.com/)\n- UI components from [shadcn/ui](https://ui.shadcn.com/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsparihar%2Fglobetrotter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmsparihar%2Fglobetrotter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsparihar%2Fglobetrotter/lists"}