{"filename":"python-fastapi-scalable-api-cursorrules-prompt-fil.mdc","content":"---\ndescription: \"Cursor rules for Python FastAPI development with scalable API integration.\"\nglobs: **/*\nalwaysApply: false\n---\nYou are an expert in **Python, FastAPI, scalable API development, TypeScript, React, Tailwind,** and **Shadcn UI**.\n\n### Key Principles\n\n- Write concise, technical responses with accurate examples in both Python and TypeScript.\n- Use **functional and declarative programming patterns**; avoid classes unless absolutely necessary.\n- Prefer **iteration and modularization** over code duplication.\n- Use descriptive variable names with auxiliary verbs (e.g., `is_active`, `has_permission`, `isLoading`, `hasError`).\n- Follow proper **naming conventions**:  \n  - For Python: use lowercase with underscores (e.g., `routers/user_routes.py`).  \n  - For TypeScript: use lowercase with dashes for directories (e.g., `components/auth-wizard`).\n\n### Project Structure\n\n- **Frontend**:  \n  - **Language**: TypeScript  \n  - **Framework**: React  \n  - **UI Library**: Tailwind CSS, Shadcn UI  \n  - **Build Tool**: Vite  \n  - **Directory Structure**:  \n    - `frontend/src/`: Main source code  \n    - `frontend/src/index.html`: Main HTML file  \n    - Configuration Files:  \n      - `vite.config.ts`  \n      - `tsconfig.json`  \n      - `tailwind.config.js`  \n      - `postcss.config.js`  \n    - **Docker Files**:  \n      - `Dockerfile`  \n      - `Dockerfile.dev`\n\n- **Backend**:  \n  - **Language**: Python  \n  - **Framework**: FastAPI  \n  - **Database**: PostgreSQL  \n  - **Directory Structure**:  \n    - `backend/src/`: Main source code  \n    - `backend/tests/`: Tests  \n    - `document-processor/`: Document processing utilities  \n    - Environment Configuration:  \n      - `.env` / `.env.example`: Environment variables  \n    - Database Configuration:  \n      - `alembic.ini`  \n      - `ddialog.db`: SQLite database for local development  \n    - **Docker Files**:  \n      - `Dockerfile`  \n      - `Dockerfile.dev`\n\n### Code Style and Structure\n\n**Backend (Python/FastAPI)**:\n\n- Use `def` for pure functions and `async def` for asynchronous operations.\n- **Type Hints**: Use Python type hints for all function signatures. Prefer Pydantic models for input validation.\n- **File Structure**: Follow clear separation with directories for routes, utilities, static content, and models/schemas.\n- **RORO Pattern**: Use the \"Receive an Object, Return an Object\" pattern.\n- **Error Handling**:  \n  - Handle errors at the beginning of functions with early returns.  \n  - Use guard clauses and avoid deeply nested if statements.  \n  - Implement proper logging and custom error types.\n\n**Frontend (TypeScript/React)**:\n\n- **TypeScript Usage**: Use TypeScript for all code. Prefer interfaces over types. Avoid enums; use maps instead.\n- **Functional Components**: Write all components as functional components with proper TypeScript interfaces.\n- **UI and Styling**: Implement responsive design using Tailwind CSS with Shadcn UI, adopting a mobile-first approach.\n- **Performance**:  \n  - Minimize `use client`, `useEffect`, and `setState` hooks. Favor server-side rendering where possible.  \n  - Wrap client components in `Suspense` with fallback for improved performance.\n\n### Performance Optimization\n\n**Backend**:\n\n- **Asynchronous Operations**: Minimize blocking I/O operations using async functions.\n- **Caching**: Implement caching strategies for frequently accessed data using Redis or in-memory stores.\n- **Lazy Loading**: Use lazy loading techniques for large datasets and API responses.\n\n**Frontend**:\n\n- **React Components**: Favor server-side rendering and avoid heavy client-side rendering where possible.\n- **Dynamic Loading**: Implement dynamic loading for non-critical components and optimize image loading using WebP format with lazy loading.\n\n### Project Conventions\n\n**Backend**:\n\n1. Follow **RESTful API design principles**.\n2. Rely on **FastAPI’s dependency injection system** for managing state and shared resources.\n3. Use **SQLAlchemy 2.0** for ORM features, if applicable.\n4. Ensure **CORS** is properly configured for local development.\n5. No authentication or authorization is required for users to access the platform.\n\n**Frontend**:\n\n1. Optimize **Web Vitals** (LCP, CLS, FID).\n2. Limit `use client` hooks to small, specific components for Web API access.\n3. Use **Docker** for containerization and ensure easy deployment.\n\n### Testing and Deployment\n\n- Implement **unit tests** for both frontend and backend.\n- Use **Docker** and **docker compose** for orchestration in both development and production environments. Avoid using the obsolete `docker-compose` command.\n- Ensure proper input validation, sanitization, and error handling throughout the application.\n"}