Backend Migration Plan: FastAPI to Fastify (TypeScript)

Goals

The objective of this migration is to transition the backend services from Python’s FastAPI framework to Node.js using Fastify with TypeScript. This migration aims to preserve existing business logic, improve maintainability, and align with the team’s preferred technology stack.

Current Architecture (FastAPI)

The existing backend is built using FastAPI and includes the following components:

• Modular routing via APIRouter with versioning (v1, v2)
• Middleware for CORS and logging
• Authentication using API keys and role-based access
• Business logic embedded in route files and shared modules
• Azure Blob Storage for file uploads
• Cosmos DB (used in development)
• Temporal workflows for orchestration
• Feature flag service for conditional logic

Proposed Architecture (Fastify with TypeScript)

The new backend will be structured using Fastify with TypeScript, following a modular and maintainable design. The proposed directory structure is as follows: src/
├── routes/
│   └── v2/
│       ├── entity.ts
│       ├── entityDocument.ts
│       └── …
├── controllers/
│   ├── entityController.ts
│   └── entityDocumentController.ts
├── services/
│   ├── entityService.ts
│   ├── blobService.ts
│   ├── workflowService.ts
│   └── …
├── auth/
│   ├── authUtils.ts
│   └── roleMiddleware.ts
├── utils/
│   ├── hashUtils.ts
│   └── errorHandlers.ts
├── config/
│   ├── featureFlags.ts
│   └── env.ts
├── plugins/
│   ├── mysql.ts
│   ├── logger.ts
│   └── auth.ts
├── app.ts
└── server.ts

Migration Strategy

The migration will be executed in the following phases:

1. Foundation Setup:
      - Confirm Fastify framework setup with TypeScript
      - Implement shared decorators for authentication and role enforcement
      - Create reusable error handling utilities
2. Route Migration:
      - Analyze each FastAPI route file
      - Create corresponding Fastify route modules
      - Move logic to controllers and services
      - Port shared utilities
      - Replace Python exceptions with Fastify error handling
3. Integration:
      - Azure Blob Storage integration
      - Temporal workflow orchestration
      - Feature flag service
      - Cosmos DB (if required)
4. Testing and Validation:
      - Unit and integration tests
      - Validate endpoint parity
      - Currently ZERO testing in place, important to add to debug issues more quickly.

Route Migration Checklist

Developer Guidelines

• Use Fastify plugins for shared functionality such as database and authentication
• Keep controllers focused on request handling; delegate business logic to services
• Use async/await consistently
• Validate inputs using appropriate TypeScript validation libraries
• Implement decorators for authentication and role checks
• Use Pino for structured logging

Shared Utilities Mapping

The following Python utilities will be ported to TypeScript equivalents:

• calculate_hash → utils/hashUtils.ts
• upload_blob → services/blobService.ts
• start_workflow → services/workflowService.ts
• ff_svc.get_flag → config/featureFlags.ts
• authenticate_key → auth/authUtils.ts
• require_roles → auth/roleMiddleware.ts

Notes

• Cosmos DB is used only in development and may be replaced or mocked
• Temporal workflows may require a Node.js SDK or REST bridge
• Feature flags should be centralized and cached for performance
• Route files are explicitly listed for clarity and tracking