Constitution Compass

Interactive quiz application for learning about the U.S. Constitution
Try it Live »

Report Bug · Request Feature · Send Feedback

About The Project

Constitution 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.

Live Application: https://constitution-compass.vercel.app

Project Documentation:

📋 CHANGELOG - View all releases and updates
📄 LICENSE - Copyright and usage terms

Key Features

🤖 AI-Powered Question Generation - Dynamic questions using Google Gemini API
📊 Regional Analytics - Track quiz performance by geographic region
🎯 Customizable Difficulty - Easy, Medium, and Hard levels
📚 Topic-Specific Quizzes - Focus on specific Constitutional topics
💡 Detailed Explanations - Learn from each answer
📱 Responsive Design - Works on all devices
🔒 Privacy-Focused - Only regional data collected, no personal information

Built With AI

This 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.

Technology Stack

Frontend: React 19, Tailwind CSS, Lucide React icons
Backend: Node.js 22, Vercel Serverless Functions
Database: Neon Serverless Postgres (via Vercel)
AI Services: Google Gemini API (gemini-2.0-flash-exp), Claude AI (development)
Analytics: Vercel Analytics
Hosting: Vercel
CI/CD: GitHub Actions with tag-based deployments
Geolocation: Vercel headers + ipapi.co fallback

Getting Started

Prerequisites

Node.js 22 or higher
npm or yarn
Google Gemini API key (for AI-generated questions)
Neon Postgres database (for score tracking)

Installation

Clone the repository

git clone https://github.com/emckenna/constitution-compass.git
cd constitution-compass

Install dependencies
```
npm install
```

Create a .env.local file with required environment variables

GEMINI_API_KEY=your_gemini_api_key
DATABASE_URL=your_neon_postgres_connection_string
BLACKLIST_IPS=your.ip.address.here,another.ip.if.needed  # Optional: Exclude IPs from analytics

Initialize the database

# After deploying to Vercel, visit:
https://your-app.vercel.app/api/init-db

Run the development server
```
npm start
```
Open http://localhost:3000 in your browser

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.

Deployment

This project uses a preview-then-promote workflow for safe deployments:

Development Workflow

Create a feature branch

git checkout -b feature/your-feature-name

Make changes and push

git add .
git commit -m "Your changes"
git push origin feature/your-feature-name

Preview deployment automatically created
- GitHub Actions automatically deploys to Vercel preview URL
- Test your changes on the preview URL before merging
Create Pull Request
- Open PR to merge into main
- Preview URL will be commented on the PR

Merge and deploy to production

git checkout main
git pull
npm run deploy-quick  # Auto-tags and deploys to production

Deployment Commands

Quick Deploy (Patch Version)

npm run deploy-quick

Interactive Deploy

npm run deploy

The deploy script:

Checks for uncommitted changes
Auto-pushes commits if needed
Creates and pushes version tags
Triggers GitHub Actions workflow
Deploys to Vercel production automatically

Deployment Environments

Preview: All feature branches and PRs → https://constitution-compass-<hash>.vercel.app
Production: Tagged releases on main → https://constitution-compass.vercel.app

API Endpoints

POST /api/generate-questions - Generate AI quiz questions
GET /api/get-region - Get user's geographic region
POST /api/save-score - Save quiz score to database
GET /api/stats - Get regional statistics
GET /api/init-db - Initialize database tables (run once)
GET /api/migrate-db - Run database migrations

Features Roadmap

Interactive analytics dashboard
Historical trending analysis
Regional leaderboards
Free-text questions with AI evaluation
Automated daily trivia posts to X/Twitter
More question topics and categories
User accounts and progress tracking

Contributing

This repository is for portfolio and demonstration purposes.

While I appreciate your interest, I am not accepting contributions at this time as this is a personal portfolio project. However, I welcome:

🐛 Bug reports via GitHub Issues
💡 Feature suggestions via GitHub Issues
💬 General feedback via GitHub Issues

License & Copyright

This project is publicly viewable for transparency and educational purposes, but remains protected by copyright.

Usage Policy

✅ View and learn from the code
✅ Use the live application at constitution-compass.vercel.app
✅ Report bugs and suggest features via GitHub Issues
⚠️ Do NOT copy, fork, or redistribute this code without explicit permission
⚠️ Do NOT use this code commercially without a license agreement

Why This Approach?

This is a portfolio project showcasing technical capabilities to employers and collaborators. Making it public allows:

📊 Transparency in demonstrating skills and coding practices
🤝 Community feedback and bug reports
🎓 Others to learn from the implementation
🔒 Protection of intellectual property and future opportunities

Want to Use This Code?

If you're interested in licensing this code or discussing collaboration:

📧 Email: eric.mckenna@gmail.com
💼 LinkedIn: linkedin.com/in/ericmckenna
🐦 X/Twitter: @USConstCompass

For recruiters and hiring managers: I'm happy to walk through the architecture, discuss technical decisions, and demonstrate how these skills apply to your needs.

Contact

Eric McKenna

💼 LinkedIn: linkedin.com/in/ericmckenna - Open to opportunities
🐦 X/Twitter: @USConstCompass
💻 GitHub: @emckenna
🌐 Live App: constitution-compass.vercel.app

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.

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.

Acknowledgments

Built primarily with Claude AI by Anthropic
Powered by Google Gemini API
Hosted on Vercel
Database by Neon
Icons by Lucide
Versioning follows Semantic Versioning
Changelog format based on Keep a Changelog
README template inspired by Best-README-Template

🇺🇸 Learn the Constitution. Know your rights. Be an informed citizen.

Name		Name	Last commit message	Last commit date
Latest commit History 72 Commits
.github		.github
api		api
bin		bin
data		data
public		public
scripts		scripts
src		src
.gitignore		.gitignore
.npmrc		.npmrc
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
SCORE_TRACKING.md		SCORE_TRACKING.md
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
prompts.md		prompts.md
tailwind.config.js		tailwind.config.js
vercel.json		vercel.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Constitution Compass