v1.4.1

.env.example

@@ -1,6 +1,11 @@
 # Database
-DATABASE_URL="postgresql://user:password@host:port/database"
-DIRECT_URL="postgresql://user:password@host:port/database"
+# For local development with Docker (see README.md "Local Development Database" section)
+DATABASE_URL="postgresql://postgres:postgres@localhost:5432/senate_path_dev?schema=public"
+DIRECT_URL="postgresql://postgres:postgres@localhost:5432/senate_path_dev?schema=public"
+
+# For production (Supabase or other hosted PostgreSQL)
+# DATABASE_URL="postgresql://user:password@host:port/database"
+# DIRECT_URL="postgresql://user:password@host:port/database"
 
 # Supabase
 NEXT_PUBLIC_SUPABASE_URL="your-supabase-url"

.github/copilot-instructions.md

@@ -0,0 +1,124 @@
+# GitHub Copilot Instructions for Next.js Project
+
+## Commit & Branch Naming Conventions
+
+### Commits
+- **Format**: `#XXX commit message in lowercase imperative mood`
+- **Examples**:
+  - `#123 add user authentication flow`
+  - `#456 fix navigation menu overflow`
+  - `#789 refactor payment processing logic`
+- **Rules**:
+  - Always prefix with issue number
+  - Use lowercase only
+  - Use imperative mood (add, fix, refactor, not added, fixed, refactored)
+  - No colon after issue number
+
+### Branches
+- **Format**: `XXX-ticket-name-in-kebab-case`
+- **Examples**:
+  - `123-add-user-authentication`
+  - `456-fix-navigation-overflow`
+  - `789-refactor-payment-processing`
+
+### Pull Requests
+- **Format**: `#XXX Ticket Name In Title Case`
+- **Examples**:
+  - `#123 Add User Authentication`
+  - `#456 Fix Navigation Overflow`
+  - `#789 Refactor Payment Processing`
+
+## Tech Stack
+
+- **Framework**: Next.js with App Router
+- **Database**: Prisma ORM
+- **Styling**: Tailwind CSS
+- **UI Components**: shadcn/ui
+- **Language**: TypeScript (strict mode)
+
+## Architecture & Patterns
+
+### API Layer
+- **NEVER use API routes** (`app/api/` directory)
+- **ALWAYS use Server Actions** for data mutations
+- **Use server components** for data fetching with Prisma calls
+- Import Prisma queries from separate service/repository files
+
+### Component Structure
+- Components live in centralized `components/` directory
+- Organize into subdirectories as needed:
+```
+  components/
+    ├── ui/           # shadcn components
+    ├── forms/        # form-related components
+    ├── layouts/      # layout components
+    └── features/     # feature-specific shared components
+```
+- Keep components focused and composable
+
+### TypeScript
+- Use TypeScript strict mode
+- Define proper types for all props and function parameters
+- Avoid `any` type
+- Prefer interfaces for component props
+- Use Prisma-generated types where applicable
+
+### Server Actions
+- Define server actions in separate files (e.g., `actions/user-actions.ts`)
+- Always use `'use server'` directive
+- Include proper error handling and validation
+- Return typed responses
+
+### Data Access
+- All database operations go through Prisma
+- Create service/repository files for complex queries
+- Keep Prisma calls in server components or server actions only
+- Never expose database calls to client components
+
+### File Organization
+```
+app/
+  ├── (routes)/           # route groups
+components/               # shared components
+lib/
+  ├── actions/           # server actions
+  ├── data/              # data queries and services
+  ├── db.ts              # Prisma client
+  └── utils.ts           # utility functions
+```
+
+## Code Style Preferences
+
+- Use named exports over default exports in all cases
+- Prefer functional components with hooks
+- Use async/await over promises
+- Implement proper loading and error states
+- Use Tailwind classes, avoid custom CSS unless absolutely necessary
+- Follow shadcn/ui patterns for component composition
+
+## Best Practices
+
+1. **Server vs Client Components**:
+   - Default to server components
+   - Only use `'use client'` when needed (interactivity, hooks, browser APIs)
+
+2. **Data Fetching**:
+   - Fetch data in server components
+   - Use Prisma for all database queries
+   - Implement proper error boundaries
+
+3. **Forms**:
+   - Use Server Actions for form submissions
+   - Implement progressive enhancement
+   - Add proper validation (client + server)
+
+4. **Performance**:
+   - Leverage Next.js caching strategies
+   - Use `revalidatePath` or `revalidateTag` after mutations
+   - Optimize images with next/image
+
+5. **Security**:
+   - Validate all inputs
+   - Never expose sensitive data to client
+   - Use environment variables for secrets
+

README.md

