🏛️ Legis-lator

A full-stack web application for exploring U.S. Congressional bills with AI-powered features.

🚀 Deploy to Production (Render.com) | 📚 Quick Start Guide

---

✨ Features

• 📊 Browse Bills - Explore U.S. Congress legislation with detailed information
• 🔍 Smart Search - Filter by tags, keywords, status, and stage
• 📈 Track Progress - Visual bill progress through the legislative process
• 🤖 AI Summaries - Auto-generated detailed summaries using OpenAI GPT-3.5-turbo
• 💬 AI Chatbot - Interactive Q&A about specific bills
• 🏷️ Intelligent Tags - Multiple categorization for easy discovery
• 📱 Responsive - Works on desktop, tablet, and mobile

---

🚀 Quick Start

Prerequisites

• Java 21 - Download
• Maven 3.6+ - Download
• Node.js 16+ - Download
• OpenAI API Key - Get one

1. Setup OpenAI API Key

Create backend/.env file:

OPENAI_API_KEY=sk-proj-YOUR_API_KEY_HERE

Get your API key from https://platform.openai.com/api-keys

2. Start Backend

cd backend
mvn spring-boot:run

Backend runs on http://localhost:8080

You should see:

✓ Loaded environment variables from .env file
Started BillsApplication in X seconds

3. Start Frontend

cd frontend
npm install
npm run dev

Frontend runs on http://localhost:5173 (or 5174 if 5173 is busy)

4. Open Application

Visit http://localhost:5173 in your browser

---

🎯 Key Features Explained

🤖 AI Summary Generation

When you open a bill detail page:

1. System checks if AI summary exists in database
2. If empty, automatically generates detailed 1 paragraph summary using GPT-3.5-turbo
3. Summary is saved to database for instant future access
4. Cost: ~$0.001 per summary (cached forever after first generation)

What makes it special:

• ✅ Explains what the bill ACTUALLY proposes
• ✅ Describes main provisions and key changes
• ✅ Written in clear, accessible language
• ✅ 200-400 words of detailed content
• ✅ Only generated once, then cached

💬 Interactive Chatbot

Click on any bill to access the AI chatbot:

• Ask questions about the bill
• Get context-aware responses
• Chatbot knows bill details, sponsor, status, etc.
• Powered by GPT-3.5-turbo

Example questions:

• "What is this bill about?"
• "Who sponsored this?"
• "What's the current status?"
• "Explain this in simple terms"

---

📁 Project Structure

Legis-lator/
├── backend/                          # Spring Boot API
│   ├── src/main/java/
│   │   └── com/congress/bills/
│   │       ├── BillsApplication.java         # Main app + .env loader
│   │       ├── controller/
│   │       │   ├── BillController.java       # Bill CRUD endpoints
│   │       │   ├── ChatController.java       # AI chatbot
│   │       │   └── SummaryController.java    # AI summary generation
│   │       ├── model/
│   │       │   └── Bill.java                 # Bill entity
│   │       └── repository/
│   │           └── BillRepository.java       # Database queries
│   ├── .env                          # ⚠️ YOUR API KEY HERE
│   ├── LegisLatorDEMO.db            # Database
│   └── pom.xml                       # Dependencies
│
└── frontend/                         # Vue.js SPA
    ├── src/
    │   ├── components/
    │   │   ├── Bill/                # Bill components
    │   │   │   ├── BillSummary.vue   # AI summary display
    │   │   │   └── ...
    │   │   └── Chatbot/
    │   │       └── Chatbot.vue       # AI chatbot component
    │   ├── pages/                    # Page views
    │   ├── services/
    │   │   └── api.js                # Backend API calls
    │   └── store/                    # State management
    └── package.json

---

🔧 Configuration

Backend Configuration

File: backend/src/main/resources/application.properties

# Server
server.port=8080

# Database
spring.datasource.url=jdbc:sqlite:LegisLatorDEMO.db

# CORS (Frontend URLs)
spring.web.cors.allowed-origins=http://localhost:5173,http://localhost:5174

# OpenAI API Key (loaded from .env)
openai.api.key=${OPENAI_API_KEY}

Frontend Configuration

File: frontend/.env (optional)

VITE_API_URL=http://localhost:8080/api

Defaults to http://localhost:8080/api if not specified.

---

📡 API Endpoints

Bills

