---
description:
globs:
alwaysApply: true
---
# SME Centralized Reporting System - Project Architecture & Structure

## PROJECT OVERVIEW
**Application**: Centralized Reporting Dashboard for SMEs
**Platform**: React Native (Cross-platform iOS/Android)
**Architecture**: Modular Component-Based Architecture
**State Management**: Redux + Redux Persist + AsyncStorage

---

## 1. PROJECT STRUCTURE

### Root Directory Structure
```
CentralizedReportingSystem/
├── src/
│   ├── modules/               # Core business modules
│   ├── shared/               # Shared components and utilities
│   ├── navigation/           # Navigation configuration
│   ├── store/               # Redux store configuration
│   ├── services/            # API services and integrations
│   ├── assets/              # Static assets
│   └── types/               # TypeScript type definitions
├── android/                 # Android specific files
├── ios/                     # iOS specific files
└── package.json
```

### Core Module Structure (Each module follows this pattern)
```
src/modules/[moduleName]/
├── screens/                # Screen components (module routes)
├── components/             # Reusable UI for this module (no screens)
│   ├── widgets/           # Dashboard/widgets
│   └── forms/             # Form components
├── navigation/            # Module-level stack navigator(s)
│   └── [ModuleName]Navigator.tsx
├── services/              # Module-specific API services
├── store/                 # Redux slices and actions
│   ├── slice.ts          # Redux toolkit slice
│   ├── selectors.ts      # State selectors
│   └── types.ts          # Module-specific types
└── index.ts              # Module exports (optional)
```



### Shared Directory Structure
```
src/shared/
├── components/             # Reusable UI components
│   ├── charts/            # Chart components
│   ├── forms/             # Form controls
│   ├── layout/            # Layout components
│   └── ui/                # Basic UI components
├── hooks/                 # Custom React hooks
├── utils/                 # Utility functions
├── constants/             # Global constants
├── styles/                # Global styles and themes
└── types/                 # Shared type definitions
```

---

## 2. CORE MODULES DEFINITION

### Module 1: Authentication (`auth`)
```
src/modules/auth/
├── screens/
│   ├── LoginScreen.tsx
│   ├── RegisterScreen.tsx
│   └── ForgotPasswordScreen.tsx
├── components/
│   └── widgets/
├── navigation/
│   └── AuthNavigator.tsx   # Stack with Login, Register, ForgotPassword
├── services/
│   ├── authAPI.ts
│   └── integrations/
└── store/
    ├── authSlice.ts
    ├── selectors.ts
    └── types.ts
```

### Module 2: HR (`hr`)
```
src/modules/hr/
├── screens/
│   ├── HRDashboardScreen.tsx
│   ├── EmployeeMetricsScreen.tsx
│   ├── AttendanceScreen.tsx
│   └── RecruitmentScreen.tsx
├── components/
│   ├── widgets/
│   │   ├── EmployeeStatsWidget.tsx
│   │   ├── AttendanceChart.tsx
│   │   └── PerformanceWidget.tsx
│   └── forms/
│       └── EmployeeForm.tsx
├── navigation/
│   └── HRNavigator.tsx      # Stack with HRDashboard, EmployeeMetrics, Attendance, Recruitment
├── services/
│   ├── hrAPI.ts
│   └── integrations/
│       ├── zohoPeopleService.ts
│       ├── bambooHRService.ts
│       └── kekaService.ts
└── store/
    ├── hrSlice.ts
    ├── selectors.ts
    └── types.ts
```

