Free, modern case management for immigration attorneys tracking Permanent Labor Certification (PERM) cases.
Test Credentials: See v2/.env (gitignored)
Deadline Hub showing overdue, upcoming, and future deadlines at a glance
Case management with filtering, search, status badges, and calendar sync
Calendar view with deadline color-coding and AI chat assistant for natural language case management
- Full CRUD with real-time sync, duplicate detection, bulk operations
- Smart date validation per 20 CFR 656.40(c) regulations
- Auto-calculations (PWD expiration, ETA 9089 windows, I-140 deadlines)
- Cascade logic - dependent dates auto-calculate
- RFI/RFE tracking with due dates
- Real-time case counts, upcoming deadlines, recent activity
- Timeline visualization with milestone tracking
- Calendar view with deadline color coding
- Privacy mode for screen sharing
- Dark/light mode, responsive design, PWA support
- In-app notification bell with unread badge
- Email notifications via Resend
- Push notifications via Web Push
- Daily deadline reminders (cron), weekly digest
- Natural language case queries and updates
- Multi-provider fallback (Gemini, OpenRouter, Groq, Cerebras)
- Web search integration for PERM regulations
- Tool confirmation for destructive actions
- One-click OAuth connection
- Automatic deadline event creation
- Bulk sync for all cases
| Layer | Technology |
|---|---|
| Frontend | Next.js 16 + React + TypeScript |
| Backend | Convex (serverless functions) |
| Database | Convex (built-in) |
| Styling | Tailwind CSS + shadcn/ui |
| Authentication | Convex Auth + Google OAuth |
| Resend | |
| Push Notifications | Web Push (VAPID) |
| Hosting | Vercel (frontend) + Convex Cloud (backend) |
- Node.js 18+
- pnpm (recommended) or npm
# Navigate to v2 directory
cd v2
# Install dependencies
pnpm install
# Start Convex dev server (Terminal 1)
npx convex dev
# Start Next.js dev server (Terminal 2)
pnpm devLocal URLs:
- Frontend: http://localhost:3000
- Convex Dashboard: https://dashboard.convex.dev
Copy .env.example to .env.local and fill in values:
# Convex
CONVEX_DEPLOYMENT=dev:your-deployment
NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud
# Google OAuth
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
# Push Notifications
NEXT_PUBLIC_VAPID_PUBLIC_KEY=your_vapid_public_keyServer-side secrets (Convex Dashboard):
RESEND_API_KEY- Email deliveryVAPID_PRIVATE_KEY- Push notificationsJWT_PRIVATE_KEY- Auth tokens
| Command | Description | Time |
|---|---|---|
pnpm test |
Watch mode (development) | Instant |
pnpm test:fast |
Unit + PERM tests only | ~30s |
pnpm test:run |
Full suite (CI) | ~9 min |
pnpm test:e2e |
Playwright E2E tests | ~2 min |
- 3600+ tests passing
- 100% coverage on PERM business logic
- Component, hook, and integration tests included
v2/
├── convex/ # Convex backend
│ ├── lib/perm/ # Central PERM business logic
│ ├── cases.ts # Case CRUD
│ ├── notifications.ts # Notifications
│ ├── scheduledJobs.ts # Cron jobs
│ └── schema.ts # Database schema
├── src/
│ ├── app/ # Next.js pages
│ ├── components/ # React components
│ └── lib/perm/ # Frontend re-exports
└── test-utils/ # Test utilities
- v2/CLAUDE.md - Developer guide with API reference
- perm_flow.md - PERM process workflow (canonical source)
- .planning/ - Architecture and planning docs
Push to main branch triggers:
- Vercel: Frontend rebuild and deploy
- Convex: Backend functions sync
git add .
git commit -m "feat: your feature"
git push origin maincd v2
npx convex deploy --prod- Convex Auth - Secure session management
- Row-Level Security - Users only access their own data
- HTTPS - Enforced in production
- Activity Timeout - Auto-logout after inactivity
This project is free to use for immigration attorneys and law firms.
- DOL PERM Program: https://flag.dol.gov/programs/perm
- 20 CFR 656.40: PERM regulations
- Convex: Serverless backend platform
- Vercel: Frontend hosting
Built with Claude Code Last Updated: January 2026 Version: 2.0