Backend API Architecture Options: Bast Admin UI¶
Date: December 2025
Status: Architecture Decision Record (ADR)
Context: Evaluating backend technology options for API services
Table of Contents¶
- Executive Summary
- Architecture Decision Records
- ADR-001: Backend Language Selection
- ADR-002: API Architecture Pattern
- ADR-003: Database & ORM Selection
- ADR-004: API Communication Protocol
- Architecture Options Overview
- Option A: TypeScript Backend
- Option B: Python Backend (Current)
- Option C: Hybrid BFF Pattern
- Option D: Polyglot Microservices
- Decision Framework
- Recommendation
- Sources
Executive Summary¶
This document evaluates four architecture options for Bast Admin UI's backend API services:
| Option | Description | Recommendation |
|---|---|---|
| A: TypeScript Only | Replace FastAPI with Node.js/NestJS | Not recommended (rewrite cost) |
| B: Python Only | Continue with existing FastAPI | Good baseline option |
| C: Hybrid BFF | Add Node.js BFF in front of FastAPI | Recommended |
| D: Polyglot | Mix of TS and Python microservices | For complex/large teams |
Primary Recommendation: Option C (Hybrid BFF Pattern) - Provides type safety benefits of TypeScript while preserving existing FastAPI investment.
Architecture Decision Records¶
ADR-001: Backend Language Selection¶
Status: Proposed
Context: We need to decide whether to use TypeScript (Node.js), Python (FastAPI), or a combination for our backend API services. The frontend is built with React/TypeScript.
Decision Options¶
| Option | Decision |
|---|---|
| 1A | Full TypeScript backend (Node.js/NestJS) |
| 1B | Full Python backend (FastAPI) - Current |
| 1C | Hybrid (TypeScript BFF + Python services) |
Option 1A: Full TypeScript Backend¶
Decision: Replace all Python/FastAPI services with TypeScript/Node.js
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ React │◄───────►│ Node.js │◄───────►│ Database │
│ (TypeScript)│ REST │ NestJS │ Prisma │ PostgreSQL │
└──────────────┘ └──────────────┘ └──────────────┘
Pros:
| Advantage | Impact | Description |
|---|---|---|
| Single language | High | TypeScript across entire stack |
| Shared types | High | Native type sharing between frontend/backend |
| tRPC compatible | High | End-to-end type safety without code generation |
| Unified tooling | Medium | Same ESLint, Prettier, Jest across codebase |
| Developer velocity | Medium | No context-switching between languages |
| Hiring flexibility | Medium | Full-stack developers can work anywhere |
| Real-time excellence | Medium | Node.js event loop ideal for WebSockets |
| Monorepo friendly | Low | Turborepo/Nx work seamlessly |
Cons:
| Disadvantage | Impact | Description |
|---|---|---|
| Complete rewrite | Critical | All existing FastAPI services must be rewritten |
| Team reskilling | High | If team is Python-focused, significant learning curve |
| ML/AI gaps | High | Node.js lacks Python's ML ecosystem |
| Lost investment | High | Existing FastAPI code becomes obsolete |
| CPU-bound weakness | Medium | Node.js less efficient for heavy computation |
| Lose Pydantic | Medium | Need Zod/io-ts to replace validation |
| Lose auto-docs | Low | Need explicit Swagger setup |
Performance Characteristics:
| Metric | Node.js | Notes |
|---|---|---|
| Requests/sec | ~44% higher than Python | Simple HTTP requests |
| Latency (p99) | Lower | Event loop efficiency |
| Startup time | Faster | V8 JIT compilation |
| WebSocket connections | Excellent | Native event-driven |
| ML workloads | Poor | Must call Python services |
Option 1B: Full Python Backend (Current)¶
Decision: Continue exclusively with Python/FastAPI microservices
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ React │◄───────►│ FastAPI │◄───────►│ Database │
│ (TypeScript)│ REST │ (Python) │SQLAlchemy PostgreSQL │
└──────────────┘ └──────────────┘ └──────────────┘
Pros:
| Advantage | Impact | Description |
|---|---|---|
| Already built | Critical | No migration effort - services exist |
| Team expertise | High | Team already knows Python/FastAPI |
| ML/AI native | High | Direct TensorFlow, PyTorch, pandas access |
| Auto documentation | High | FastAPI generates OpenAPI automatically |
| Pydantic validation | High | Powerful data validation built-in |
| Data processing | Medium | Excellent for ETL, analytics pipelines |
| Mature ecosystem | Medium | SQLAlchemy, Celery, etc. well-established |
Cons:
| Disadvantage | Impact | Description |
|---|---|---|
| Two languages | Medium | Context-switching between TS frontend and Python |
| Type drift | Medium | Manual effort to keep TS types synced |
| No shared code | Medium | Can't share validation logic |
| GIL limitations | Low | Affects CPU parallelism (mitigated by async) |
| WebSocket gaps | Low | Less natural than Node.js |
Performance Characteristics:
| Metric | FastAPI | Notes |
|---|---|---|
| Requests/sec | Baseline | Good async performance |
| PostgreSQL fetch | 6ms avg | Slightly faster than Node |
| ML workloads | Excellent | Native ecosystem |
| Data processing | Excellent | pandas, numpy native |
Option 1C: Hybrid (TypeScript BFF + Python)¶
Decision: Add TypeScript BFF layer while keeping Python services
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ React │◄───────►│ Node.js BFF │◄───────►│ FastAPI │
│ (TypeScript)│ tRPC │ (TypeScript)│ REST │ (Python) │
└──────────────┘ └──────────────┘ └──────────────┘
Pros:
| Advantage | Impact | Description |
|---|---|---|
| Preserves investment | Critical | No rewrite of existing FastAPI |
| Type safety | High | tRPC between frontend and BFF |
| Best of both | High | Node.js for real-time, Python for ML |
| Incremental adoption | High | Can start small, expand gradually |
| Security boundary | Medium | BFF handles auth; internal APIs hidden |
| Team flexibility | Medium | Frontend team owns BFF |
| Future-proof | Medium | Can add Python ML services behind BFF |
Cons:
| Disadvantage | Impact | Description |
|---|---|---|
| Added complexity | Medium | Another layer to deploy and maintain |
| Extra latency | Low | One more network hop (mitigated by caching) |
| Potential duplication | Low | Some logic might be duplicated |
| Learning curve | Low | Team needs to learn BFF patterns |
ADR-001 Recommendation¶
Selected Option: 1C (Hybrid)
Rationale: 1. Preserves existing FastAPI investment 2. Provides type safety benefits via tRPC 3. Positions for future ML/AI capabilities 4. Allows incremental adoption 5. Frontend team can own the BFF layer
ADR-002: API Architecture Pattern¶
Status: Proposed
Context: Given the hybrid approach, we need to decide the specific architecture pattern for the BFF layer and how it communicates with backend services.
Decision Options¶
| Option | Decision |
|---|---|
| 2A | Backend-for-Frontend (BFF) Pattern |
| 2B | API Gateway Pattern |
| 2C | Direct Frontend-to-Services |
Option 2A: BFF Pattern¶
Decision: Dedicated Node.js backend tailored for the React frontend
┌─────────────────────────────────────────────────────────────────────────────┐
│ BFF PATTERN ARCHITECTURE │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ │
│ │ React │ │
│ │ Frontend │ │
│ │ (TypeScript) │
│ └──────┬──────┘ │
│ │ │
│ │ tRPC (type-safe) │
│ ▼ │
│ ┌─────────────────────────────────────────┐ │
│ │ Node.js BFF Layer │ │
│ │ (NestJS or Express + tRPC) │ │
│ │ │ │
│ │ • Authentication & Session Management │ │
│ │ • Request Aggregation │ │
│ │ • Response Shaping for UI │ │
│ │ • Caching (Redis) │ │
│ │ • Real-time WebSocket Hub │ │
│ │ • Rate Limiting │ │
│ └─────────────────┬───────────────────────┘ │
│ │ │
│ │ REST / gRPC (internal) │
│ ▼ │
│ ┌─────────────────────────────────────────┐ │
│ │ FastAPI Microservices (Python) │ │
│ │ │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ Auth │ │ Ontology│ │ Data │ │ │
│ │ │ Service │ │ Service │ │ Service │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ │ │
│ │ │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │Governance│ │Analytics│ │ ML/AI │ │ │
│ │ │ Service │ │ Service │ │ Service │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ │ │
│ └─────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Pros:
| Advantage | Impact | Description |
|---|---|---|
| UI-optimized API | High | Responses shaped exactly for frontend needs |
| End-to-end types | High | tRPC provides compile-time safety |
| Security isolation | High | Internal services never exposed to internet |
| Request aggregation | Medium | Combine multiple service calls into one |
| Caching layer | Medium | Reduce load on backend services |
| Frontend ownership | Medium | Frontend team controls API shape |
| WebSocket hub | Medium | Centralized real-time handling |
Cons:
| Disadvantage | Impact | Description |
|---|---|---|
| Additional service | Medium | More infrastructure to manage |
| Potential bottleneck | Low | All traffic flows through BFF |
| Code duplication | Low | Some validation may be duplicated |
Option 2B: API Gateway Pattern¶
Decision: Use an API Gateway (Kong, AWS API Gateway) to route to services
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ React │◄───────►│ API Gateway │◄───────►│ FastAPI │
│ (TypeScript)│ REST │ (Kong/AWS) │ REST │ Services │
└──────────────┘ └──────────────┘ └──────────────┘
Pros:
| Advantage | Impact | Description |
|---|---|---|
| Infrastructure solution | Medium | No custom code for routing |
| Built-in features | Medium | Rate limiting, auth, logging |
| Language agnostic | Medium | Works with any backend |
Cons:
| Disadvantage | Impact | Description |
|---|---|---|
| No type safety | High | OpenAPI codegen still required |
| Generic responses | Medium | Can't shape responses for UI |
| No aggregation | Medium | Multiple round trips for complex views |
| Vendor lock-in | Low | Tied to gateway provider |
Option 2C: Direct Frontend-to-Services¶
Decision: Frontend calls backend services directly via OpenAPI client
┌──────────────┐ ┌──────────────┐
│ React │◄────────REST/OpenAPI────────►│ FastAPI │
│ (TypeScript)│ │ Services │
└──────────────┘ └──────────────┘
Pros:
| Advantage | Impact | Description |
|---|---|---|
| Simplicity | High | No additional layers |
| Lower latency | Medium | Direct communication |
| Less infrastructure | Medium | Fewer services to manage |
Cons:
| Disadvantage | Impact | Description |
|---|---|---|
| No type safety | High | Must use OpenAPI codegen |
| Multiple calls | Medium | Frontend makes many requests |
| Security exposure | Medium | Backend services exposed to internet |
| No caching layer | Low | Each request hits backend |
ADR-002 Recommendation¶
Selected Option: 2A (BFF Pattern)
Rationale: 1. Provides end-to-end type safety via tRPC 2. Aggregates requests reducing frontend complexity 3. Centralizes authentication and caching 4. Keeps internal services secure 5. Frontend team has full control over API shape
ADR-003: Database & ORM Selection¶
Status: Proposed
Context: We need to select appropriate database tools for each layer of the architecture.
Decision Options¶
| Layer | Options |
|---|---|
| BFF Layer | Prisma, TypeORM, Drizzle, Kysely |
| Python Services | SQLAlchemy, SQLModel, Tortoise ORM |
BFF Layer ORM Options¶
| ORM | Pros | Cons | Recommendation |
|---|---|---|---|
| Prisma | Type-safe, auto-generated client, migrations, great DX | Newer, some edge cases | Recommended |
| TypeORM | Mature, Active Record & Data Mapper patterns | Complex config, slower | Good alternative |
| Drizzle | Lightweight, SQL-like, fast | Smaller ecosystem | For simple needs |
| Kysely | Type-safe query builder | Not a full ORM | For raw SQL preference |
Recommendation: Prisma
Prisma provides: - Auto-generated TypeScript client - Schema-first workflow - 30% faster complex queries than alternatives - Excellent migrations - Works well with tRPC
Python Services ORM Options¶
| ORM | Pros | Cons | Recommendation |
|---|---|---|---|
| SQLAlchemy | Very mature, flexible, powerful | Steeper learning curve | Recommended |
| SQLModel | Pydantic integration, FastAPI creator | Newer | Good for new services |
| Tortoise ORM | Async-first, Django-like | Smaller community | For async-heavy |
Recommendation: SQLAlchemy (existing) + SQLModel (new services)
ADR-004: API Communication Protocol¶
Status: Proposed
Context: We need to decide how different layers communicate.
Decision Options¶
| Communication Path | Options |
|---|---|
| Frontend ↔ BFF | tRPC, REST, GraphQL |
| BFF ↔ Services | REST, gRPC, Message Queue |
| Service ↔ Service | REST, gRPC, Events |
Frontend ↔ BFF Communication¶
| Protocol | Pros | Cons | Recommendation |
|---|---|---|---|
| tRPC | End-to-end types, no codegen, excellent DX | TS-only | Recommended |
| REST | Universal, cacheable | Manual types | Fallback option |
| GraphQL | Flexible queries | Over-engineering for BFF | Not recommended |
Recommendation: tRPC
BFF ↔ Backend Services Communication¶
| Protocol | Pros | Cons | Recommendation |
|---|---|---|---|
| REST | Simple, FastAPI native | Slower than gRPC | Recommended initially |
| gRPC | High performance, typed | More setup | For high-throughput later |
| Message Queue | Async, decoupled | Complexity | For event-driven features |
Recommendation: REST initially, gRPC for high-throughput services
Architecture Options Overview¶
┌─────────────────────────────────────────────────────────────────────────────┐
│ BACKEND ARCHITECTURE OPTIONS │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ OPTION A: TypeScript Only │
│ ┌──────────┐ ┌──────────────┐ ┌──────────┐ │
│ │ React │◄──►│ Node.js/ │◄──►│ Database │ │
│ │ (TS) │ │ NestJS (TS) │ │ │ │
│ └──────────┘ └──────────────┘ └──────────┘ │
│ │
│ OPTION B: Python Only (Current) │
│ ┌──────────┐ ┌──────────────┐ ┌──────────┐ │
│ │ React │◄──►│ FastAPI │◄──►│ Database │ │
│ │ (TS) │ │ (Python) │ │ │ │
│ └──────────┘ └──────────────┘ └──────────┘ │
│ │
│ OPTION C: Hybrid (BFF Pattern) - RECOMMENDED │
│ ┌──────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────┐ │
│ │ React │◄──►│ Node.js BFF │◄──►│ FastAPI │◄──►│ Database │ │
│ │ (TS) │ │ (TS) │ │ Services │ │ │ │
│ └──────────┘ └──────────────┘ └──────────────┘ └──────────┘ │
│ │
│ OPTION D: Polyglot Microservices │
│ ┌──────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────┐ │
│ │ React │◄──►│ API Gateway │◄──►│ TS Service │◄──►│ Database │ │
│ │ (TS) │ │ │ │ Py Service │ │ │ │
│ └──────────┘ └──────────────┘ └──────────────┘ └──────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Option A: TypeScript Backend (Node.js/NestJS)¶
Overview¶
Replace Python/FastAPI with a TypeScript-based backend using Node.js frameworks like NestJS, Express, or Fastify.
Frameworks Comparison¶
| Framework | Description | Best For |
|---|---|---|
| NestJS | Angular-inspired, modular architecture | Enterprise apps, large teams |
| Express | Minimal, flexible, huge ecosystem | Simple APIs, quick prototypes |
| Fastify | Performance-focused, schema-based | High-throughput APIs |
| Hono | Ultra-light, edge-ready | Serverless, edge functions |
Database Tools (TypeScript)¶
| ORM | Strengths | Weaknesses |
|---|---|---|
| Prisma | Type-safe, auto-generated client, migrations | Newer, some edge cases |
| TypeORM | Mature, Active Record & Data Mapper | Complex config, slower |
| Drizzle | Lightweight, SQL-like, fast | Smaller ecosystem |
| Kysely | Type-safe query builder | Not a full ORM |
Pros & Cons Summary¶
| Category | Details |
|---|---|
| Key Advantages | Single language, shared types, tRPC compatible, unified tooling, real-time excellence |
| Key Disadvantages | Complete rewrite required, team reskilling needed, ML/AI gaps, lost investment |
| Best For | New projects without existing Python codebase, TypeScript-focused teams |
| Avoid When | Significant FastAPI investment exists, ML/AI is core requirement |
Performance Benchmarks (2025)¶
| Metric | Node.js/Express | Python/FastAPI | Winner |
|---|---|---|---|
| Requests/sec (simple) | ~44% higher | Baseline | Node.js |
| Latency (p99) | Lower | Higher | Node.js |
| Startup time | Faster | Slower | Node.js |
| PostgreSQL fetch (avg) | 8ms | 6ms | FastAPI |
| WebSocket connections | Excellent | Good | Node.js |
| ML/AI workloads | Poor | Excellent | FastAPI |
Option B: Python Backend (FastAPI) - Current¶
Overview¶
Continue with existing Python/FastAPI microservices architecture.
Database Tools (Python)¶
| ORM | Strengths | Weaknesses |
|---|---|---|
| SQLAlchemy | Very mature, flexible, powerful | Steeper learning curve |
| Tortoise ORM | Async-first, Django-like | Smaller community |
| SQLModel | FastAPI creator's ORM, Pydantic-based | Newer |
| Prisma Python | Port of Prisma, type-safe | Less mature than TS version |
Pros & Cons Summary¶
| Category | Details |
|---|---|
| Key Advantages | Already built, team expertise, ML/AI native, auto documentation, Pydantic validation |
| Key Disadvantages | Two languages, type drift, no shared code, GIL limitations |
| Best For | Teams with Python expertise, ML/AI-heavy applications |
| Avoid When | Real-time features are critical, frontend team wants API ownership |
Direct Comparison Matrix¶
| Criteria | TypeScript (Node.js) | Python (FastAPI) |
|---|---|---|
| Language Consistency | Same as frontend | Different from frontend |
| Type Sharing | Native | Via OpenAPI codegen |
| Real-Time/WebSockets | Excellent | Good |
| ML/AI Integration | Poor (needs Python) | Excellent |
| Data Processing | Moderate | Excellent |
| Raw Performance | ~44% faster requests | Good async performance |
| Developer Hiring | Full-stack TS common | Python specialists needed |
| Existing Codebase | Requires rewrite | Already built |
| Learning Curve | Low (if team knows TS) | Low (team already uses it) |
| Auto Documentation | Manual (Swagger setup) | Built-in (FastAPI) |
| Validation | Zod, Yup, io-ts | Pydantic (excellent) |
| ORM Maturity | Prisma (good), TypeORM | SQLAlchemy (excellent) |
Option C: Hybrid BFF Pattern¶
Overview¶
Add a Node.js Backend-for-Frontend layer while preserving existing FastAPI microservices.
Architecture¶
┌─────────────────────────────────────────────────────────────────────────────┐
│ BFF PATTERN ARCHITECTURE │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ │
│ │ React │ │
│ │ Frontend │ │
│ │ (TypeScript) │
│ └──────┬──────┘ │
│ │ │
│ │ tRPC / REST │
│ ▼ │
│ ┌─────────────────────────────────────────┐ │
│ │ Node.js BFF Layer │ │
│ │ (TypeScript/NestJS) │ │
│ │ │ │
│ │ • Authentication & Session Management │ │
│ │ • Request Aggregation │ │
│ │ • Response Shaping for UI │ │
│ │ • Caching (Redis) │ │
│ │ • Real-time WebSocket Hub │ │
│ └─────────────────┬───────────────────────┘ │
│ │ │
│ │ REST / gRPC │
│ ▼ │
│ ┌─────────────────────────────────────────┐ │
│ │ FastAPI Microservices (Python) │ │
│ │ │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ Auth │ │ Data │ │ ML/AI │ │ │
│ │ │ Service │ │ Service │ │ Service │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ │ │
│ │ │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │Ontology │ │Governance│ │Analytics│ │ │
│ │ │ Service │ │ Service │ │ Service │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ │ │
│ └─────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
How It Works¶
| Layer | Responsibilities |
|---|---|
| Frontend | Communicates ONLY with the BFF layer via tRPC |
| BFF (Node.js) | Auth, aggregation, response shaping, WebSockets, caching |
| FastAPI Services | Core business logic, data processing, ML/AI, database ops |
Pros & Cons Summary¶
| Category | Details |
|---|---|
| Key Advantages | Preserves investment, type safety via tRPC, best of both worlds, incremental adoption, security boundary |
| Key Disadvantages | Added complexity, extra latency hop, potential duplication |
| Best For | Existing FastAPI codebase, need for real-time features, frontend team wants API ownership |
| Avoid When | Very simple API needs, team can't maintain two runtimes |
When to Use BFF¶
- Multiple frontend clients (web, mobile, etc.)
- Need real-time features (WebSockets)
- Want tRPC type safety without rewriting backend
- Frontend team wants more control over API shape
- Need request aggregation for complex views
Option D: Polyglot Microservices¶
Overview¶
Run services in different languages based on their optimal use case, unified by an API Gateway.
Architecture¶
┌─────────────────────────────────────────────────────────────────────────────┐
│ POLYGLOT MICROSERVICES │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ │
│ │ React │ │
│ │ Frontend │ │
│ └──────┬──────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────┐ │
│ │ API Gateway / Load Balancer │ │
│ │ (Kong / AWS ALB / Traefik) │ │
│ └─────────────────┬───────────────────────┘ │
│ │ │
│ ┌───────────────┼───────────────┬───────────────┐ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ User │ │ Data │ │ ML/AI │ │ Realtime│ │
│ │ Service │ │ Service │ │ Service │ │ Service │ │
│ │ │ │ │ │ │ │ │ │
│ │ Node.js │ │ FastAPI │ │ FastAPI │ │ Node.js │ │
│ │ + Prisma│ │ + SQLAlch│ │ + PyTorch│ │ + WS │ │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
│ │
│ Message Broker (Kafka / RabbitMQ) │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Service Distribution Example¶
| Service | Language | Rationale |
|---|---|---|
| User/Auth Service | Node.js/TypeScript | Type sharing with frontend, session management |
| Ontology Service | Python/FastAPI | Complex data processing, graph operations |
| ML/AI Service | Python/FastAPI | TensorFlow, PyTorch, pandas integration |
| Real-Time Service | Node.js/TypeScript | WebSocket handling, live updates |
| Analytics Service | Python/FastAPI | Data aggregation, reporting |
| Notification Service | Node.js/TypeScript | Push notifications, email queues |
Communication Patterns¶
| Pattern | Use Case | Tools |
|---|---|---|
| REST | Simple CRUD operations | HTTP/JSON |
| gRPC | High-performance inter-service | Protocol Buffers |
| Message Queue | Async processing, events | Kafka, RabbitMQ |
| GraphQL Federation | Unified API from multiple services | Apollo Federation |
Pros & Cons Summary¶
| Category | Details |
|---|---|
| Key Advantages | Optimal tech per service, independent scaling, team autonomy, fault isolation, gradual migration |
| Key Disadvantages | Operational complexity, type safety gaps, debugging difficulty, onboarding challenge |
| Best For | Large teams, complex domains, high-scale requirements |
| Avoid When | Small team, limited DevOps capacity, simple domain |
Decision Framework¶
┌─────────────────────────────────────────────────────────────────┐
│ DECISION FLOWCHART │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Do you have existing FastAPI services? │
│ ├─► YES ──► Do you want to preserve them? │
│ │ ├─► YES ──► Option C (BFF) or D (Polyglot) │
│ │ └─► NO ───► Option A (Full TypeScript) │
│ └─► NO ───► What is team's primary expertise? │
│ ├─► TypeScript ──► Option A (Full TypeScript) │
│ └─► Python ─────► Option B (Full Python) │
│ │
│ Do you need ML/AI capabilities? │
│ ├─► YES ──► Keep Python services (Option B, C, or D) │
│ └─► NO ───► Consider full TypeScript (Option A) │
│ │
│ Do you need real-time/WebSocket features? │
│ ├─► YES ──► Add Node.js layer (Option A, C, or D) │
│ └─► NO ───► Python FastAPI is sufficient │
│ │
│ Is end-to-end type safety critical? │
│ ├─► YES ──► Option A (tRPC native) or C (BFF with tRPC) │
│ └─► NO ───► OpenAPI codegen is sufficient (Option B) │
│ │
│ What is your team size? │
│ ├─► Small (< 5) ──► Option B or C │
│ ├─► Medium (5-15) ──► Option C │
│ └─► Large (> 15) ──► Option C or D │
│ │
└─────────────────────────────────────────────────────────────────┘
Recommendation¶
For Bast Admin UI: Option C (Hybrid BFF Pattern)¶
Given your context: - ✅ Existing FastAPI microservices - ✅ TypeScript React frontend - ✅ Multi-org, multi-environment complexity - ✅ Ontology builder (potentially ML-assisted)
┌─────────────────────────────────────────────────────────────────┐
│ RECOMMENDED ARCHITECTURE │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────────────────────────┐ │
│ │ Bast Admin │ tRPC │ Node.js BFF │ │
│ │ React UI │◄───────►│ (NestJS/Express) │ │
│ │ │ │ │ │
│ │ • TypeScript │ │ • Auth/Session management │ │
│ │ • TanStack Q │ │ • WebSocket hub │ │
│ │ │ │ • Request aggregation │ │
│ └──────────────┘ │ • Caching layer │ │
│ └──────────────┬───────────────────┘ │
│ │ REST │
│ ▼ │
│ ┌──────────────────────────────────┐ │
│ │ FastAPI Microservices │ │
│ │ (Existing - No Changes) │ │
│ │ │ │
│ │ • Core business logic │ │
│ │ • Ontology processing │ │
│ │ • Data governance │ │
│ │ • ML/AI capabilities (future) │ │
│ └──────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Why This Works¶
| Benefit | Description |
|---|---|
| Preserves Investment | No rewrite of existing FastAPI services |
| Type Safety | tRPC between React and BFF provides end-to-end types |
| Real-Time Ready | Node.js BFF handles WebSockets natively |
| Future-Proof | Can add Python ML services behind BFF |
| Security | BFF handles auth; internal services stay internal |
| Incremental | Can start with BFF for one feature, expand gradually |
Gradual Migration Path¶
Phase 1: Add TypeScript BFF
Phase 2: New Services in TypeScript
Phase 3: Migrate as Needed
Architecture Comparison Summary¶
| Criteria | Option A (TS Only) | Option B (Python Only) | Option C (BFF) | Option D (Polyglot) |
|---|---|---|---|---|
| Migration Effort | High | None | Low-Medium | Medium |
| Type Safety | Excellent | Good (codegen) | Excellent | Good |
| ML/AI Support | Poor | Excellent | Excellent | Excellent |
| Real-Time | Excellent | Good | Excellent | Excellent |
| Complexity | Low | Low | Medium | High |
| Team Flexibility | Medium | Medium | High | Very High |
| Operational Overhead | Low | Low | Medium | High |
| Recommendation | New projects | Simple APIs | Most projects | Large scale |
Sources¶
TypeScript vs Python Backend¶
- Node.js vs Python: Best Backend Choice for 2025 - Kanhasoft
- Battle of the Backends: FastAPI vs Node.js - HostAdvice
- Node.js vs Python Benchmarks - DEV Community
- TypeScript vs Python 2025 - Leanware
- Node.js vs FastAPI for Building APIs - PLANEKS
- Backend Battle 2025: FastAPI vs Express - Slincom
- FastAPI vs NestJS - Medium
Hybrid & Polyglot Architecture¶
- Polyglot Architecture - Confluent
- Analyzing Polyglot Microservices - Capital One Tech
- Future of Cross Platform Development: Polyglot Architectures - Medium
- Why Think Twice Before Polyglot Microservices - Codeboje
BFF Pattern¶
- 5 Best Practices for BFFs - WunderGraph
- Backend for Frontend Pattern - Auth0
- Backends for Frontends Pattern - AWS
- Complete Guide to BFF - Christian Lüdemann
- NestJS-BFF Starter - GitHub
Database & ORM Comparison¶
- Prisma vs SQLAlchemy - Medium
- Prisma vs TypeORM 2025 - Bytebase
- TypeORM vs Prisma vs SQLAlchemy - Medium
- Top 5 ORMs for Developers 2025 - Strapi
Document generated for Bast Admin UI Backend Architecture Planning