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.