# Careers System Documentation

Complete documentation for the Mawidi careers page and job application system.

---

## Documentation Files

### 📋 [IMPLEMENTATION_SUMMARY.md](./IMPLEMENTATION_SUMMARY.md)

**Comprehensive implementation overview**

- Research findings and best practices
- Implementation details for all components
- Testing results with Playwright MCP
- Known issues and solutions
- Production upgrade guide
- File structure and maintenance notes

**Use this for**: Understanding what was built and why

### 🚀 [QUICK_REFERENCE.md](./QUICK_REFERENCE.md)

**Fast access guide for common tasks**

- Adding/removing jobs (code snippets)
- Testing locally
- Troubleshooting common issues
- Helper functions usage
- Quick commands

**Use this for**: Day-to-day maintenance and updates

### 🔧 [TECHNICAL_SPEC.md](./TECHNICAL_SPEC.md)

**Detailed technical specification**

- Architecture and component hierarchy
- Data flow diagrams
- Type definitions and schemas
- API contract specifications
- Security measures
- Performance metrics
- Testing strategies

**Use this for**: Technical implementation details and architecture decisions

---

## Quick Start

### View the Careers Page

```bash
npm run dev
# Open: http://localhost:9000/en/careers
```

### Add a New Job

1. Ensure Supabase CLI is linked and migrations applied (`supabase migration up`)
2. Insert a new row into the `jobs` table (Supabase Studio or SQL)
3. Provide translations, benefits, and dates; set `status = 'open'`
4. Refresh `/en/careers` – listings auto-refresh from Supabase

### Test Application Flow

1. Click "Apply Now" on any job
2. Fill form (name, email, phone, upload PDF)
3. Submit
4. Confirm new row exists in `job_applications` table and CV stored in `job-cvs`

---

## File Locations

```
supabase/
├── migrations/…                ← Careers + jobs schema & policies
├── seed.sql                    ← Default careers/jobs seed data

app/[lang]/careers/
├── page.tsx                    ← Server component loads Supabase data
└── CareersClient.tsx           ← Interactive client component

app/api/apply-job/
└── route.ts                    ← Uploads PDFs + inserts job applications

lib/
├── careers.ts                  ← Supabase fetch helpers (public client)
└── supabase.ts                 ← Client/admin helpers & storage config

claudedocs/careers/             ← This documentation folder
├── README.md                   ← This file
├── IMPLEMENTATION_SUMMARY.md
├── QUICK_REFERENCE.md
└── TECHNICAL_SPEC.md
```

---

## Implementation Status

✅ **Complete (Database-backed MVP)**

- Supabase migrations + seed data for careers & jobs
- 4 sample bilingual roles stored in Postgres
- Application modal uploads PDFs to `job-cvs` bucket
- API persists submissions to `job_applications`
- Bilingual support (AR/EN) with translation fallbacks
- Mobile-responsive design, improved validation

🚧 **Next Enhancements**

- Email integration (Resend or SMTP)
- Admin dashboard for reviewing applications
- Automated close of roles past `closing_at`
- Analytics + notifications for new submissions
- Rate limiting / CAPTCHA hardening

---

## Key Features

### Job Listings

- Supabase-powered listings (filter by status/opening & closing dates)
- 4 departments represented in default seed
- Salary transparency + bilingual metadata
- Department badges and dynamic sections (benefits, skills, workday)

### Application System

- 7-field form (4 required, 3 optional)
- PDF resume upload (max 10 MB)
- Client validation + server enforcement (MIME-size checks)
- CV stored privately in Supabase storage
- Submissions recorded in `job_applications` with metadata
- Success/error feedback and auto-dismiss modal

### Technical Notes

- Supabase public client for read, admin client for writes
- Row Level Security ensures public read / insert-only behaviour
- Dedicated storage bucket `job-cvs` with service-role policies
- Translation fallbacks handled in `lib/careers.ts`
- Doc + test plan covering Playwright + manual QA

---

## Support

### For Implementation Questions

- See [TECHNICAL_SPEC.md](./TECHNICAL_SPEC.md)
- Check [IMPLEMENTATION_SUMMARY.md](./IMPLEMENTATION_SUMMARY.md)

### For Maintenance Tasks

- See [QUICK_REFERENCE.md](./QUICK_REFERENCE.md)

### For Troubleshooting

- See [QUICK_REFERENCE.md](./QUICK_REFERENCE.md) → Troubleshooting section
- See [IMPLEMENTATION_SUMMARY.md](./IMPLEMENTATION_SUMMARY.md) → Known Issues

---

## Version History

**v2.0.0** (October 15, 2025)

- Migrated careers page to Supabase
- Added storage-backed CV uploads
- Updated documentation & test plan
- Playwright MCP testing completed

---

## Next Steps

### Immediate (This Week)

1. Test in production build
2. Fix webpack development mode error (if needed)
3. Add email integration (Resend)
4. Test email delivery

### Short Term (Next 2 Weeks)

1. Database storage implementation
2. Admin dashboard for viewing applications
3. Rate limiting on submissions
4. Enhanced error handling

### Long Term (Next Month+)

1. Full ATS system with status tracking
2. Applicant portal for status checks
3. Interview scheduling integration
4. Team collaboration features
5. AI-powered resume screening

---

## Credits

**Implementation Date**: October 15, 2025
**Research Sources**:

- Indeed.com (job posting best practices)
- BambooHR (application form optimization)
- Industry standards (2025 hiring trends)

**Technologies Used**:

- Next.js 14 App Router
- TypeScript
- React (Client Components)
- Tailwind CSS
- Playwright MCP (testing)

**Architecture Pattern**: Following existing Mawidi project structure