@@ -62,8 +62,9 @@ The application manages three main entities:
    - To check if it's installed: `node -v`
    - To install: [mac/linux](https://github.com/nvm-sh/nvm) or [windows](https://github.com/coreybutler/nvm-windows)
 
-2. [PostgreSQL](https://www.postgresql.org/download/) database
-   - Local installation or cloud service (Supabase, Neon, etc.)
+2. [Docker Desktop](https://www.docker.com/products/docker-desktop/) (for local database)
+   - Required for running the local PostgreSQL database
+   - To check if it's installed: `docker --version`
 
 ### Installation
 
@@ -83,7 +84,9 @@ npm install
 cp .env.example .env.local
 ```
 
-Edit `.env.local` and add your database connection strings and Supabase credentials:
+The `.env.example` file comes pre-configured with local database settings. For local development, you can use these defaults as-is.
+
+For production or if you want to use a different database:
 ```
 DATABASE_URL="postgresql://user:password@host:port/database"
 DIRECT_URL="postgresql://user:password@host:port/database"
@@ -98,11 +101,114 @@ To get your Supabase credentials:
 - Copy the Project URL and anon/public key
 - Copy the service_role key (this is needed for user management - keep it secret!)
 
-4. Generate Prisma client and run migrations:
+## Local Development Database
+
+This project uses Docker to run a local PostgreSQL database for development. This allows you to test database schema changes locally before deploying to production.
+
+### Prerequisites
+
+- [Docker Desktop](https://www.docker.com/products/docker-desktop/) must be installed and running
+- Ensure port 5432 is available on your machine
+
+### Initial Setup
+
+1. Make sure you have copied `.env.example` to `.env.local`:
+```bash
+cp .env.example .env.local
+```
+
+The default local database connection is already configured in `.env.example`:
+```
+DATABASE_URL="postgresql://postgres:postgres@localhost:5432/senate_path_dev?schema=public"
+DIRECT_URL="postgresql://postgres:postgres@localhost:5432/senate_path_dev?schema=public"
+```
+
+2. Start the local PostgreSQL database:
+```bash
+npm run db:start
+```
+
+3. Run Prisma migrations to create the database schema:
+```bash
+npm run prisma:migrate
+```
+
+You're now ready to develop! The local database will persist data between restarts.
+
+### Common Commands
+
+| Command | Description |
+|---------|-------------|
+| `npm run db:start` | Start the Docker PostgreSQL container in the background |
+| `npm run db:stop` | Stop the Docker container (data is preserved) |
+| `npm run db:reset` | Stop container, remove all data, start fresh, and run migrations |
+| `npm run prisma:migrate` | Create and apply a new Prisma migration (will prompt for migration name) |
+| `npm run prisma:studio` | Open Prisma Studio to visually browse and edit your local database |
+| `npm run prisma:generate` | Regenerate Prisma client after schema changes |
+
+### Development Workflow
+
+1. Create a new branch for your work:
+```bash
+git checkout -b 123-add-new-feature
+```
+
+2. Start the local database (if not already running):
+```bash
+npm run db:start
+```
+
+3. Make changes to your Prisma schema in `prisma/schema.prisma`
+
+4. Create and apply the migration:
 ```bash
-npm run prisma:generate
 npm run prisma:migrate
 ```
+Prisma will prompt you for a migration name (e.g., "add_user_role_field")
+
+5. Test your changes locally using Prisma Studio or your application:
+```bash
+npm run prisma:studio  # Visual database browser
+npm run dev            # Start Next.js dev server
+```
+
+6. Commit both your schema changes AND the migration files:
+```bash
+git add prisma/schema.prisma prisma/migrations/
+git commit -m "#123 add new feature"
+git push
+```
+
+### Troubleshooting
+
+**Port 5432 already in use**
+- Mac/Linux: Check if PostgreSQL is running: `sudo lsof -i :5432`
+- Windows: Check port usage: `netstat -ano | findstr :5432`
+- Stop the existing PostgreSQL service or change the port in `docker-compose.yml`
+
+**Container won't start**
+- Make sure Docker Desktop is running
+- Check Docker logs: `docker logs senate-path-db`
+- Try removing the container: `docker compose down -v` then `npm run db:start`
+
+**Database connection errors**
+- Verify the container is running: `docker ps`
+- Check your `.env.local` file has the correct `DATABASE_URL`
+- Try restarting the container: `npm run db:stop && npm run db:start`
+
+**Need to start fresh**
+- Use `npm run db:reset` to completely reset your local database
+- This will delete all data and re-run migrations
+
+**Migration conflicts**
+- If you have uncommitted migrations, you may need to reset: `npm run db:reset`
+- Delete problematic migration folders from `prisma/migrations/` and re-create them
+
+### Database Deployment Notes
+
+- Local database is completely separate from production/staging databases
+- Migration files in `prisma/migrations/` are version controlled
+- Migrations run automatically on deployment when merged to `dev` or `main` branches
 
 ## Running the app
 
@@ -121,12 +227,21 @@ npm start
 
 ## Available Scripts
 
+### Development
 - `npm run dev` - Start development server
 - `npm run build` - Build for production
 - `npm start` - Start production server
 - `npm run lint` - Run ESLint
+
+### Database Management
+- `npm run db:start` - Start local Docker PostgreSQL container
+- `npm run db:stop` - Stop local Docker container
+- `npm run db:reset` - Reset local database (removes all data and re-runs migrations)
+
+### Prisma
 - `npm run prisma:generate` - Generate Prisma client
-- `npm run prisma:migrate` - Run database migrations
+- `npm run prisma:migrate` - Create and apply database migrations
+- `npm run prisma:studio` - Open Prisma Studio for database inspection
 
 ## Key Features
 

app/admin/settings/settings-form.tsx

@@ -4,6 +4,7 @@ import { useState } from 'react';
 import { useForm } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
 import { z } from 'zod';
+import { useRouter } from 'next/navigation';
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
@@ -49,6 +50,7 @@ interface SettingsFormProps {
 }
 
 export default function SettingsForm({ settings }: SettingsFormProps) {
+  const router = useRouter();
   const [isSubmitting, setIsSubmitting] = useState(false);
   const [error, setError] = useState<string | null>(null);
 
@@ -101,6 +103,7 @@ export default function SettingsForm({ settings }: SettingsFormProps) {
 
       if (result.success) {
         toast.success('Settings updated successfully!');
+        router.refresh();
       } else {
         setError(result.error || 'Failed to update settings');
       }

docker-compose.yml

@@ -0,0 +1,20 @@
+services:
+  postgres:
+    image: postgres:15-alpine
+    container_name: senate-path-db
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: senate_path_dev
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  postgres_data: