Python FastAPI Scalable API

1You are an expert in **Python, FastAPI, scalable API development, TypeScript, React, Tailwind,** and **Shadcn UI**.
2 
3### Key Principles
4 
5- Write concise, technical responses with accurate examples in both Python and TypeScript.
6- Use **functional and declarative programming patterns**; avoid classes unless absolutely necessary.
7- Prefer **iteration and modularization** over code duplication.
8- Use descriptive variable names with auxiliary verbs (e.g., `is_active`, `has_permission`, `isLoading`, `hasError`).
9- Follow proper **naming conventions**:  
10  - For Python: use lowercase with underscores (e.g., `routers/user_routes.py`).  
11  - For TypeScript: use lowercase with dashes for directories (e.g., `components/auth-wizard`).
12 
13### Project Structure
14 
15- **Frontend**:  
16  - **Language**: TypeScript  
17  - **Framework**: React  
18  - **UI Library**: Tailwind CSS, Shadcn UI  
19  - **Build Tool**: Vite  
20  - **Directory Structure**:  
21    - `frontend/src/`: Main source code  
22    - `frontend/src/index.html`: Main HTML file  
23    - Configuration Files:  
24      - `vite.config.ts`  
25      - `tsconfig.json`  
26      - `tailwind.config.js`  
27      - `postcss.config.js`  
28    - **Docker Files**:  
29      - `Dockerfile`  
30      - `Dockerfile.dev`
31 
32- **Backend**:  
33  - **Language**: Python  
34  - **Framework**: FastAPI  
35  - **Database**: PostgreSQL  
36  - **Directory Structure**:  
37    - `backend/src/`: Main source code  
38    - `backend/tests/`: Tests  
39    - `document-processor/`: Document processing utilities  
40    - Environment Configuration:  
41      - `.env` / `.env.example`: Environment variables  
42    - Database Configuration:  
43      - `alembic.ini`  
44      - `ddialog.db`: SQLite database for local development  
45    - **Docker Files**:  
46      - `Dockerfile`  
47      - `Dockerfile.dev`
48 
49### Code Style and Structure
50 
51**Backend (Python/FastAPI)**:
52 
53- Use `def` for pure functions and `async def` for asynchronous operations.
54- **Type Hints**: Use Python type hints for all function signatures. Prefer Pydantic models for input validation.
55- **File Structure**: Follow clear separation with directories for routes, utilities, static content, and models/schemas.
56- **RORO Pattern**: Use the "Receive an Object, Return an Object" pattern.
57- **Error Handling**:  
58  - Handle errors at the beginning of functions with early returns.  
59  - Use guard clauses and avoid deeply nested if statements.  
60  - Implement proper logging and custom error types.
61 
62**Frontend (TypeScript/React)**:
63 
64- **TypeScript Usage**: Use TypeScript for all code. Prefer interfaces over types. Avoid enums; use maps instead.
65- **Functional Components**: Write all components as functional components with proper TypeScript interfaces.
66- **UI and Styling**: Implement responsive design using Tailwind CSS with Shadcn UI, adopting a mobile-first approach.
67- **Performance**:  
68  - Minimize `use client`, `useEffect`, and `setState` hooks. Favor server-side rendering where possible.  
69  - Wrap client components in `Suspense` with fallback for improved performance.
70 
71### Performance Optimization
72 
73**Backend**:
74 
75- **Asynchronous Operations**: Minimize blocking I/O operations using async functions.
76- **Caching**: Implement caching strategies for frequently accessed data using Redis or in-memory stores.
77- **Lazy Loading**: Use lazy loading techniques for large datasets and API responses.
78 
79**Frontend**:
80 
81- **React Components**: Favor server-side rendering and avoid heavy client-side rendering where possible.
82- **Dynamic Loading**: Implement dynamic loading for non-critical components and optimize image loading using WebP format with lazy loading.
83 
84### Project Conventions
85 
86**Backend**:
87 
881. Follow **RESTful API design principles**.
892. Rely on **FastAPI’s dependency injection system** for managing state and shared resources.
903. Use **SQLAlchemy 2.0** for ORM features, if applicable.
914. Ensure **CORS** is properly configured for local development.
925. No authentication or authorization is required for users to access the platform.
93 
94**Frontend**:
95 
961. Optimize **Web Vitals** (LCP, CLS, FID).
972. Limit `use client` hooks to small, specific components for Web API access.
983. Use **Docker** for containerization and ensure easy deployment.
99 
100### Testing and Deployment
101 
102- Implement **unit tests** for both frontend and backend.
103- Use **Docker** and **docker compose** for orchestration in both development and production environments. Avoid using the obsolete `docker-compose` command.
104- Ensure proper input validation, sanitization, and error handling throughout the application.
105 
106