# CharityCare — Beneficiary Management System A clean, production-ready web application for managing charity beneficiary records. Built with **Next.js 15 (App Router)**, **JavaScript**, **MySQL**, **mysql2**, **Tailwind CSS** and **shadcn/ui** style components. ## Features - Add, edit, search, filter, and delete beneficiary records - Month-wise and year-wise filtering based on kit delivery date - Dashboard with live stats (total, kits delivered, pending, this month) - CSV export of the currently filtered dataset - Debounced search, pagination, responsive tables, loading states - Toast notifications and delete confirmation dialogs - Form validation with React Hook Form + Zod - Reusable UI components and a clean folder structure ## Tech Stack | Layer | Tools | | --------- | --------------------------------------------------------------------- | | Frontend | Next.js 15 (App Router), JavaScript, Tailwind CSS, shadcn/ui, RHF, Zod, React Icons | | Backend | Next.js API Routes, mysql2, MySQL | | Libs | mysql2, react-hook-form, zod, papaparse, file-saver, xlsx, date-fns | ## Project Structure ``` app/ page.js # Landing page layout.js # Root layout (Navbar + Toasts) dashboard/page.js # Dashboard beneficiaries/page.js # Listing + search + filters + pagination beneficiaries/add/page.js beneficiaries/edit/[id]/page.js api/ beneficiaries/route.js # GET (list) / POST beneficiaries/[id]/route.js # GET / PUT / DELETE beneficiaries/areas/route.js# Distinct areas for the filter dropdown export/csv/route.js # CSV download components/ Navbar.js Sidebar.js AppShell.js ToastProvider.js BeneficiaryForm.js BeneficiaryTable.js DeleteModal.js DashboardCards.js FiltersBar.js PaginationBar.js EmptyState.js Spinner.js ui/ # shadcn-style primitives hooks/ useDebounce.js lib/ db.js validation.js csv.js filters.js constants.js format.js utils.js database/ schema.sql scripts/ seed.js create-user.js ``` ## Setup Prerequisites: Node.js 18.18+ and a running MySQL server. ```bash # 1. Create the app from scratch (already done in this repo) npx create-next-app@latest charity-management --js --app --tailwind --no-src-dir # 2. Install dependencies npm install npm install mysql2 react-hook-form zod papaparse file-saver xlsx date-fns react-icons npm install @hookform/resolvers @radix-ui/react-dialog @radix-ui/react-select @radix-ui/react-slot @radix-ui/react-label @radix-ui/react-separator clsx tailwind-merge class-variance-authority # 3. Configure the database connection # Edit .env and point DB_HOST / DB_PORT / DB_USER / DB_PASSWORD / DB_NAME # at your MySQL instance, e.g. # DB_HOST=localhost # DB_PORT=3306 # DB_USER=root # DB_PASSWORD=yourpassword # DB_NAME=charity_management # 4. Create the database and apply the schema # mysql -u root -p -e "CREATE DATABASE charity_management CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci" # mysql -u root -p charity_management < database/schema.sql # 5. (Optional) Seed sample data and create users npm run db:seed npm run user:create -- [full name] [USER|ADMIN] # 6. Run the development server npm run dev ``` Open http://localhost:3000 ### Useful scripts ```bash npm run dev # Start the dev server npm run build # Production build npm run start # Run the production build npm run lint # ESLint npm run db:seed # Seed sample data npm run user:create # Create a user (admin or normal) ``` ## API Routes | Method | Endpoint | Description | | -------- | ------------------------- | --------------------------------- | | GET | `/api/beneficiaries` | List with search, filters, pagination | | POST | `/api/beneficiaries` | Create a beneficiary | | GET | `/api/beneficiaries/:id` | Fetch a single beneficiary | | PUT | `/api/beneficiaries/:id` | Update a beneficiary | | DELETE | `/api/beneficiaries/:id` | Delete a beneficiary | | GET | `/api/beneficiaries/areas`| Distinct areas for filters | | GET | `/api/export/csv` | Download filtered records as CSV | Query parameters for list/export endpoints: `search`, `area`, `status`, `caste`, `month` (1–12), `year`, `page`, `pageSize`. ## Database Table: `beneficiaries` | Column | Type | Notes | | ----------------- | --------------- | --------------------------------- | | id | Int (PK, auto) | | | area | String | required | | serialNo | Int (unique) | auto-incrementing sequence number | | surveyName | String | required | | name | String | required | | fatherName | String | required | | age | Int | required, validated 0–120 | | caste | String | STHA / DERAVASI / OTHER | | status | String | Widow / Disabled / Senior Citizen / Orphan / Poor Family / Other | | kitDeliveredDate | Date? | optional | | remarks | Text? | optional | | createdAt / updatedAt | DateTime | auto-managed | ## Deployment Guide ### Vercel (recommended) 1. Push the repository to GitHub. 2. Import the project at https://vercel.com/new. 3. Add the environment variables `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD` and `DB_NAME` pointing to your MySQL database (use a managed provider like PlanetScale, Railway, Aiven, or a VPS-hosted MySQL). 4. Deploy. Make sure the `database/schema.sql` has been applied to your production database first. ### Traditional server (Node + PM2) ```bash # On the server git clone charity-management cd charity-management npm install # Apply the schema to your production database first mysql -u -p charity_management < database/schema.sql npm run build # Configure DB_HOST / DB_PORT / DB_USER / DB_PASSWORD / DB_NAME in .env, then start npm run start # or with PM2 pm2 start "npm run start" --name charity-management ``` Tip: the production build serves the dashboard as dynamic content, so it always reflects the latest records. # charitymanagement