name: hr_my_app description: HR.my - Enterprise HR Management Platform (Flutter + Supabase) starter publish_to: 'none' version: 0.1.0+1 environment: sdk: '>=3.0.0 <4.0.0' dependencies: flutter: sdk: flutter cupertino_icons: ^1.0.5 flutter_localizations: sdk: flutter intl: ^0.18.0 flutter_bloc: ^8.1.2 equatable: ^2.0.5 supabase_flutter: ^1.5.0 flutter_secure_storage: ^9.0.0 dev_dependencies: flutter_test: sdk: flutter flutter_lints: ^2.0.1 flutter: uses-material-design: true assets: - assets/i18n/en.json - assets/i18n/ar.json fonts: - family: Roboto fonts: - asset: assets/fonts/Roboto-Regular.ttf generate: true module: false web: renderer: html # add additional platform configuration as needed # keep this pubspec minimal for the starter import 'package:flutter/material.dart'; import 'package:supabase_flutter/supabase_flutter.dart'; import 'app.dart'; import 'src/core/app_config.dart'; import 'src/data/supabase_client.dart'; Future main() async { WidgetsFlutterBinding.ensureInitialized(); // Initialize Supabase await SupabaseClientProvider.init( url: AppConfig.supabaseUrl, anonKey: AppConfig.supabaseAnonKey, ); runApp(const MyApp()); } import 'package:flutter/material.dart'; import 'package:flutter_localizations/flutter_localizations.dart'; import 'src/presentation/screens/home_page.dart'; import 'src/core/app_config.dart'; class MyApp extends StatefulWidget { const MyApp({super.key}); @override State createState() => _MyAppState(); } class _MyAppState extends State { Locale _locale = AppConfig.defaultLocale; void _setLocale(Locale locale) { setState(() { _locale = locale; }); } @override Widget build(BuildContext context) { return MaterialApp( title: 'HR.my', debugShowCheckedModeBanner: false, theme: ThemeData( primarySwatch: Colors.indigo, useMaterial3: true, ), locale: _locale, supportedLocales: const [Locale('en'), Locale('ar')], localizationsDelegates: const [ GlobalMaterialLocalizations.delegate, GlobalWidgetsLocalizations.delegate, GlobalCupertinoLocalizations.delegate, ], home: HomePage(onLocaleChange: _setLocale), ); } } import 'package:flutter/material.dart'; class AppConfig { // Replace these with your Supabase project values before running static const String supabaseUrl = 'https://your-supabase-project.supabase.co'; static const String supabaseAnonKey = 'your-public-anon-key'; // Default locale for the app (can be toggled in UI) static const Locale defaultLocale = Locale('en'); // App-level constants for roles static const String roleAdmin = 'admin'; static const String roleHR = 'hr'; static const String roleManager = 'manager'; static const String roleEmployee = 'employee'; } import 'package:supabase_flutter/supabase_flutter.dart'; /// Simple Supabase initializer and provider for the app. /// This singleton wraps basic Supabase initialization and provides /// a single access point for the Supabase client. class SupabaseClientProvider { static late final SupabaseClient _client; static bool _initialized = false; static Future init({ required String url, required String anonKey, }) async { if (_initialized) return; await Supabase.initialize( url: url, anonKey: anonKey, // Optional: add debug or auth settings here ); _client = Supabase.instance.client; _initialized = true; } static SupabaseClient get client { if (!_initialized) { throw StateError('SupabaseClientProvider not initialized. Call init() first.'); } return _client; } } import 'package:equatable/equatable.dart'; /// Basic Employee domain model. This is a minimal example and should /// be extended with many more fields for a real HR system. class Employee extends Equatable { final String id; final String firstName; final String lastName; final String email; final String? phone; final String? positionId; final String? departmentId; final DateTime? hireDate; const Employee({ required this.id, required this.firstName, required this.lastName, required this.email, this.phone, this.positionId, this.departmentId, this.hireDate, }); factory Employee.fromJson(Map json) { return Employee( id: json['id'] as String, firstName: json['first_name'] as String, lastName: json['last_name'] as String, email: json['email'] as String, phone: json['phone'] as String?, positionId: json['position_id'] as String?, departmentId: json['department_id'] as String?, hireDate: json['hire_date'] != null ? DateTime.parse(json['hire_date'] as String) : null, ); } Map toJson() { return { 'id': id, 'first_name': firstName, 'last_name': lastName, 'email': email, 'phone': phone, 'position_id': positionId, 'department_id': departmentId, 'hire_date': hireDate?.toIso8601String(), }; } @override List get props => [id, firstName, lastName, email]; } import 'package:flutter/material.dart'; import 'package:supabase_flutter/supabase_flutter.dart'; import '../../data/supabase_client.dart'; import '../../domain/models/employee.dart'; import '../../core/app_config.dart'; class HomePage extends StatefulWidget { final void Function(Locale) onLocaleChange; const HomePage({super.key, required this.onLocaleChange}); @override State createState() => _HomePageState(); } class _HomePageState extends State { final SupabaseClient _supabase = SupabaseClientProvider.client; String _status = 'idle'; Future _fetchCurrentUser() async { setState(() => _status = 'loading'); try { final user = _supabase.auth.currentUser; if (user == null) { setState(() => _status = 'not authenticated'); return; } // Example: fetch employee by user id from employees table final res = await _supabase .from('employees') .select() .eq('auth_uid', user.id) .maybeSingle() .execute(); if (res.error != null) { setState(() => _status = 'error: ${res.error!.message}'); return; } final data = res.data as Map?; if (data == null) { setState(() => _status = 'employee not found'); return; } final employee = Employee.fromJson(data); setState(() => _status = 'Hello, ${employee.firstName} ${employee.lastName}'); } catch (e) { setState(() => _status = 'exception: $e'); } } void _toggleLocale() { final current = WidgetsBinding.instance.platformDispatcher.locale; final newLocale = (current.languageCode == 'ar') ? const Locale('en') : const Locale('ar'); widget.onLocaleChange(newLocale); } @override Widget build(BuildContext context) { final isRtl = Directionality.of(context) == TextDirection.rtl; return Directionality( textDirection: isRtl ? TextDirection.rtl : TextDirection.ltr, child: Scaffold( appBar: AppBar( title: const Text('HR.my'), actions: [ IconButton( tooltip: 'Toggle Locale', onPressed: _toggleLocale, icon: const Icon(Icons.language), ), PopupMenuButton( onSelected: (value) { // Simple role switch stub for demo/testing // In a real app use proper auth and RBAC checks ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text('Switched role: $value'))); }, itemBuilder: (context) => [ const PopupMenuItem(value: AppConfig.roleAdmin, child: Text('Admin')), const PopupMenuItem(value: AppConfig.roleHR, child: Text('HR')), const PopupMenuItem(value: AppConfig.roleManager, child: Text('Manager')), const PopupMenuItem(value: AppConfig.roleEmployee, child: Text('Employee')), ], ), ], ), body: Padding( padding: const EdgeInsets.all(16), child: Column( crossAxisAlignment: CrossAxisAlignment.start, children: [ Text('Status: $_status'), const SizedBox(height: 16), ElevatedButton.icon( onPressed: _fetchCurrentUser, icon: const Icon(Icons.person_search), label: const Text('Fetch Current Employee'), ), const SizedBox(height: 8), ElevatedButton.icon( onPressed: () async { // Demo sign in anonymously (for development only) setState(() => _status = 'signing in anonymously...'); final res = await _supabase.auth.signInWithOtp(email: 'dev@example.com'); if (res.hasError) { setState(() => _status = 'sign-in error: ${res.error!.message}'); } else { setState(() => _status = 'check email for magic link'); } }, icon: const Icon(Icons.login), label: const Text('Demo Sign-In'), ), const SizedBox(height: 24), const Text('Starter notes:'), const SizedBox(height: 8), const Text('- Replace Supabase keys in lib/src/core/app_config.dart'), const Text('- Create tables: users, employees, departments, payroll_runs'), const Text('- Enable Row-Level Security and add RLS policies for RBAC'), ], ), ), ), ); } } # HR.my - Flutter & Supabase Starter (Unified Prompt) This repository contains a minimal Flutter starter application structured for building the HR.my enterprise HR management platform (Flutter frontend + Supabase backend). The full, unified project prompt and requirements (to be used as the precise product specification for development) are included below. --- # Comprehensive Prompt for a Complete Enterprise HR Management System (HR.my) Design and develop a complete, enterprise-level HR management platform. The system will feature all core HR functions, seamless module integration, advanced reporting, and be fully compliant with regional labor laws for Egypt, Saudi Arabia, and the Gulf countries. The application will be built with a Flutter frontend and a Supabase backend, prioritizing enterprise-grade security, scalability, and an intuitive user experience with full RTL/Arabic support. ## 🎯 Project Goals * **Develop a unified HR ecosystem:** Integrate all HR subsystems (employee management, payroll, attendance, leave, performance, recruitment, etc.) into a single, cohesive platform. * **Ensure regional compliance:** Implement specific labor law rules and reporting for Egypt, Saudi Arabia, and the Gulf countries (UAE, Qatar, Bahrain, Kuwait, Oman). * **Achieve enterprise-grade standards:** Build with robust security, high availability, and scalability in mind. * **Provide a superior user experience:** Offer a modern, responsive, and role-specific interface with bilingual (English/Arabic) support. --- ## 🏢 System Modules ### 1. Authentication & Security * **Multi-role login:** Differentiate between Employee, Manager, HR, and Admin roles. * **Advanced authentication:** Implement Two-factor authentication (2FA) and biometric login. * **Session management:** Securely manage user sessions. * **Role-Based Access Control (RBAC):** Granular access control for all modules and data based on user roles. * **Audit logging:** Log all user and system actions for accountability. ### 2. Employee Management * **Centralized employee database:** Complete profiles including personal details, contact information, employment history, and skills. * **Organizational hierarchy:** Define and visualize departments, positions, and reporting structures. * **Documents management:** Securely store and manage employee documents with expiration alerts. ### 3. Payroll Management * **Flexible salary configuration:** Define salary structures, allowances, deductions, and pay grades. * **Automated payroll processing:** Calculate salaries, taxes, social insurance (GOSI, etc.), and end-of-service benefits based on regional laws. * **Payment & reimbursement:** Manage payment history, generate payslips, and process reimbursements. ### 4. Attendance & Time Tracking * **Real-time tracking:** Implement a clock-in/clock-out system. * **Biometric device integration:** Support for devices like ZKTeco and FingerTec with real-time sync, device health monitoring, and bulk enrollment. * **Geofencing:** Verify location for attendance records. * **Timesheet & workflow:** Allow for overtime tracking and timesheet approval workflows. ### 5. Leave Management * **Comprehensive leave types:** Configure and track various leave types (annual, sick, maternity, etc.). * **Automated workflows:** Implement an approval/rejection system for leave applications. * **Accrual & balance:** Track leave balances and automated accrual systems based on policies. * **Holiday calendar:** Support both Gregorian and Hijri calendars. ### 6. Performance Management * **Goal & KPI tracking:** Set, track, and manage employee goals and key performance indicators. * **Performance reviews:** Conduct performance reviews with 360-degree feedback and competency assessments. * **Career development:** Plan and track training needs and career development paths. ### 7. Recruitment & Onboarding * **Applicant tracking system (ATS):** Manage job postings, applications, and candidate pipelines. * **Interview scheduling:** Automate interview scheduling and candidate evaluation. * **Onboarding workflow:** Define and manage onboarding checklists and tasks for new hires. ### 8. Reports & Analytics * **Custom report builder:** A drag-and-drop interface for creating custom reports. * **Pre-built reports:** Include compliance reports for each target region (Egypt, Saudi, Gulf), payroll, and attendance. * **Data visualization:** Dashboards with key HR metrics and analytics. * **Export & printing:** Export capabilities to PDF, Excel, and Word, with custom print templates. * **Scheduled reporting:** Automate the generation and delivery of reports. ### 9. Notification System * **Multi-channel alerts:** Send notifications via email, in-app alerts, and SMS. * **Reminders:** Automated reminders for important events like document expirations, compliance deadlines, or pending approvals. * **Preferences:** Allow users to customize their notification settings. --- ## 🛠️ Technical Architecture ### Frontend (Flutter) * **Architecture:** Clean Architecture with Domain-Driven Design (DDD). * **State Management:** BLoC/Cubit pattern. * **Design System:** A comprehensive custom design system with design tokens, a component library, dark/light mode, and RTL/LTR layout support. * **Responsiveness:** A single codebase for web, mobile, and tablet. * **Bilingual support:** Full English and Arabic localization with bilingual comments in the code. ### Backend (Supabase) * **Database:** A complete SQL schema with tables for all modules and regional configurations. * **Auth:** Extended authentication schema for multi-role support. * **Database logic:** Implement complex business logic, such as payroll calculations and end-of-service benefits, directly in the database using SQL functions or triggers. ### Security * **Data Protection:** Adhere to GDPR, HIPAA, and regional data protection laws. * **Encryption:** End-to-end encryption for sensitive data. * **Advanced RBAC:** Implement fine-grained RBAC policies directly in Supabase using Row-Level Security (RLS). * **Auditing:** Maintain a complete audit trail of all data modifications and user activities. --- ## 📊 Database Schema * **Core Tables:** `employees`, `departments`, `positions`, `employment_history`. * **Payroll Tables:** `salary_structures`, `pay_grades`, `payroll_runs`, `payslips`, `tax_configurations`. * **Regional Compliance Tables:** `country_labor_laws`, `employee_legal_documents`. * **Attendance Tables:** `shifts`, `attendance_records`, `biometric_devices`, `device_attendance_records`. * **Recruitment Tables:** `job_openings`, `applicants`, `interviews`. * **Backup & Recovery Tables:** `backup_records`, `data_residency_rules`. --- ## 🔄 Workflow Automation * **Automated HR workflows:** Create workflows for employee onboarding, leave approvals, and payroll processing. * **Compliance workflows:** Automate GOSI registration (Saudi Arabia), social insurance reporting (Egypt), and visa expiration alerts (UAE). * **Biometric sync:** Implement automated, scheduled synchronization of attendance data from biometric devices. --- ## 🧪 Testing & Quality Assurance * **Test Coverage:** Maintain a minimum of **90% unit test coverage**. * **Test Types:** Conduct comprehensive integration, E2E, performance (1000+ concurrent users), security, accessibility (WCAG 2.1 AA), and usability testing. * **Regional Testing:** Validate labor law calculations and compliance reporting for each target country. --- ## 📋 Deployment & Operations * **Infrastructure:** Utilize Docker containerization with Kubernetes orchestration. * **CI/CD:** Implement a fully automated pipeline for testing, security scanning, and deployments. * **Backup & Recovery:** A comprehensive system for automated daily encrypted backups (database and files) with point-in-time recovery capabilities and cloud storage integration (AWS S3, Google Cloud). --- ## 📝 Documentation * **Technical:** Maintain an up-to-date documentation suite including architecture diagrams, API specifications (OpenAPI/Swagger), and deployment guides. * **User Guides:** Provide comprehensive user manuals, video tutorials, and an FAQ for all user roles. * **Compliance:** Document all security measures and compliance adherence. --- ## 🚀 Implementation Phasing Plan * **Phase 1 (Core Foundation):** Authentication, Employee Database, Basic Attendance & Leave, and Core UI Components. * **Phase 2 (Advanced Features):** Payroll, Performance Management, Recruitment, and Advanced Reporting. * **Phase 3 (Regional & Optimization):** Biometric Device Integration, Regional Labor Law Compliance, and Advanced Backup System. * **Phase 4 (Scale & Finalization):** Full Localization, Performance Optimization for large datasets, and Compliance Certification. --- ## 💡 Success Metrics * **User Adoption:** > 90% * **Process Automation:** > 70% of manual HR tasks automated. * **Data Accuracy:** > 99.5% * **System Uptime:** > 99.9% * **User Satisfaction:** > 4.5/5 * **Time Reduction:** > 40% reduction in administrative time. * **Compliance Audit:** 100% pass rate for regional compliance audits. --- ## Starter Setup & Notes 1. Replace Supabase credentials in `lib/src/core/app_config.dart`. 2. Create the core tables in Supabase (employees, departments, positions, payroll tables). 3. Enable Row-Level Security (RLS) and add corresponding policies for roles. 4. Implement DB functions/triggers for payroll, accruals, and compliance calculations. 5. Add i18n JSON files under `assets/i18n/` for full bilingual support. 6. Expand domain models and split features into modules per Clean Architecture. This starter app is intentionally minimal but structured to be easily extended into the full HR.my platform described above.