sciagent/fe0/FRONTEND_MIGRATION_GUIDE.md

Frontend Migration Guide

Overview

This guide helps you migrate from the current frontend structure to the new production-ready architecture.

Migration Steps

Step 1: Install Dependencies

npm install axios

Step 2: Create New Directory Structure

Create the following directories:

mkdir -p src/app/providers
mkdir -p src/app/router
mkdir -p src/features/workflows/{components,hooks,services,types}
mkdir -p src/features/auth/{components,hooks,services,types}
mkdir -p src/shared/api
mkdir -p src/shared/components/feedback
mkdir -p src/shared/config
mkdir -p src/shared/utils
mkdir -p src/shared/types

Step 3: Move Files

1. Move API-related code:

   • lib/auth-service.ts → features/auth/services/authService.ts
   • Create shared/api/client.ts (new API client)

2. Move components by feature:

   • Workflow-related components → features/workflows/components/
   • Auth components → features/auth/components/

3. Move shared components:

   • UI components stay in components/ui/
   • Layout components → layouts/
   • Shared components → shared/components/

Step 4: Update Imports

Update all import paths to use the new structure:

// Old
import { authService } from '@/lib/auth-service';

// New
import { authService } from '@/features/auth/services/authService';

Step 5: Update App.tsx

Replace the current App.tsx with the new structure that includes:

• Error boundaries
• Query client setup
• Route configuration
• Suspense boundaries

Step 6: Create Environment Files

1. Copy .env.example to .env.development
2. Update environment variables
3. Add .env.production for production

Step 7: Update TypeScript Config

Ensure tsconfig.json has proper path aliases:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Testing the Migration

1. Start the development server:

   npm run dev
   

2. Test key features:

   • Authentication flow
   • API calls
   • Error handling
   • Loading states

3. Check for console errors:

   • Fix any import errors
   • Fix any type errors

Common Issues

Issue: Import errors

Solution: Update all import paths to match the new structure.

Issue: Missing types

Solution: Create type definitions in features/*/types/ or shared/types/.

Issue: API calls failing

Solution: Ensure the API client is properly configured with the correct base URL.

Next Steps

1. Migrate remaining features
2. Add error boundaries to specific routes
3. Implement loading states
4. Add tests
5. Optimize bundle size