### Module 3: Zoho Projects (`zohoProjects`)
```
src/modules/zohoProjects/
├── screens/
│   ├── ZohoProjectsDashboardScreen.tsx
│   ├── ProjectPerformanceScreen.tsx
│   ├── ResourceUtilizationScreen.tsx
│   └── ClientAnalyticsScreen.tsx
├── components/
│   ├── widgets/
│   │   ├── ProjectTimelineWidget.tsx
│   │   ├── ResourceAllocationChart.tsx
│   │   └── QualityMetricsWidget.tsx
│   └── forms/
│       └── ProjectForm.tsx
├── navigation/
│   └── ZohoProjectsNavigator.tsx   # Stack with ZohoProjects screens
├── services/
│   ├── zohoProjectsAPI.ts
│   └── integrations/
│       └── zohoProjectsService.ts
└── store/
    ├── zohoProjectsSlice.ts
    ├── selectors.ts
    └── types.ts
```

### Module 4: Profile (`profile`)
```
src/modules/profile/
├── screens/
│   ├── ProfileScreen.tsx
│   └── EditProfileScreen.tsx
├── components/
│   └── widgets/
├── navigation/
│   └── ProfileNavigator.tsx # Stack with Profile and EditProfile
├── services/
│   ├── profileAPI.ts
└── store/
    ├── profileSlice.ts
    ├── selectors.ts
    └── types.ts
```

---

## 3. NAVIGATION STRUCTURE

### Navigation Configuration
```typescript
// src/navigation/AppNavigator.tsx
import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';
import { createStackNavigator } from '@react-navigation/stack';
import Icon from 'react-native-vector-icons/MaterialIcons';

const Tab = createBottomTabNavigator();
const Stack = createStackNavigator();

const AppNavigator = () => (
  <Tab.Navigator
    screenOptions={({ route }) => ({
      tabBarIcon: ({ focused, color, size }) => {
        const iconName = getTabIconName(route.name);
        return <Icon name={iconName} size={size} color={color} />;
      },
    })}
  >
    <Tab.Screen name="ZohoProjects" component={ZohoProjectsStack} />
    <Tab.Screen name="HR" component={HRStack} />
    <Tab.Screen name="Profile" component={ProfileStack} />
  </Tab.Navigator>
);
```

### Stack Navigators for Each Module
```typescript
// HR Stack
const HRStack = () => (
  <Stack.Navigator>
    <Stack.Screen name="HRDashboard" component={HRDashboardScreen} />
    <Stack.Screen name="EmployeeMetrics" component={EmployeeMetricsScreen} />
    <Stack.Screen name="Attendance" component={AttendanceScreen} />
    <Stack.Screen name="Recruitment" component={RecruitmentScreen} />
  </Stack.Navigator>
);

// Zoho Projects Stack
const ZohoProjectsStack = () => (
  <Stack.Navigator>
    <Stack.Screen name="ZohoProjectsDashboard" component={ZohoProjectsDashboardScreen} />
    <Stack.Screen name="ProjectPerformance" component={ProjectPerformanceScreen} />
    <Stack.Screen name="ResourceUtilization" component={ResourceUtilizationScreen} />
    <Stack.Screen name="ClientAnalytics" component={ClientAnalyticsScreen} />
  </Stack.Navigator>
);

// Profile Stack
const ProfileStack = () => (
  <Stack.Navigator>
    <Stack.Screen name="Profile" component={ProfileScreen} />
    <Stack.Screen name="EditProfile" component={EditProfileScreen} />
  </Stack.Navigator>
);
```

---

## 4. INTEGRATION FRAMEWORK

### Primary Integration Services

#### HR Systems Integration
```
src/modules/hr/services/integrations/
├── zohoPeopleService.ts     # Zoho People integration
├── bambooHRService.ts       # BambooHR integration
├── workdayService.ts        # Workday integration
└── kekaService.ts           # Keka integration
```

#### Project Management Integration
```
src/modules/zohoProjects/services/integrations/
└── zohoProjectsService.ts   # Zoho Projects integration
```

#### Communication & Collaboration
```
src/shared/services/integrations/
├── slackService.ts          # Slack integration
├── teamsService.ts          # Microsoft Teams integration
└── zoomService.ts           # Zoom integration
```

---

## 5. DESIGN SYSTEM & STYLING

