dotnet-to-react-python-refactor

Core Workflow

Phase 1: Assessment & Architecture Planning

1. Analyze .NET application — run the assessment script:

   python scripts/assess_dotnet_app.py /path/to/dotnet/project
   

   Outputs: project type, controllers, models, views, services, DB contexts, auth, NuGet packages.

2. Design target architecture (see references/architecture-patterns.md):

   • Frontend: React SPA (routing, state management, UI framework)
   • Backend: Python REST API (FastAPI/Flask/Django) + ORM
   • Auth: JWT, OAuth2, or session-based
   • Data: same DB or migration strategy

Phase 2: Backend Migration (.NET → Python)

1. Initialize Python backend:

   python scripts/init_python_backend.py <name> --framework fastapi --db-type postgresql
   

   Framework choice: FastAPI (async, OpenAPI docs), Flask (lightweight), Django REST (full-featured with ORM/admin).

2. Migrate business logic: map .NET controllers → Python endpoints; translate C# classes, LINQ → Python/ORM queries, async/await patterns. See references/framework-equivalents.md.

3. Data access: map Entity Framework models → SQLAlchemy/Django ORM; convert queries and stored procedures. See references/orm-migration.md.

4. Auth: map ASP.NET Identity → JWT tokens or session auth; preserve role-based/policy authorization. See references/authentication-patterns.md.

Phase 3: Frontend Migration (.NET Views → React)

1. Initialize React (Vite recommended):

   npm create vite@latest frontend -- --template react-ts
   

   See assets/react-project-template/ for recommended structure.

2. Convert Razor views to JSX (semi-automated):

   python scripts/convert_razor_to_jsx.py ./Views --output ./frontend/src/components
   

   Use assets/react-component-templates/ for production-ready Button, Input, and Modal components.

3. State management: Context API (small apps), Zustand (medium), Redux Toolkit (large); convert ViewBag/ViewData to component or global state.

4. Routing: replace ASP.NET routing with React Router; implement protected routes for authenticated pages.

5. API integration: React Query + axios with auth interceptors. See references/api-integration.md.

6. Forms: React Hook Form or Formik; client-side validation matching backend rules.

Phase 4: Data Layer Migration

1. Generate ORM models:

   python scripts/generate_migration.py /path/to/models --framework sqlalchemy --output ./migrations
   

2. Preserve relationships, constraints, indexes, and custom type mappings.

3. Apply migrations: Alembic (SQLAlchemy) or Django migrations.

Phase 5: Testing & Validation

• Backend (pytest): unit tests, endpoint integration tests, auth flows, error handling.
• Frontend (Jest + RTL): component tests; Cypress/Playwright for E2E.
• Data integrity: compare query results between .NET and Python; validate CRUD and cascading deletes.

Phase 6: Deployment

1. Environment: configure env vars, secrets, and per-environment configs (dev/staging/prod).
2. Backend: Gunicorn/Uvicorn + Nginx reverse proxy; health checks and DB connection pooling.
3. Frontend: production build → static hosting (Netlify, Vercel, S3+CloudFront); CDN for assets.
4. Cutover strategy: Big Bang (fast, higher risk) | Strangler Fig (incremental, lower risk) | Parallel Run.
5. See references/deployment-guides/ for step-by-step Docker Compose and AWS guides. Use assets/docker-compose.yml and assets/nginx.conf.

Execution Guidelines

Order: backend first → frontend as endpoints become available → staging validation → cutover with rollback plan.

Key pitfalls:

• N+1 queries: Python ORM lazy loading differs from Entity Framework
• Async/await: C# and Python semantics differ
• Timezones: standardize on UTC
• Decimal precision: map carefully for financial calculations

Standards: PEP 8 + type hints + mypy (Python); ESLint + Prettier + TypeScript (React); 80%+ test coverage.

Performance: profile DB queries early; add Redis caching; paginate large datasets; use React.memo/useMemo and lazy loading.

Quick Reference

Scripts

| Script | Purpose | |--------|---------| | assess_dotnet_app.py | Generate migration inventory from .NET project | | init_python_backend.py | Scaffold Python backend (FastAPI/Flask/Django) | | generate_migration.py | Create ORM models from .NET Entity Framework models | | convert_razor_to_jsx.py | Convert Razor views to React JSX |

Reference Docs (references/)

| File | Use When | |------|---------| | architecture-patterns.md | Planning architecture or choosing tech stack | | framework-equivalents.md | Mapping .NET → Python technologies and packages | | orm-migration.md | Entity Framework → SQLAlchemy/Django ORM | | authentication-patterns.md | Implementing auth migration | | api-integration.md | React–Python API client patterns | | testing-strategies.md | Setting up tests and coverage | | security-hardening-checklist.md | Pre-production security audit | | troubleshooting-guide.md | Debugging migration and deployment issues | | deployment-guides/docker-compose-deployment.md | Docker Compose deployment | | deployment-guides/aws-deployment.md | AWS deployment (Elastic Beanstalk, EC2, ECS) |

Assets (assets/)

| Asset | Purpose | |-------|---------| | react-project-template/ | React project structure guide | | react-component-templates/ | Button, Input, Modal components with CSS | | docker-compose.yml | Full-stack Docker setup (PostgreSQL, Redis, Nginx) | | nginx.conf | Production Nginx reverse proxy | | Dockerfile.dev | Development frontend Dockerfile with hot-reload | | .env.example | Environment variables template | | cicd-templates/ | GitHub Actions and GitLab CI/CD pipelines |