Full-stack shelter operations platform with AI-powered case management

Context

Shelters face fragmented systems for managing resident intake, service requests, and operations. Staff need real-time visibility into occupancy, maintenance issues, and client status; residents need accessible channels to report problems and access services; administrators need reporting and analytics to demonstrate impact. This platform unifies all workflows in a single, role-based interface with automated insights.

Approach

Built as a Next.js fullstack app with server and client components colocated by feature. Authentication uses custom JWT tokens signed with HS256, validated via middleware for protected dashboard routes and per-endpoint via `withAuth()` wrapper pattern. Data modeling in Prisma v6 (v7 incompatible with legacy schema) maps to MongoDB collections with proper ObjectId handling. API routes implement role-based authorization (client/staff/admin) with dedicated endpoints for each role — 92+ routes handling intake forms, grievances, maintenance requests, meal coordination, and daily sign-ins. File uploads toggle between local storage (`/public/uploads`) and Vercel Blob based on env config. OpenAI integration generates personalized housing plans and service referral suggestions using GPT-3.5-turbo, with fallback suggestions for resilience. Frontend uses 55 pre-installed shadcn/ui components with Tailwind CSS 4 for responsive design across three dashboard types. Form handling with React Hook Form + Zod validation reduces boilerplate. Framer Motion handles animations with `type: "spring" as const` pattern. Notional layer with custom `ClientActivity` collection (raw MongoDB, not Prisma) for audit logging. Email notifications via Nodemailer for form submissions and staff responses.

Outcome

Operational: Residents can submit referral requests, grievances, and maintenance tickets with real-time status tracking; staff can process and respond to requests with signature capture and cost tracking; admins see occupancy analytics, request trends, and client demographics via Chart.js dashboards. AI-driven personalization through generated housing plans and referral suggestions. Integrated file uploads with photo evidence for maintenance and PDF receipt tracking. Daily sign-in sheets for billing and meal coordination with household declarations.

What it does

• 0192 API endpoints across 4 role-based route groups (admin, staff, client, public) with granular authorization
• 0214 Prisma models covering 200+ intake form fields, shelter capacity tracking, multi-level grievance workflows, and maintenance cost accounting
• 03120+ React components including 35 admin-specific dashboard components, form builders for 8+ complex forms, and signature/image capture UI