### Theme Configuration
```typescript
// src/shared/styles/theme.ts
export const COLORS = {
  // Primary colors
  primary: '#2C5F4A',
  primaryLight: '#4A8B6A',
  primaryDark: '#1A3D2E',
  
  // Secondary colors
  secondary: '#FF6B35',
  secondaryLight: '#FF8F65',
  secondaryDark: '#E55A2B',
  
  // UI colors
  background: '#F8F9FA',
  surface: '#FFFFFF',
  text: '#2D3748',
  textLight: '#718096',
  border: '#E2E8F0',
  error: '#E53E3E',
  success: '#38A169',
  warning: '#D69E2E',
  
  // Dashboard specific
  chartPrimary: '#2C5F4A',
  chartSecondary: '#FF6B35',
  chartTertiary: '#4299E1',
  chartQuaternary: '#48BB78',
};

export const FONTS = {
  regular: 'Roboto-Regular',
  medium: 'Roboto-Medium',
  bold: 'Roboto-Bold',
  light: 'Roboto-Light',
  black: 'Roboto-Black',
};

export const FONT_SIZES = {
  xs: 12,
  sm: 14,
  md: 16,
  lg: 18,
  xl: 20,
  xxl: 24,
  xxxl: 32,
};

export const SPACING = {
  xs: 4,
  sm: 8,
  md: 16,
  lg: 24,
  xl: 32,
  xxl: 48,
};

export const BORDER_RADIUS = {
  sm: 4,
  md: 8,
  lg: 12,
  xl: 16,
};

export const SHADOWS = {
  light: {
    shadowColor: '#000',
    shadowOffset: { width: 0, height: 1 },
    shadowOpacity: 0.1,
    shadowRadius: 2,
    elevation: 2,
  },
  medium: {
    shadowColor: '#000',
    shadowOffset: { width: 0, height: 2 },
    shadowOpacity: 0.15,
    shadowRadius: 4,
    elevation: 4,
  },
  heavy: {
    shadowColor: '#000',
    shadowOffset: { width: 0, height: 4 },
    shadowOpacity: 0.2,
    shadowRadius: 8,
    elevation: 8,
  },
};
```

### Theme System and Context
```
src/shared/styles/
├── theme.ts                 # Semantic tokens (colors, spacing, fonts, shadows)
├── ThemeProvider.tsx        # App-level provider with light/dark palettes
├── useTheme.ts              # Hook to consume the theme
└── types.ts                 # Theme typing (Theme, Palette, SemanticTokens)
```

Guidelines
- Use semantic tokens from `theme.ts` (e.g., `COLORS.surface`, `COLORS.text`) instead of hard-coded hex values.
- Support light and dark palettes; default to Light as per the provided UI (white surfaces, cool blue header, soft gray background, subtle shadows).
- Wrap the app at the root with `ThemeProvider`; access tokens via `useTheme()` in components.
- Gradients: primary header/hero areas may use a cool-blue gradient (from `#3AA0FF` to `#2D6BFF`). Keep content surfaces white.
- Spacing and radii: use `SPACING` and `BORDER_RADIUS` tokens; avoid magic numbers.
- Elevation: use `SHADOWS.light|medium|heavy` for cards and bottom toolbars.

Palettes (inspired by the attached design)
- Light palette
  - primary: `#2D6BFF` (buttons/icons), primaryLight: `#3AA0FF`
  - background: `#F4F6F9`, surface: `#FFFFFF`
  - text: `#1F2937`, textLight: `#6B7280`
  - accent (success): `#22C55E`, accent (warning): `#F59E0B`, accent (error): `#EF4444`
  - chartPrimary: `#2D6BFF`, chartSecondary: `#3AA0FF`, chartTertiary: `#10B981`, chartQuaternary: `#F59E0B`
- Dark palette (optional)
  - background: `#0F172A`, surface: `#111827`, text: `#E5E7EB`, textLight: `#9CA3AF`, primary: `#60A5FA`

