create-ern-boilerplate 0.0.21 → 0.0.22

package/templates/simple/PROJECT_CONTEXT.MD

@@ -1,663 +0,0 @@
-# Project Context for AI Agents
-
-> **Purpose**: This document helps AI coding agents understand the project architecture, conventions, and patterns to generate consistent, high-quality code.
-
-## 🏗️ Tech Stack
-
-```
-- Framework: React Native + Expo SDK 54
-- Routing: Expo Router (file-based)
-- Language: TypeScript (strict mode)
-- Styling: NativeWind (Tailwind CSS for React Native)
-- State: React Context API
-- API: Mock API (development) / Real API (production)
-```
-
-## 📁 Project Structure
-
-### Core Directories
-
-```
-app/                   # File-based routing (Expo Router)
-├── (auth)/            # Public authentication routes
-├── (protected)/       # Routes requiring authentication
-├── (admin)/           # Routes requiring admin role
-└── _layout.tsx        # Root layout wrapper
-
-src/
-├── components/        # Reusable UI components
-├── contexts/          # React Context providers
-├── hooks/             # Custom React hooks
-├── services/          # API and business logic
-├── types/             # TypeScript type definitions
-├── theme/             # Design tokens and theme config
-└── utils/             # Helper functions and utilities
-```
-
-### Detailed Structure
-
-#### **Components** (`src/components/`)
-- `auth/` - Authentication-specific components (ProtectedRoute)
-- `common/` - Generic reusable components (Button, Input, Card)
-- `shared/` - Shared business components (FormInput, ConfirmDialog)
-- `users/` - User management components
-- `header/` - Navigation and header components
-- `config/` - Configuration components (ToastConfig)
-
-#### **Services** (`src/services/`)
-- `*.service.ts` - Real API service implementations
-- `mockApi/*.mock.ts` - Mock data for development
-- `api.ts` - Base API client configuration
-
-#### **Types** (`src/types/`)
-- `*.types.ts` - TypeScript interfaces and types
-- Group by domain: `auth`, `user`, `product`, `api`
-
-## 🎯 Architecture Patterns
-
-### 1. Data Flow
-```
-Component → Custom Hook → Service → API/Mock
-                ↓
-            Context (if global state needed)
-```
-
-### 2. Authentication Flow
-```
-1. User logs in via authService.login()
-2. Token stored in AsyncStorage
-3. AuthContext provides user state
-4. ProtectedRoute guards routes in (protected)/ and (admin)/
-```
-
-### 3. API Strategy
-- **Development**: Uses `mockApi/*.mock.ts` files
-- **Production**: Uses real API via `*.service.ts`
-- Switch via environment variable or constants
-
-## 📝 Naming Conventions
-
-### Files
-- Components: `PascalCase.tsx` (e.g., `UserCard.tsx`)
-- Services: `camelCase.service.ts` (e.g., `auth.service.ts`)
-- Hooks: `useCamelCase.ts` (e.g., `useAuth.ts`)
-- Types: `camelCase.types.ts` (e.g., `user.types.ts`)
-- Utils: `camelCase.ts` (e.g., `validation.ts`)
-
-### Code
-- Components: `PascalCase` (e.g., `UserCard`)
-- Functions: `camelCase` (e.g., `getUserById`)
-- Constants: `UPPER_SNAKE_CASE` (e.g., `API_BASE_URL`)
-- Types/Interfaces: `PascalCase` (e.g., `User`, `ApiResponse<T>`)
-- Enums: `PascalCase` with `UPPER_SNAKE_CASE` values
-
-### Variables
-- Boolean: prefix with `is`, `has`, `should` (e.g., `isLoading`, `hasError`)
-- Arrays: plural nouns (e.g., `users`, `products`)
-- Event handlers: prefix with `handle` or `on` (e.g., `handleSubmit`, `onPress`)
-
-## 🗺️ Routing Guide
-
-### Route Groups (Expo Router)
-
-#### `(auth)` - Public Routes
-```typescript
-// No authentication required
-app/(auth)/
-├── _layout.tsx      // Auth-specific layout (no header)
-├── login.tsx        // Login screen
-└── register.tsx     // Registration screen
-```
-
-#### `(protected)` - Authenticated Routes
-```typescript
-// Requires valid user token
-app/(protected)/
-├── _layout.tsx      // Protected layout with header
-├── home.tsx         // Home screen
-└── settings.tsx     // User settings
-```
-
-#### `(admin)` - Admin-Only Routes
-```typescript
-// Requires admin role
-app/(admin)/
-├── profile.tsx           // Admin profile
-└── user-management.tsx   // User CRUD
-```
-
-### Navigation
-```typescript
-import { router } from 'expo-router';
-
-// Navigate
-router.push('/login');
-router.replace('/(protected)/home');
-
-// Go back
-router.back();
-
-// With params
-router.push({
-  pathname: '/user/[id]',
-  params: { id: '123' }
-});
-```
-
-## 🎨 Styling Guide
-
-### NativeWind (Tailwind CSS)
-```typescript
-// Use className prop
-<View className="flex-1 bg-white p-4">
-  <Text className="text-lg font-bold text-gray-900">
-    Hello World
-  </Text>
-</View>
-
-// Conditional classes
-<View className={`p-4 ${isActive ? 'bg-blue-500' : 'bg-gray-200'}`}>
-```
-
-### Theme Colors
-```typescript
-// Defined in src/theme/colors.ts
-import { colors } from '@/theme/colors';
-
-// Usage in StyleSheet (if needed)
-backgroundColor: colors.primary[500]
-```
-
-### Best Practices
-- Prefer NativeWind classes over StyleSheet
-- Use theme colors for consistency
-- Responsive: `sm:`, `md:`, `lg:` prefixes
-- Dark mode: `dark:` prefix
-
-## 🔐 Authentication & Authorization
-
-### AuthContext
-```typescript
-// Available throughout the app
-const { user, login, logout, isAuthenticated } = useAuth();
-
-// User object structure
-interface User {
-  id: string;
-  email: string;
-  name: string;
-  role: 'user' | 'admin';
-}
-```
-
-### Protected Routes
-```typescript
-// Automatic protection via ProtectedRoute component
-// Already implemented in (protected)/_layout.tsx and (admin)/_layout.tsx
-
-// Manual check in component
-const { isAuthenticated, user } = useAuth();
-
-if (!isAuthenticated) {
-  return <Redirect href="/login" />;
-}
-
-if (user?.role !== 'admin') {
-  return <Redirect href="/(protected)/home" />;
-}
-```
-
-### Token Management
-```typescript
-// Stored in AsyncStorage via utils/storage.ts
-import { storage } from '@/utils/storage';
-
-await storage.setToken(token);
-const token = await storage.getToken();
-await storage.removeToken();
-```
-
-## 🛠️ Service Layer Guide
-
-### Service Structure
-```typescript
-// src/services/user.service.ts
-import { api } from './api';
-import { User, CreateUserDto } from '@/types/user.types';
-
-export const userService = {
-  // GET all users
-  getAll: async (): Promise<User[]> => {
-    const response = await api.get('/users');
-    return response.data;
-  },
-
-  // GET single user
-  getById: async (id: string): Promise<User> => {
-    const response = await api.get(`/users/${id}`);
-    return response.data;
-  },
-
-  // POST create user
-  create: async (data: CreateUserDto): Promise<User> => {
-    const response = await api.post('/users', data);
-    return response.data;
-  },
-
-  // PUT update user
-  update: async (id: string, data: Partial<User>): Promise<User> => {
-    const response = await api.put(`/users/${id}`, data);
-    return response.data;
-  },
-
-  // DELETE user
-  delete: async (id: string): Promise<void> => {
-    await api.delete(`/users/${id}`);
-  },
-};
-```
-
-### Mock Services
-```typescript
-// src/services/mockApi/user.mock.ts
-import { User } from '@/types/user.types';
-
-const mockUsers: User[] = [
-  { id: '1', name: 'John Doe', email: 'john@example.com', role: 'admin' },
-  // ... more mock data
-];
-
-export const userMockService = {
-  getAll: async (): Promise<User[]> => {
-    // Simulate network delay
-    await new Promise(resolve => setTimeout(resolve, 500));
-    return mockUsers;
-  },
-  // ... other methods
-};
-```
-
-### API Client
-```typescript
-// src/services/api.ts
-import axios from 'axios';
-import { storage } from '@/utils/storage';
-
-export const api = axios.create({
-  baseURL: process.env.EXPO_PUBLIC_API_URL || 'http://localhost:3000',
-  timeout: 10000,
-});
-
-// Request interceptor (add auth token)
-api.interceptors.request.use(async (config) => {
-  const token = await storage.getToken();
-  if (token) {
-    config.headers.Authorization = `Bearer ${token}`;
-  }
-  return config;
-});
-
-// Response interceptor (handle errors)
-api.interceptors.response.use(
-  (response) => response,
-  (error) => {
-    if (error.response?.status === 401) {
-      // Handle unauthorized
-      storage.removeToken();
-      router.replace('/login');
-    }
-    return Promise.reject(error);
-  }
-);
-```
-
-## 🪝 Custom Hooks Guide
-
-### Pattern
-```typescript
-// src/hooks/useUsers.ts
-import { useState, useEffect } from 'react';
-import { userService } from '@/services/user.service';
-import { User } from '@/types/user.types';
-
-export const useUsers = () => {
-  const [users, setUsers] = useState<User[]>([]);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
-
-  const fetchUsers = async () => {
-    try {
-      setLoading(true);
-      setError(null);
-      const data = await userService.getAll();
-      setUsers(data);
-    } catch (err) {
-      setError(err instanceof Error ? err.message : 'Failed to fetch users');
-    } finally {
-      setLoading(false);
-    }
-  };
-
-  useEffect(() => {
-    fetchUsers();
-  }, []);
-
-  const refresh = () => fetchUsers();
-
-  return { users, loading, error, refresh };
-};
-```
-
-### Usage in Component
-```typescript
-const UserList = () => {
-  const { users, loading, error, refresh } = useUsers();
-
-  if (loading) return <Loading />;
-  if (error) return <ErrorState message={error} />;
-
-  return (
-    <FlatList
-      data={users}
-      renderItem={({ item }) => <UserCard user={item} />}
-      refreshing={loading}
-      onRefresh={refresh}
-    />
-  );
-};
-```
-
-## 📦 Component Patterns
-
-### Reusable Component Template
-```typescript
-// src/components/common/Button.tsx
-import { TouchableOpacity, Text, ActivityIndicator } from 'react-native';
-
-interface ButtonProps {
-  title: string;
-  onPress: () => void;
-  variant?: 'primary' | 'secondary' | 'danger';
-  loading?: boolean;
-  disabled?: boolean;
-}
-
-export const Button = ({
-  title,
-  onPress,
-  variant = 'primary',
-  loading = false,
-  disabled = false,
-}: ButtonProps) => {
-  const baseClasses = 'px-6 py-3 rounded-lg items-center justify-center';
-  const variantClasses = {
-    primary: 'bg-blue-600',
-    secondary: 'bg-gray-600',
-    danger: 'bg-red-600',
-  };
-
-  return (
-    <TouchableOpacity
-      onPress={onPress}
-      disabled={disabled || loading}
-      className={`${baseClasses} ${variantClasses[variant]} ${
-        disabled ? 'opacity-50' : ''
-      }`}
-    >
-      {loading ? (
-        <ActivityIndicator color="white" />
-      ) : (
-        <Text className="text-white font-semibold">{title}</Text>
-      )}
-    </TouchableOpacity>
-  );
-};
-```
-
-### Feature Component Template
-```typescript
-// src/components/users/UserCard.tsx
-import { View, Text } from 'react-native';
-import { User } from '@/types/user.types';
-import { Button } from '@/components/common/Button';
-
-interface UserCardProps {
-  user: User;
-  onEdit?: (user: User) => void;
-  onDelete?: (userId: string) => void;
-}
-
-export const UserCard = ({ user, onEdit, onDelete }: UserCardProps) => {
-  return (
-    <View className="bg-white p-4 rounded-lg shadow-sm mb-3">
-      <Text className="text-lg font-bold">{user.name}</Text>
-      <Text className="text-gray-600">{user.email}</Text>
-      <Text className="text-sm text-gray-500">{user.role}</Text>
-
-      <View className="flex-row gap-2 mt-3">
-        {onEdit && (
-          <Button title="Edit" onPress={() => onEdit(user)} variant="secondary" />
-        )}
-        {onDelete && (
-          <Button title="Delete" onPress={() => onDelete(user.id)} variant="danger" />
-        )}
-      </View>
-    </View>
-  );
-};
-```
-
-## 🔤 TypeScript Patterns
-
-### Type Definitions
-```typescript
-// src/types/user.types.ts
-
-// Base entity
-export interface User {
-  id: string;
-  email: string;
-  name: string;
-  role: UserRole;
-  createdAt: string;
-  updatedAt: string;
-}
-
-// Enums
-export enum UserRole {
-  USER = 'user',
-  ADMIN = 'admin',
-}
-
-// DTOs (Data Transfer Objects)
-export interface CreateUserDto {
-  email: string;
-  name: string;
-  password: string;
-  role?: UserRole;
-}
-
-export interface UpdateUserDto {
-  email?: string;
-  name?: string;
-  role?: UserRole;
-}
-
-// Utility types
-export type UserWithoutPassword = Omit<User, 'password'>;
-export type PartialUser = Partial<User>;
-```
-
-### Generic API Response
-```typescript
-// src/types/api.types.ts
-export interface ApiResponse<T> {
-  data: T;
-  message: string;
-  success: boolean;
-}
-
-export interface PaginatedResponse<T> {
-  data: T[];
-  total: number;
-  page: number;
-  limit: number;
-}
-
-export interface ApiError {
-  message: string;
-  code: string;
-  details?: Record<string, string[]>;
-}
-```
-
-## 🚨 Error Handling
-
-### Service Level
-```typescript
-try {
-  const users = await userService.getAll();
-  return users;
-} catch (error) {
-  if (axios.isAxiosError(error)) {
-    // Handle API errors
-    const message = error.response?.data?.message || 'Network error';
-    throw new Error(message);
-  }
-  throw error;
-}
-```
-
-### Component Level
-```typescript
-const handleSubmit = async () => {
-  try {
-    setLoading(true);
-    await userService.create(formData);
-    Toast.show({ type: 'success', text1: 'User created successfully' });
-    router.back();
-  } catch (error) {
-    Toast.show({
-      type: 'error',
-      text1: 'Failed to create user',
-      text2: error instanceof Error ? error.message : 'Unknown error',
-    });
-  } finally {
-    setLoading(false);
-  }
-};
-```
-
-## ✅ Best Practices
-
-### Do's
-- ✅ Use TypeScript strict mode
-- ✅ Define proper interfaces for all data structures
-- ✅ Use custom hooks for reusable logic
-- ✅ Keep components small and focused (< 200 lines)
-- ✅ Use meaningful variable and function names
-- ✅ Add JSDoc comments for complex functions
-- ✅ Handle loading and error states in UI
-- ✅ Use async/await instead of promises
-- ✅ Implement proper error boundaries
-- ✅ Use React.memo for expensive renders
-
-### Don'ts
-- ❌ Don't use `any` type
-- ❌ Don't put business logic in components
-- ❌ Don't mutate state directly
-- ❌ Don't forget to cleanup effects
-- ❌ Don't hardcode strings (use constants)
-- ❌ Don't ignore TypeScript errors
-- ❌ Don't use inline styles when NativeWind available
-- ❌ Don't fetch data in useEffect without dependency array
-
-## 🧪 Testing Patterns
-
-### Component Test Template
-```typescript
-// src/components/common/__tests__/Button.test.tsx
-import { render, fireEvent } from '@testing-library/react-native';
-import { Button } from '../Button';
-
-describe('Button', () => {
-  it('renders correctly', () => {
-    const { getByText } = render(<Button title="Click me" onPress={() => {}} />);
-    expect(getByText('Click me')).toBeTruthy();
-  });
-
-  it('calls onPress when clicked', () => {
-    const onPress = jest.fn();
-    const { getByText } = render(<Button title="Click me" onPress={onPress} />);
-    fireEvent.press(getByText('Click me'));
-    expect(onPress).toHaveBeenCalled();
-  });
-
-  it('shows loading state', () => {
-    const { getByTestId } = render(
-      <Button title="Click me" onPress={() => {}} loading={true} />
-    );
-    expect(getByTestId('activity-indicator')).toBeTruthy();
-  });
-});
-```
-
-## 🔧 Common Tasks
-
-### Adding a New Feature
-1. Define types in `src/types/feature.types.ts`
-2. Create service in `src/services/feature.service.ts`
-3. Create mock in `src/services/mockApi/feature.mock.ts`
-4. Create custom hook in `src/hooks/useFeature.ts`
-5. Create components in `src/components/feature/`
-6. Add route in `app/(protected)/feature.tsx`
-
-### Adding a New Route
-1. Create file in appropriate route group
-2. Add proper layout if needed
-3. Implement authentication guard if protected
-4. Update navigation types if using typed routes
-
-### Adding a New Component
-1. Create component file in appropriate folder
-2. Define Props interface
-3. Export as named export
-4. Add to index.ts if grouping exports
-
-## 📚 Key Files Reference
-
-### Must-Read Files
-- `app/_layout.tsx` - Root app layout
-- `src/contexts/AuthContext.tsx` - Authentication state
-- `src/services/api.ts` - API client setup
-- `src/utils/storage.ts` - AsyncStorage wrapper
-- `src/types/*.types.ts` - Type definitions
-
-### Configuration Files
-- `app.json` - Expo configuration
-- `tailwind.config.js` - NativeWind/Tailwind config
-- `tsconfig.json` - TypeScript configuration
-- `babel.config.js` - Babel configuration
-
-## 🚀 Development Workflow
-
-### Starting Development
-```bash
-npm install
-npm start
-# Press 'i' for iOS, 'a' for Android, 'w' for Web
-```
-
-### Code Generation Guidelines
-1. Always use TypeScript with proper types
-2. Follow existing file structure
-3. Use NativeWind for styling
-4. Implement error handling
-5. Add loading states
-6. Keep components reusable
-7. Write JSDoc for complex functions
-
----
-
-**Last Updated**: 2025-01-29
-**Version**: 1.0.0