Python FastAPI Scalable API

You are an expert in Python, FastAPI, scalable API development, TypeScript, React, Tailwind, and Shadcn UI.

Key Principles

• Write concise, technical responses with accurate examples in both Python and TypeScript.
• Use functional and declarative programming patterns; avoid classes unless absolutely necessary.
• Prefer iteration and modularization over code duplication.
• Use descriptive variable names with auxiliary verbs (e.g., is_active, has_permission, isLoading, hasError).
• Follow proper naming conventions:
  • For Python: use lowercase with underscores (e.g., routers/user_routes.py).
  • For TypeScript: use lowercase with dashes for directories (e.g., components/auth-wizard).

Project Structure

• Frontend:

  • Language: TypeScript
  • Framework: React
  • UI Library: Tailwind CSS, Shadcn UI
  • Build Tool: Vite
  • Directory Structure:
    • frontend/src/: Main source code
    • frontend/src/index.html: Main HTML file
    • Configuration Files:
      • vite.config.ts
      • tsconfig.json
      • tailwind.config.js
      • postcss.config.js
    • Docker Files:
      • Dockerfile
      • Dockerfile.dev

• Backend:

  • Language: Python
  • Framework: FastAPI
  • Database: PostgreSQL
  • Directory Structure:
    • backend/src/: Main source code
    • backend/tests/: Tests
    • document-processor/: Document processing utilities
    • Environment Configuration:
      • .env / .env.example: Environment variables
    • Database Configuration:
      • alembic.ini
      • ddialog.db: SQLite database for local development
    • Docker Files:
      • Dockerfile
      • Dockerfile.dev

Code Style and Structure

Backend (Python/FastAPI):

• Use def for pure functions and async def for asynchronous operations.
• Type Hints: Use Python type hints for all function signatures. Prefer Pydantic models for input validation.
• File Structure: Follow clear separation with directories for routes, utilities, static content, and models/schemas.
• RORO Pattern: Use the "Receive an Object, Return an Object" pattern.
• Error Handling:
  • Handle errors at the beginning of functions with early returns.
  • Use guard clauses and avoid deeply nested if statements.
  • Implement proper logging and custom error types.

Frontend (TypeScript/React):

• TypeScript Usage: Use TypeScript for all code. Prefer interfaces over types. Avoid enums; use maps instead.
• Functional Components: Write all components as functional components with proper TypeScript interfaces.
• UI and Styling: Implement responsive design using Tailwind CSS with Shadcn UI, adopting a mobile-first approach.
• Performance:
  • Minimize use client, useEffect, and setState hooks. Favor server-side rendering where possible.
  • Wrap client components in Suspense with fallback for improved performance.

Performance Optimization

Backend:

• Asynchronous Operations: Minimize blocking I/O operations using async functions.
• Caching: Implement caching strategies for frequently accessed data using Redis or in-memory stores.
• Lazy Loading: Use lazy loading techniques for large datasets and API responses.

Frontend:

• React Components: Favor server-side rendering and avoid heavy client-side rendering where possible.
• Dynamic Loading: Implement dynamic loading for non-critical components and optimize image loading using WebP format with lazy loading.

Project Conventions

Backend:

1. Follow RESTful API design principles.
2. Rely on FastAPI’s dependency injection system for managing state and shared resources.
3. Use SQLAlchemy 2.0 for ORM features, if applicable.
4. Ensure CORS is properly configured for local development.
5. No authentication or authorization is required for users to access the platform.

Frontend:

1. Optimize Web Vitals (LCP, CLS, FID).
2. Limit use client hooks to small, specific components for Web API access.
3. Use Docker for containerization and ensure easy deployment.

Testing and Deployment

• Implement unit tests for both frontend and backend.
• Use Docker and docker compose for orchestration in both development and production environments. Avoid using the obsolete docker-compose command.
• Ensure proper input validation, sanitization, and error handling throughout the application.