Provider responsibilities
- Expose `{ colors, spacing, fonts, shadows, isDark, setScheme }`.
- Persist the scheme preference with AsyncStorage.
- Mirror system scheme when `followSystem=true`.

Usage rules
- Import tokens from `useTheme()` or direct constants from `theme.ts` for static styles.
- Do not inline hex codes in components; never duplicate spacing or font sizes.
- For icons and charts, pull colors from `theme.colors` so they adapt to scheme changes.

Example usage
```typescript
// Inside a component
import { useTheme } from '@/shared/styles/useTheme';

const MyCard = () => {
  const { colors, spacing, shadows } = useTheme();
  return (
    <View style={{
      backgroundColor: colors.surface,
      padding: spacing.md,
      borderRadius: 12,
      ...shadows.medium,
    }} />
  );
};
```

---

## 6. ASSETS ORGANIZATION

### Assets Directory Structure
```
src/assets/
├── fonts/                  # Roboto font files
│   ├── Roboto-Regular.ttf
│   ├── Roboto-Medium.ttf
│   ├── Roboto-Bold.ttf
│   ├── Roboto-Light.ttf
│   └── Roboto-Black.ttf
├── images/                 # Image assets
│   ├── logos/
│   ├── icons/
│   ├── illustrations/
│   └── backgrounds/
├── animations/             # Lottie animation files
└── data/                  # Static data files
    ├── currencies.json
    ├── countries.json
    └── industries.json
```

---

## 7. SHARED COMPONENTS LIBRARY

### UI Components Structure
```
src/shared/components/
├── ui/                     # Basic UI components
│   ├── Button/
│   ├── Input/
│   ├── Card/
│   ├── Modal/
│   ├── LoadingSpinner/
│   └── EmptyState/
├── charts/                 # Chart components
│   ├── LineChart/
│   ├── BarChart/
│   ├── PieChart/
│   ├── DonutChart/
│   └── ProgressChart/
├── forms/                  # Form components
│   ├── FormInput/
│   ├── FormSelect/
│   ├── FormDatePicker/
│   ├── FormCheckbox/
│   └── FormRadio/
├── layout/                 # Layout components
│   ├── Container/
│   ├── Header/
│   ├── Footer/
│   ├── Sidebar/
│   └── Grid/
└── widgets/               # Reusable widget components
    ├── KPIWidget/
    ├── ChartWidget/
    ├── ListWidget/
    ├── StatWidget/
    └── FilterWidget/
```

---

## 8. PERFORMANCE OPTIMIZATION GUIDELINES

### Code Organization for Performance
- Implement lazy loading for non-critical screens
- Use React.memo for expensive dashboard widgets
- Implement virtualized lists for large datasets
- Cache frequently accessed data using Redux Persist
- Use image optimization and caching strategies

### Data Management Optimization
- Implement pagination for large datasets (>100 records)
- Use memoization for expensive calculations
- Cache API responses with appropriate TTL
- Implement background data refresh strategies
- Use efficient data structures for complex operations

---

## 9. SECURITY & DATA PROTECTION

### Data Security Implementation
```
src/shared/security/
├── encryption/            # Data encryption utilities
├── storage/              # Secure storage implementation  
├── authentication/       # Auth security measures
└── validation/          # Input validation and sanitization
```

### Security Measures
- Encrypt sensitive data before storing in AsyncStorage
- Implement secure token storage
- Add certificate pinning for API communications
- Implement proper input validation and sanitization

---

## 10. ACCESSIBILITY & INTERNATIONALIZATION

### Accessibility Structure
```
src/shared/accessibility/
├── labels.ts             # Accessibility labels
├── hints.ts              # Accessibility hints
├── roles.ts              # Accessibility roles
└── utils.ts              # Accessibility utilities
```



This architecture file provides the complete project structure and organization guidelines for building a maintainable, scalable SME reporting system.