{"id":31729745,"url":"https://github.com/emckenna/constitution-compass","last_synced_at":"2026-04-11T03:10:02.333Z","repository":{"id":318187046,"uuid":"1058915150","full_name":"emckenna/constitution-compass","owner":"emckenna","description":"Interactive Constitutional quiz app with AI-powered questions, regional analytics, and automated daily trivia posts to X/Twitter. Built with React, Vercel, and Claude AI.","archived":false,"fork":false,"pushed_at":"2025-10-05T17:53:44.000Z","size":3243,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-05T18:29:43.415Z","etag":null,"topics":["ai","analytics","civic-education","constitution","postgres","react","tailwindcss","vercel"],"latest_commit_sha":null,"homepage":"https://constitution-compass.vercel.app","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/emckenna.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-17T18:11:40.000Z","updated_at":"2025-10-05T18:03:09.000Z","dependencies_parsed_at":"2025-10-05T18:29:51.756Z","dependency_job_id":"fefc4ac4-bdd3-44e7-997a-fdf22e743b0d","html_url":"https://github.com/emckenna/constitution-compass","commit_stats":null,"previous_names":["emckenna/constitution-compass"],"tags_count":38,"template":false,"template_full_name":null,"purl":"pkg:github/emckenna/constitution-compass","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emckenna%2Fconstitution-compass","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emckenna%2Fconstitution-compass/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emckenna%2Fconstitution-compass/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emckenna%2Fconstitution-compass/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/emckenna","download_url":"https://codeload.github.com/emckenna/constitution-compass/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emckenna%2Fconstitution-compass/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279000989,"owners_count":26082972,"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","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["ai","analytics","civic-education","constitution","postgres","react","tailwindcss","vercel"],"created_at":"2025-10-09T07:16:14.557Z","updated_at":"2025-10-09T07:16:19.635Z","avatar_url":"https://github.com/emckenna.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Constitution Compass\n\n[![Issues][issues-shield]][issues-url]\n[![LinkedIn][linkedin-shield]][linkedin-url]\n\n\u003cdiv align=\"center\"\u003e\n  \u003ch3 align=\"center\"\u003eConstitution Compass\u003c/h3\u003e\n  \u003cp align=\"center\"\u003e\n    Interactive quiz application for learning about the U.S. Constitution\n    \u003cbr /\u003e\n    \u003ca href=\"https://constitution-compass.vercel.app\"\u003e\u003cstrong\u003eTry it Live »\u003c/strong\u003e\u003c/a\u003e\n    \u003cbr /\u003e\n    \u003cbr /\u003e\n    \u003ca href=\"https://github.com/emckenna/constitution-compass/issues/new?template=bug_report.md\"\u003eReport Bug\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/emckenna/constitution-compass/issues/new?template=feature_request.md\"\u003eRequest Feature\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/emckenna/constitution-compass/issues/new?template=feedback.md\"\u003eSend Feedback\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n## About The Project\n\nConstitution Compass is an interactive quiz application designed to test and improve your knowledge of the United States Constitution. Whether you're a student, educator, or civically engaged citizen, this tool makes learning about our founding document engaging and accessible.\n\n**Live Application:** [https://constitution-compass.vercel.app](https://constitution-compass.vercel.app)\n\n**Project Documentation:**\n- 📋 [CHANGELOG](CHANGELOG.md) - View all releases and updates\n- 📄 [LICENSE](LICENSE) - Copyright and usage terms\n\n### Key Features\n\n- 🤖 **AI-Powered Question Generation** - Dynamic questions using Google Gemini API\n- 📊 **Regional Analytics** - Track quiz performance by geographic region\n- 🎯 **Customizable Difficulty** - Easy, Medium, and Hard levels\n- 📚 **Topic-Specific Quizzes** - Focus on specific Constitutional topics\n- 💡 **Detailed Explanations** - Learn from each answer\n- 📱 **Responsive Design** - Works on all devices\n- 🔒 **Privacy-Focused** - Only regional data collected, no personal information\n\n### Built With AI\n\nThis application was primarily built using **Claude AI** (Anthropic's large language model) as a development partner. The codebase demonstrates how AI can accelerate modern web development while maintaining code quality and best practices.\n\n### Technology Stack\n\n- **Frontend:** React 19, Tailwind CSS, Lucide React icons\n- **Backend:** Node.js 22, Vercel Serverless Functions\n- **Database:** Neon Serverless Postgres (via Vercel)\n- **AI Services:** Google Gemini API (gemini-2.0-flash-exp), Claude AI (development)\n- **Analytics:** Vercel Analytics\n- **Hosting:** Vercel\n- **CI/CD:** GitHub Actions with tag-based deployments\n- **Geolocation:** Vercel headers + ipapi.co fallback\n\n## Getting Started\n\n### Prerequisites\n\n- Node.js 22 or higher\n- npm or yarn\n- Google Gemini API key (for AI-generated questions)\n- Neon Postgres database (for score tracking)\n\n### Installation\n\n1. Clone the repository\n   ```bash\n   git clone https://github.com/emckenna/constitution-compass.git\n   cd constitution-compass\n   ```\n\n2. Install dependencies\n   ```bash\n   npm install\n   ```\n\n3. Create a `.env.local` file with required environment variables\n   ```env\n   GEMINI_API_KEY=your_gemini_api_key\n   DATABASE_URL=your_neon_postgres_connection_string\n   BLACKLIST_IPS=your.ip.address.here,another.ip.if.needed  # Optional: Exclude IPs from analytics\n   ```\n\n4. Initialize the database\n   ```bash\n   # After deploying to Vercel, visit:\n   https://your-app.vercel.app/api/init-db\n   ```\n\n5. Run the development server\n   ```bash\n   npm start\n   ```\n\n6. Open [http://localhost:3000](http://localhost:3000) in your browser\n\n**Note:** AI-generated questions require the Gemini API and will only work in production (Vercel). For local development, the app falls back to hardcoded questions.\n\n## Deployment\n\nThis project uses a **preview-then-promote** workflow for safe deployments:\n\n### Development Workflow\n\n1. **Create a feature branch**\n   ```bash\n   git checkout -b feature/your-feature-name\n   ```\n\n2. **Make changes and push**\n   ```bash\n   git add .\n   git commit -m \"Your changes\"\n   git push origin feature/your-feature-name\n   ```\n\n3. **Preview deployment automatically created**\n   - GitHub Actions automatically deploys to Vercel preview URL\n   - Test your changes on the preview URL before merging\n\n4. **Create Pull Request**\n   - Open PR to merge into `main`\n   - Preview URL will be commented on the PR\n\n5. **Merge and deploy to production**\n   ```bash\n   git checkout main\n   git pull\n   npm run deploy-quick  # Auto-tags and deploys to production\n   ```\n\n### Deployment Commands\n\n**Quick Deploy (Patch Version)**\n```bash\nnpm run deploy-quick\n```\n\n**Interactive Deploy**\n```bash\nnpm run deploy\n```\n\nThe deploy script:\n- Checks for uncommitted changes\n- Auto-pushes commits if needed\n- Creates and pushes version tags\n- Triggers GitHub Actions workflow\n- Deploys to Vercel production automatically\n\n### Deployment Environments\n\n- **Preview:** All feature branches and PRs → `https://constitution-compass-\u003chash\u003e.vercel.app`\n- **Production:** Tagged releases on `main` → `https://constitution-compass.vercel.app`\n\n## API Endpoints\n\n- `POST /api/generate-questions` - Generate AI quiz questions\n- `GET /api/get-region` - Get user's geographic region\n- `POST /api/save-score` - Save quiz score to database\n- `GET /api/stats` - Get regional statistics\n- `GET /api/init-db` - Initialize database tables (run once)\n- `GET /api/migrate-db` - Run database migrations\n\n## Features Roadmap\n\n- [ ] Interactive analytics dashboard\n- [ ] Historical trending analysis\n- [ ] Regional leaderboards\n- [ ] Free-text questions with AI evaluation\n- [ ] Automated daily trivia posts to X/Twitter\n- [ ] More question topics and categories\n- [ ] User accounts and progress tracking\n\n## Contributing\n\n**This repository is for portfolio and demonstration purposes.**\n\nWhile I appreciate your interest, I am **not accepting contributions** at this time as this is a personal portfolio project. However, I welcome:\n\n- 🐛 **Bug reports** via [GitHub Issues](https://github.com/emckenna/constitution-compass/issues/new?template=bug_report.md)\n- 💡 **Feature suggestions** via [GitHub Issues](https://github.com/emckenna/constitution-compass/issues/new?template=feature_request.md)\n- 💬 **General feedback** via [GitHub Issues](https://github.com/emckenna/constitution-compass/issues/new?template=feedback.md)\n\n## License \u0026 Copyright\n\n**© 2024-2025 Eric McKenna. All Rights Reserved.**\n\nThis project is **publicly viewable** for transparency and educational purposes, but remains protected by copyright.\n\n### Usage Policy\n\n- ✅ **View and learn** from the code\n- ✅ **Use the live application** at [constitution-compass.vercel.app](https://constitution-compass.vercel.app)\n- ✅ **Report bugs and suggest features** via GitHub Issues\n- ⚠️ **Do NOT** copy, fork, or redistribute this code without explicit permission\n- ⚠️ **Do NOT** use this code commercially without a license agreement\n\n### Why This Approach?\n\nThis is a **portfolio project** showcasing technical capabilities to employers and collaborators. Making it public allows:\n\n- 📊 Transparency in demonstrating skills and coding practices\n- 🤝 Community feedback and bug reports\n- 🎓 Others to learn from the implementation\n- 🔒 Protection of intellectual property and future opportunities\n\n### Want to Use This Code?\n\nIf you're interested in licensing this code or discussing collaboration:\n- 📧 Email: eric.mckenna@gmail.com\n- 💼 LinkedIn: [linkedin.com/in/ericmckenna](https://www.linkedin.com/in/ericmckenna/)\n- 🐦 X/Twitter: [@USConstCompass](https://x.com/USConstCompass)\n\nFor **recruiters and hiring managers**: I'm happy to walk through the architecture, discuss technical decisions, and demonstrate how these skills apply to your needs.\n\n## Contact\n\n**Eric McKenna**\n\n- 💼 LinkedIn: [linkedin.com/in/ericmckenna](https://www.linkedin.com/in/ericmckenna/) - Open to opportunities\n- 🐦 X/Twitter: [@USConstCompass](https://x.com/USConstCompass)\n- 💻 GitHub: [@emckenna](https://github.com/emckenna)\n- 🌐 Live App: [constitution-compass.vercel.app](https://constitution-compass.vercel.app)\n\n**Portfolio Context:** This project showcases full-stack development capabilities—from React component architecture and state management to serverless functions, AI integration, and database design with Postgres. It demonstrates practical problem-solving and the ability to ship a polished, production-ready application.\n\n**Job Seeking?** I know how challenging the market can be. I built this to showcase technical skills and connect with others—whether you're hiring, looking for opportunities yourself, or want to discuss building with AI and modern web tech.\n\n## Acknowledgments\n\n- Built primarily with [Claude AI](https://claude.ai) by Anthropic\n- Powered by [Google Gemini API](https://ai.google.dev/gemini-api)\n- Hosted on [Vercel](https://vercel.com)\n- Database by [Neon](https://neon.tech)\n- Icons by [Lucide](https://lucide.dev)\n- Versioning follows [Semantic Versioning](https://semver.org/)\n- Changelog format based on [Keep a Changelog](https://keepachangelog.com/)\n- README template inspired by [Best-README-Template](https://github.com/othneildrew/Best-README-Template)\n\n---\n\n**🇺🇸 Learn the Constitution. Know your rights. Be an informed citizen.**\n\n\u003c!-- MARKDOWN LINKS \u0026 IMAGES --\u003e\n[issues-shield]: https://img.shields.io/github/issues/emckenna/constitution-compass.svg?style=for-the-badge\n[issues-url]: https://github.com/emckenna/constitution-compass/issues\n[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge\u0026logo=linkedin\u0026colorB=555\n[linkedin-url]: https://linkedin.com/in/ericmckenna\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femckenna%2Fconstitution-compass","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femckenna%2Fconstitution-compass","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femckenna%2Fconstitution-compass/lists"}