• GET /api/bills - Get all bills
• GET /api/bills/{billId} - Get specific bill
• GET /api/bills/search?q={query} - Search bills
• GET /api/bills/tag/{tag} - Filter by tag
• GET /api/bills/stage/{stage} - Filter by stage
• GET /api/bills/recent - Get recent bills

AI Features

• POST /api/chat/message - Send message to AI chatbot
• POST /api/summary/generate - Generate AI summary for bill
• DELETE /api/summary/clear - Clear all summaries (force regeneration)

---

🛠️ Common Tasks

Clear AI Summaries (Force Regeneration)

Windows:

cd backend
.\clear_summaries.ps1

Mac/Linux:

cd backend
chmod +x clear_summaries.sh
./clear_summaries.sh

Or via API:

curl -X DELETE http://localhost:8080/api/summary/clear

Build for Production

Backend:

cd backend
mvn clean package -DskipTests
java -jar target/bills-api-1.0.0.jar

Frontend:

cd frontend
npm run build

Output in frontend/dist/

Change OpenAI Model

File: backend/src/main/java/com/congress/bills/controller/SummaryController.java (line 75)

requestBody.put("model", "gpt-3.5-turbo");  // Change to gpt-4, etc.

File: backend/src/main/java/com/congress/bills/controller/ChatController.java (line 52)

requestBody.put("model", "gpt-3.5-turbo");  // Change to gpt-4, etc.

---

🐛 Troubleshooting

Backend won't start

Problem: Port 8080 already in use
Solution: Change port in application.properties:

server.port=8081

Problem: "OpenAI API key is not configured"
Solution:

1. Check backend/.env exists
2. Verify key format: OPENAI_API_KEY=sk-proj-...
3. Restart backend

Problem: Java version error
Solution: Install Java 21

java -version  # Should show 21.x.x

Frontend won't start

Problem: "Failed to fetch bills"
Solution: Ensure backend is running on port 8080

Problem: CORS errors
Solution: Add your frontend URL to backend's application.properties:

spring.web.cors.allowed-origins=http://localhost:5173

AI Features

Problem: "OpenAI quota exceeded"
Solution:

1. Go to https://platform.openai.com/account/billing
2. Add payment method
3. Add credits ($5-10 recommended)

Problem: "Invalid API key"
Solution:

1. Get new key from https://platform.openai.com/api-keys
2. Update backend/.env
3. Restart backend

Problem: Summaries too short/long
Solution: Adjust max_tokens in SummaryController.java:

requestBody.put("max_tokens", 800);  // Increase/decrease

---

💰 Cost Estimates

OpenAI API Costs

GPT-3.5-turbo Pricing:

• $0.002 per 1,000 tokens

Typical Usage:

• AI Summary: ~600 tokens = $0.001 per bill
• Chatbot message: ~200 tokens = $0.0004 per message

Example Costs:

• 100 bills with summaries: $0.10
• 1,000 chatbot messages: $0.40
• Total for 150 bills + 500 messages: ~$0.35

Free tier: New accounts get $5 in credits (enough for ~5,000 summaries!)

---

🔐 Security Notes

• ✅ API key stored in .env file (gitignored)
• ✅ Key never exposed to frontend
• ✅ Summaries cached in database (no repeated API calls)
• ✅ CORS configured for specific origins only

⚠️ Important: Never commit your .env file to Git!

---

🎓 Tech Stack

Backend

• Java 21
• Spring Boot 3.5.0
• SQLite with JPA/Hibernate
• dotenv-java for environment variables
• RestTemplate for OpenAI API calls

Frontend

• Vue 3 (Composition API)
• Vite (build tool)
• Tailwind CSS (styling)
• Pinia (state management)
• Vue Router (routing)

AI

• OpenAI GPT-3.5-turbo
• Context-aware prompts
• Response caching

---

📚 Additional Resources

• OpenAI API Docs: https://platform.openai.com/docs
• Spring Boot Docs: https://spring.io/projects/spring-boot
• Vue.js Docs: https://vuejs.org/
• Tailwind CSS: https://tailwindcss.com/

---

📝 License

This project is for educational purposes.

---

🙏 Credits

• Bill data structure based on Congress.gov schema
• UI inspired by modern legislative tracking platforms
• AI features powered by OpenAI

---

Ready to explore legislation? Start the servers and visit http://localhost:5173! 🚀