Name: backend
Author: zzw4257

Prompt file imported from zzw4257/free-to-do-app (.cursor/commands/backend.md). Copyright stays with the author.

Backend Development Quick Commands (lifetrace version)

Tech Stack Information

Framework: FastAPI + Uvicorn (async web framework)
Language: Python 3.12
ORM: SQLAlchemy 2.x + SQLModel
Database Migration: Alembic
Data Validation: Pydantic 2.x
Configuration Management: Dynaconf (supports YAML hot reload)
Logging: Loguru
Scheduler: APScheduler (background task scheduling)
OCR: RapidOCR (local OCR recognition)
Vector Database: ChromaDB (optional, for semantic search)
Text Embedding: sentence-transformers (optional)
LLM: OpenAI-compatible API
Package Manager: uv (recommended)
Code Quality: Ruff (lint/format/check)

🏗️ Project Architecture

lifetrace/
├── server.py                 # FastAPI application entry point
├── config/                   # Configuration files directory
│   ├── config.yaml          # User configuration
│   ├── default_config.yaml  # Default configuration
│   └── prompt.yaml          # LLM Prompt templates
├── routers/                  # API routing layer
├── services/                 # Business service layer
├── repositories/             # Data access layer (Repository pattern)
├── schemas/                  # Pydantic data models
├── storage/                  # Data storage layer (SQLAlchemy models)
├── llm/                      # LLM and AI services
├── jobs/                     # Background tasks
├── core/                     # Core dependencies and lazy-loaded services
└── util/                     # Utility functions

Layered Architecture Overview

Router Layer: Handles HTTP requests, parameter validation, calls Service layer
Service Layer: Business logic, orchestrates multiple Repository operations
Repository Layer: Data access abstraction, encapsulates database queries
Schema Layer: Request/response Pydantic models
Storage Layer: SQLAlchemy ORM model definitions

🔧 Route Development

Creating New API Routes

Create new routes in the lifetrace/routers/ directory:

Use APIRouter to define route prefixes and tags
Follow RESTful API design principles
Use dependency injection to get database sessions
Add complete type annotations and docstrings

RESTful Route Conventions

GET /api/{resource} - Get list
GET /api/{resource}/{id} - Get single resource
POST /api/{resource} - Create resource
PUT /api/{resource}/{id} - Full update
PATCH /api/{resource}/{id} - Partial update
DELETE /api/{resource}/{id} - Delete resource

Registering Routes

Import and register new routes in server.py:

Use app.include_router(xxx.router) to register
Routes organized by functional modules

📦 Data Models

Pydantic Schema Conventions

Create data models in the lifetrace/schemas/ directory:

Use Pydantic v2 syntax
Distinguish models for different scenarios: Create, Update, Response, etc.
Use Field() to add validation rules and descriptions
Enable model_config = ConfigDict(from_attributes=True) to support ORM conversion

Common Model Patterns

{Resource}Create - Request body for creation
{Resource}Update - Request body for updates (fields typically Optional)
{Resource}Response - API response format
{Resource}List - List response (includes pagination info)

SQLAlchemy Model Conventions

Define database tables in lifetrace/storage/models.py:

Use SQLAlchemy 2.x declarative syntax
Add indexes for commonly queried fields
Use relationships to define table associations
Add created_at and updated_at timestamp fields

🗄️ Repository Layer

Creating Repositories

Create data access classes in the lifetrace/repositories/ directory:

Inherit or implement interfaces defined in interfaces.py
Encapsulate all database query logic
Use async methods (async def)
Support parameterized queries to prevent SQL injection

Repository Naming Conventions

sql_{resource}_repository.py - SQL database implementation
Class names use {Resource}Repository format

🎯 Service Layer

Creating Services

Create business services in the lifetrace/services/ directory:

Implement complex business logic
Orchestrate multiple Repository operations
Handle transaction boundaries
Call external services (LLM, OCR, etc.)

Service Conventions

Class names use {Resource}Service format
Get Repository instances through dependency injection
Use custom Exception classes for business exceptions
Add detailed logging

🤖 LLM Services

LLM Client Usage

The project uses OpenAI-compatible APIs, encapsulated via llm/llm_client.py:

Supports Alibaba Cloud Tongyi Qianwen, OpenAI, Claude, etc.
Configuration managed through the llm section in config/config.yaml
Supports streaming responses (SSE)

RAG Service

llm/rag_service.py provides Retrieval-Augmented Generation:

Smart time parsing (e.g., "last week", "yesterday")
Hybrid retrieval strategy (vector search + full-text search)
Context compression and ranking

Prompt Management

Prompt templates are stored in config/prompt.yaml:

Use YAML format for easy maintenance
Support variable interpolation
Organized by functional modules

Agno Agent

llm/agno_agent.py provides AI-powered todo management via Agno framework:

FreeTodoToolkit with 14 tools (CRUD, breakdown, time parsing, etc.)
Internationalization support (zh/en)
Mixin-based architecture for extensibility

See .cursor/commands/agno_agent.md for detailed development guide.

⏰ Background Tasks

Task Scheduling

Use APScheduler to manage background tasks:

Tasks defined in lifetrace/jobs/ directory
Managed uniformly through job_manager.py
Supports scheduled tasks and interval tasks

Task Types

recorder: Screen recorder, scheduled screenshots
ocr: OCR processor, processes screenshots awaiting recognition

⚙️ Configuration Management

Configuration File Structure

config/default_config.yaml - Default configuration (do not modify)
config/config.yaml - User configuration (overrides default values)
Uses Dynaconf to support configuration hot reload

Accessing Configuration

Access through the settings object in util/settings.py:

settings.server.port - Access nested configuration
settings.get("key", default) - Access with default value

Configuration Hot Reload

The following configurations support hot reload (no restart required):

LLM configuration
Recording configuration
OCR configuration

📝 Logging

Using Loguru

Import logger from util/logging_config.py:

logger.info() - General information
logger.warning() - Warning information
logger.error() - Error information
logger.debug() - Debug information

Logging Conventions

Critical operations must be logged
Exceptions must log full stack traces
Sensitive information (API Keys, etc.) must be sanitized
Use structured logging for easier analysis

🗃️ Database Migration

Using Alembic

The project uses Alembic to manage database migrations:

Configuration file: alembic.ini
Migration scripts: migrations/versions/

Common Commands

alembic revision --autogenerate -m "description" - Generate migration script
alembic upgrade head - Apply all migrations
alembic downgrade -1 - Rollback one version
alembic history - View migration history

🧪 Code Quality

Ruff Checking and Formatting

The project uses Ruff for code checking and formatting:

uv run ruff check . - Check code
uv run ruff check --fix . - Auto-fix issues
uv run ruff format . - Format code

Code Standards

Follow PEP 8 style guide
Maximum 100 characters per line
Maximum 500 lines per file (warning threshold 700 lines)
Maximum 50 statements per function
Cyclomatic complexity should not exceed 15

🔐 Error Handling

HTTP Exceptions

Use FastAPI's HTTPException:

400 - Request parameter error
404 - Resource not found
422 - Validation error (automatically handled by Pydantic)
500 - Internal server error

Exception Handling Conventions

Catch specific exceptions, avoid catching all exceptions
Log errors with context
Return user-friendly error messages
Do not expose sensitive information to clients

🚀 Performance Optimization

Database Query Optimization

Use selectinload to avoid N+1 queries
Add indexes for commonly queried fields
Use pagination to limit returned data
Use batch operations instead of looping single operations

Async Processing

Use async/await for I/O operations
Use async sessions for database queries
Use async clients for external API calls

Lazy Loading

Large services (vector service, OCR) use lazy loading
Initialize on-demand through core/lazy_services.py
Avoid loading all dependencies at startup

📡 API and Frontend Interaction

Naming Style Conversion

Backend uses snake_case, frontend uses camelCase:

Frontend fetcher automatically converts
Backend Schema uniformly uses snake_case
OpenAPI Schema automatically generated by FastAPI

Frontend Code Generation

Frontend uses Orval to automatically generate API code from OpenAPI Schema:

After backend API changes, frontend runs pnpm orval to regenerate
Ensure OpenAPI Schema is complete and accurate

📋 Dependency Management

Using uv

The project uses uv as package manager:

uv sync - Sync dependencies
uv add <package> - Add dependency
uv remove <package> - Remove dependency
uv run <command> - Run command in virtual environment

Dependency Groups

Main dependencies: dependencies in pyproject.toml
Development dependencies: dependency-groups.dev
Optional dependencies: dependency-groups.vector (vector search functionality)

🔍 Debugging and Troubleshooting

Starting Development Server

python -m lifetrace.server - Direct start
uvicorn lifetrace.server:app --reload - Hot reload mode

API Documentation

Swagger UI: http://localhost:8001/docs
ReDoc: http://localhost:8001/redoc
OpenAPI JSON: http://localhost:8001/openapi.json

Log Viewing

Log files located at lifetrace/data/logs/
View via API: GET /api/logs
Adjust log level: modify logging.level in config/config.yaml

✅ Code Review Checklist

Before submitting code, ensure:

# Backend Development Quick Commands (lifetrace version) ## Tech Stack Information - **Framework**: FastAPI + Uvicorn (async web framework) - **Language**: Python 3.12 - **ORM**: SQLAlchemy 2.x + SQLModel - **Database Migration**: Alembic - **Data Validation**: Pydantic 2.x - **Configuration Management**: Dynaconf (supports YAML hot reload) - **Logging**: Loguru - **Scheduler**: APScheduler (background task scheduling) - **OCR**: RapidOCR (local OCR recognition) - **Vector Database**: ChromaDB (optional, for semantic search) - **Text Embedding**: sentence-transformers (optional) - **LLM**: OpenAI-compatible API - **Package Manager**: uv (recommended) - **Code Quality**: Ruff (lint/format/check) --- ## 🏗️ Project Architecture ``` lifetrace/ ├── server.py # FastAPI application entry point ├── config/ # Configuration files directory │ ├── config.yaml # User configuration │ ├── default_config.yaml # Default configuration │ └── prompt.yaml # LLM Prompt templates ├── routers/ # API routing layer ├── services/ # Business service layer ├── repositories/ # Data access layer (Repository pattern) ├── schemas/ # Pydantic data models ├── storage/ # Data storage layer (SQLAlchemy models) ├── llm/ # LLM and AI services ├── jobs/ # Background tasks ├── core/ # Core dependencies and lazy-loaded services └── util/ # Utility functions ``` ### Layered Architecture Overview - **Router Layer**: Handles HTTP requests, parameter validation, calls Service layer - **Service Layer**: Business logic, orchestrates multiple Repository operations - **Repository Layer**: Data access abstraction, encapsulates database queries - **Schema Layer**: Request/response Pydantic models - **Storage Layer**: SQLAlchemy ORM model definitions --- ## 🔧 Route Development ### Creating New API Routes Create new routes in the `lifetrace/routers/` directory: - Use `APIRouter` to define route prefixes and tags - Follow RESTful API design principles - Use dependency injection to get database sessions - Add complete type annotations and docstrings ### RESTful Route Conventions - `GET /api/{resource}` - Get list - `GET /api/{resource}/{id}` - Get single resource - `POST /api/{resource}` - Create resource - `PUT /api/{resource}/{id}` - Full update - `PATCH /api/{resource}/{id}` - Partial update - `DELETE /api/{resource}/{id}` - Delete resource ### Registering Routes Import and register new routes in `server.py`: - Use `app.include_router(xxx.router)` to register - Routes organized by functional modules --- ## 📦 Data Models ### Pydantic Schema Conventions Create data models in the `lifetrace/schemas/` directory: - Use Pydantic v2 syntax - Distinguish models for different scenarios: `Create`, `Update`, `Response`, etc. - Use `Field()` to add validation rules and descriptions - Enable `model_config = ConfigDict(from_attributes=True)` to support ORM conversion ### Common Model Patterns - `{Resource}Create` - Request body for creation - `{Resource}Update` - Request body for updates (fields typically Optional) - `{Resource}Response` - API response format - `{Resource}List` - List response (includes pagination info) ### SQLAlchemy Model Conventions Define database tables in `lifetrace/storage/models.py`: - Use SQLAlchemy 2.x declarative syntax - Add indexes for commonly queried fields - Use relationships to define table associations - Add `created_at` and `updated_at` timestamp fields --- ## 🗄️ Repository Layer ### Creating Repositories Create data access classes in the `lifetrace/repositories/` directory: - Inherit or implement interfaces defined in `interfaces.py` - Encapsulate all database query logic - Use async methods (`async def`) - Support parameterized queries to prevent SQL injection ### Repository Naming Conventions - `sql_{resource}_repository.py` - SQL database implementation - Class names use `{Resource}Repository` format --- ## 🎯 Service Layer ### Creating Services Create business services in the `lifetrace/services/` directory: - Implement complex business logic - Orchestrate multiple Repository operations - Handle transaction boundaries - Call external services (LLM, OCR, etc.) ### Service Conventions - Class names use `{Resource}Service` format - Get Repository instances through dependency injection - Use custom Exception classes for business exceptions - Add detailed logging --- ## 🤖 LLM Services ### LLM Client Usage The project uses OpenAI-compatible APIs, encapsulated via `llm/llm_client.py`: - Supports Alibaba Cloud Tongyi Qianwen, OpenAI, Claude, etc. - Configuration managed through the `llm` section in `config/config.yaml` - Supports streaming responses (SSE) ### RAG Service `llm/rag_service.py` provides Retrieval-Augmented Generation: - Smart time parsing (e.g., "last week", "yesterday") - Hybrid retrieval strategy (vector search + full-text search) - Context compression and ranking ### Prompt Management Prompt templates are stored in `config/prompt.yaml`: - Use YAML format for easy maintenance - Support variable interpolation - Organized by functional modules ### Agno Agent `llm/agno_agent.py` provides AI-powered todo management via [Agno framework](https://docs.agno.com/): - FreeTodoToolkit with 14 tools (CRUD, breakdown, time parsing, etc.) - Internationalization support (zh/en) - Mixin-based architecture for extensibility See `.cursor/commands/agno_agent.md` for detailed development guide. --- ## ⏰ Background Tasks ### Task Scheduling Use APScheduler to manage background tasks: - Tasks defined in `lifetrace/jobs/` directory - Managed uniformly through `job_manager.py` - Supports scheduled tasks and interval tasks ### Task Types - **recorder**: Screen recorder, scheduled screenshots - **ocr**: OCR processor, processes screenshots awaiting recognition --- ## ⚙️ Configuration Management ### Configuration File Structure - `config/default_config.yaml` - Default configuration (do not modify) - `config/config.yaml` - User configuration (overrides default values) - Uses Dynaconf to support configuration hot reload ### Accessing Configuration Access through the `settings` object in `util/settings.py`: - `settings.server.port` - Access nested configuration - `settings.get("key", default)` - Access with default value ### Configuration Hot Reload The following configurations support hot reload (no restart required): - LLM configuration - Recording configuration - OCR configuration --- ## 📝 Logging ### Using Loguru Import logger from `util/logging_config.py`: - `logger.info()` - General information - `logger.warning()` - Warning information - `logger.error()` - Error information - `logger.debug()` - Debug information ### Logging Conventions - Critical operations must be logged - Exceptions must log full stack traces - Sensitive information (API Keys, etc.) must be sanitized - Use structured logging for easier analysis --- ## 🗃️ Database Migration ### Using Alembic The project uses Alembic to manage database migrations: - Configuration file: `alembic.ini` - Migration scripts: `migrations/versions/` ### Common Commands - `alembic revision --autogenerate -m "description"` - Generate migration script - `alembic upgrade head` - Apply all migrations - `alembic downgrade -1` - Rollback one version - `alembic history` - View migration history --- ## 🧪 Code Quality ### Ruff Checking and Formatting The project uses Ruff for code checking and formatting: - `uv run ruff check .` - Check code - `uv run ruff check --fix .` - Auto-fix issues - `uv run ruff format .` - Format code ### Code Standards - Follow PEP 8 style guide - Maximum 100 characters per line - Maximum 500 lines per file (warning threshold 700 lines) - Maximum 50 statements per function - Cyclomatic complexity should not exceed 15 --- ## 🔐 Error Handling ### HTTP Exceptions Use FastAPI's `HTTPException`: - `400` - Request parameter error - `404` - Resource not found - `422` - Validation error (automatically handled by Pydantic) - `500` - Internal server error ### Exception Handling Conventions - Catch specific exceptions, avoid catching all exceptions - Log errors with context - Return user-friendly error messages - Do not expose sensitive information to clients --- ## 🚀 Performance Optimization ### Database Query Optimization - Use `selectinload` to avoid N+1 queries - Add indexes for commonly queried fields - Use pagination to limit returned data - Use batch operations instead of looping single operations ### Async Processing - Use `async/await` for I/O operations - Use async sessions for database queries - Use async clients for external API calls ### Lazy Loading - Large services (vector service, OCR) use lazy loading - Initialize on-demand through `core/lazy_services.py` - Avoid loading all dependencies at startup --- ## 📡 API and Frontend Interaction ### Naming Style Conversion Backend uses `snake_case`, frontend uses `camelCase`: - Frontend fetcher automatically converts - Backend Schema uniformly uses `snake_case` - OpenAPI Schema automatically generated by FastAPI ### Frontend Code Generation Frontend uses Orval to automatically generate API code from OpenAPI Schema: - After backend API changes, frontend runs `pnpm orval` to regenerate - Ensure OpenAPI Schema is complete and accurate --- ## 📋 Dependency Management ### Using uv The project uses uv as package manager: - `uv sync` - Sync dependencies - `uv add <package>` - Add dependency - `uv remove <package>` - Remove dependency - `uv run <command>` - Run command in virtual environment ### Dependency Groups - Main dependencies: `dependencies` in `pyproject.toml` - Development dependencies: `dependency-groups.dev` - Optional dependencies: `dependency-groups.vector` (vector search functionality) --- ## 🔍 Debugging and Troubleshooting ### Starting Development Server - `python -m lifetrace.server` - Direct start - `uvicorn lifetrace.server:app --reload` - Hot reload mode ### API Documentation - Swagger UI: `http://localhost:8001/docs` - ReDoc: `http://localhost:8001/redoc` - OpenAPI JSON: `http://localhost:8001/openapi.json` ### Log Viewing - Log files located at `lifetrace/data/logs/` - View via API: `GET /api/logs` - Adjust log level: modify `logging.level` in `config/config.yaml` --- ## ✅ Code Review Checklist Before submitting code, ensure: - [ ] Code follows PEP 8 style guide - [ ] Running `uv run ruff check .` produces no errors - [ ] Running `uv run ruff format .` to format code - [ ] All functions and classes have type annotations - [ ] All public functions and classes have docstrings - [ ] Appropriate error handling has been added - [ ] Parameterized queries are used to prevent SQL injection - [ ] Necessary logging has been added - [ ] Relevant documentation has been updated - [ ] API changes are reflected in OpenAPI Schema

{ "prompt": "# Backend Development Quick Commands (lifetrace version)\n\n## Tech Stack Information\n\n- **Framework**: FastAPI + Uvicorn (async web framework)\n- **Language**: Python 3.12\n- **ORM**: SQLAlchemy 2.x + SQLModel\n- **Database Migration**: Alembic\n- **Data Validation**: Pydantic 2.x\n- **Configuration Management**: Dynaconf (supports YAML hot reload)\n- **Logging**: Loguru\n- **Scheduler**: APScheduler (background task scheduling)\n- **OCR**: RapidOCR (local OCR recognition)\n- **Vector Database**: ChromaDB (optional, for semantic search)\n- **Text Embedding**: sentence-transformers (optional)\n- **LLM**: OpenAI-compatible API\n- **Package Manager**: uv (recommended)\n- **Code Quality**: Ruff (lint/format/check)\n\n---\n\n## 🏗️ Project Architecture\n\n```\nlifetrace/\n├── server.py # FastAPI application entry point\n├── config/ # Configuration files directory\n│ ├── config.yaml # User configuration\n│ ├── default_config.yaml # Default configuration\n│ └── prompt.yaml # LLM Prompt templates\n├── routers/ # API routing layer\n├── services/ # Business service layer\n├── repositories/ # Data access layer (Repository pattern)\n├── schemas/ # Pydantic data models\n├── storage/ # Data storage layer (SQLAlchemy models)\n├── llm/ # LLM and AI services\n├── jobs/ # Background tasks\n├── core/ # Core dependencies and lazy-loaded services\n└── util/ # Utility functions\n```\n\n### Layered Architecture Overview\n\n- **Router Layer**: Handles HTTP requests, parameter validation, calls Service layer\n- **Service Layer**: Business logic, orchestrates multiple Repository operations\n- **Repository Layer**: Data access abstraction, encapsulates database queries\n- **Schema Layer**: Request/response Pydantic models\n- **Storage Layer**: SQLAlchemy ORM model definitions\n\n---\n\n## 🔧 Route Development\n\n### Creating New API Routes\n\nCreate new routes in the `lifetrace/routers/` directory:\n- Use `APIRouter` to define route prefixes and tags\n- Follow RESTful API design principles\n- Use dependency injection to get database sessions\n- Add complete type annotations and docstrings\n\n### RESTful Route Conventions\n\n- `GET /api/{resource}` - Get list\n- `GET /api/{resource}/{id}` - Get single resource\n- `POST /api/{resource}` - Create resource\n- `PUT /api/{resource}/{id}` - Full update\n- `PATCH /api/{resource}/{id}` - Partial update\n- `DELETE /api/{resource}/{id}` - Delete resource\n\n### Registering Routes\n\nImport and register new routes in `server.py`:\n- Use `app.include_router(xxx.router)` to register\n- Routes organized by functional modules\n\n---\n\n## 📦 Data Models\n\n### Pydantic Schema Conventions\n\nCreate data models in the `lifetrace/schemas/` directory:\n- Use Pydantic v2 syntax\n- Distinguish models for different scenarios: `Create`, `Update`, `Response`, etc.\n- Use `Field()` to add validation rules and descriptions\n- Enable `model_config = ConfigDict(from_attributes=True)` to support ORM conversion\n\n### Common Model Patterns\n\n- `{Resource}Create` - Request body for creation\n- `{Resource}Update` - Request body for updates (fields typically Optional)\n- `{Resource}Response` - API response format\n- `{Resource}List` - List response (includes pagination info)\n\n### SQLAlchemy Model Conventions\n\nDefine database tables in `lifetrace/storage/models.py`:\n- Use SQLAlchemy 2.x declarative syntax\n- Add indexes for commonly queried fields\n- Use relationships to define table associations\n- Add `created_at` and `updated_at` timestamp fields\n\n---\n\n## 🗄️ Repository Layer\n\n### Creating Repositories\n\nCreate data access classes in the `lifetrace/repositories/` directory:\n- Inherit or implement interfaces defined in `interfaces.py`\n- Encapsulate all database query logic\n- Use async methods (`async def`)\n- Support parameterized queries to prevent SQL injection\n\n### Repository Naming Conventions\n\n- `sql_{resource}_repository.py` - SQL database implementation\n- Class names use `{Resource}Repository` format\n\n---\n\n## 🎯 Service Layer\n\n### Creating Services\n\nCreate business services in the `lifetrace/services/` directory:\n- Implement complex business logic\n- Orchestrate multiple Repository operations\n- Handle transaction boundaries\n- Call external services (LLM, OCR, etc.)\n\n### Service Conventions\n\n- Class names use `{Resource}Service` format\n- Get Repository instances through dependency injection\n- Use custom Exception classes for business exceptions\n- Add detailed logging\n\n---\n\n## 🤖 LLM Services\n\n### LLM Client Usage\n\nThe project uses OpenAI-compatible APIs, encapsulated via `llm/llm_client.py`:\n- Supports Alibaba Cloud Tongyi Qianwen, OpenAI, Claude, etc.\n- Configuration managed through the `llm` section in `config/config.yaml`\n- Supports streaming responses (SSE)\n\n### RAG Service\n\n`llm/rag_service.py` provides Retrieval-Augmented Generation:\n- Smart time parsing (e.g., \"last week\", \"yesterday\")\n- Hybrid retrieval strategy (vector search + full-text search)\n- Context compression and ranking\n\n### Prompt Management\n\nPrompt templates are stored in `config/prompt.yaml`:\n- Use YAML format for easy maintenance\n- Support variable interpolation\n- Organized by functional modules\n\n### Agno Agent\n\n`llm/agno_agent.py` provides AI-powered todo management via [Agno framework](https://docs.agno.com/):\n- FreeTodoToolkit with 14 tools (CRUD, breakdown, time parsing, etc.)\n- Internationalization support (zh/en)\n- Mixin-based architecture for extensibility\n\nSee `.cursor/commands/agno_agent.md` for detailed development guide.\n\n---\n\n## ⏰ Background Tasks\n\n### Task Scheduling\n\nUse APScheduler to manage background tasks:\n- Tasks defined in `lifetrace/jobs/` directory\n- Managed uniformly through `job_manager.py`\n- Supports scheduled tasks and interval tasks\n\n### Task Types\n\n- **recorder**: Screen recorder, scheduled screenshots\n- **ocr**: OCR processor, processes screenshots awaiting recognition\n\n---\n\n## ⚙️ Configuration Management\n\n### Configuration File Structure\n\n- `config/default_config.yaml` - Default configuration (do not modify)\n- `config/config.yaml` - User configuration (overrides default values)\n- Uses Dynaconf to support configuration hot reload\n\n### Accessing Configuration\n\nAccess through the `settings` object in `util/settings.py`:\n- `settings.server.port` - Access nested configuration\n- `settings.get(\"key\", default)` - Access with default value\n\n### Configuration Hot Reload\n\nThe following configurations support hot reload (no restart required):\n- LLM configuration\n- Recording configuration\n- OCR configuration\n\n---\n\n## 📝 Logging\n\n### Using Loguru\n\nImport logger from `util/logging_config.py`:\n- `logger.info()` - General information\n- `logger.warning()` - Warning information\n- `logger.error()` - Error information\n- `logger.debug()` - Debug information\n\n### Logging Conventions\n\n- Critical operations must be logged\n- Exceptions must log full stack traces\n- Sensitive information (API Keys, etc.) must be sanitized\n- Use structured logging for easier analysis\n\n---\n\n## 🗃️ Database Migration\n\n### Using Alembic\n\nThe project uses Alembic to manage database migrations:\n- Configuration file: `alembic.ini`\n- Migration scripts: `migrations/versions/`\n\n### Common Commands\n\n- `alembic revision --autogenerate -m \"description\"` - Generate migration script\n- `alembic upgrade head` - Apply all migrations\n- `alembic downgrade -1` - Rollback one version\n- `alembic history` - View migration history\n\n---\n\n## 🧪 Code Quality\n\n### Ruff Checking and Formatting\n\nThe project uses Ruff for code checking and formatting:\n- `uv run ruff check .` - Check code\n- `uv run ruff check --fix .` - Auto-fix issues\n- `uv run ruff format .` - Format code\n\n### Code Standards\n\n- Follow PEP 8 style guide\n- Maximum 100 characters per line\n- Maximum 500 lines per file (warning threshold 700 lines)\n- Maximum 50 statements per function\n- Cyclomatic complexity should not exceed 15\n\n---\n\n## 🔐 Error Handling\n\n### HTTP Exceptions\n\nUse FastAPI's `HTTPException`:\n- `400` - Request parameter error\n- `404` - Resource not found\n- `422` - Validation error (automatically handled by Pydantic)\n- `500` - Internal server error\n\n### Exception Handling Conventions\n\n- Catch specific exceptions, avoid catching all exceptions\n- Log errors with context\n- Return user-friendly error messages\n- Do not expose sensitive information to clients\n\n---\n\n## 🚀 Performance Optimization\n\n### Database Query Optimization\n\n- Use `selectinload` to avoid N+1 queries\n- Add indexes for commonly queried fields\n- Use pagination to limit returned data\n- Use batch operations instead of looping single operations\n\n### Async Processing\n\n- Use `async/await` for I/O operations\n- Use async sessions for database queries\n- Use async clients for external API calls\n\n### Lazy Loading\n\n- Large services (vector service, OCR) use lazy loading\n- Initialize on-demand through `core/lazy_services.py`\n- Avoid loading all dependencies at startup\n\n---\n\n## 📡 API and Frontend Interaction\n\n### Naming Style Conversion\n\nBackend uses `snake_case`, frontend uses `camelCase`:\n- Frontend fetcher automatically converts\n- Backend Schema uniformly uses `snake_case`\n- OpenAPI Schema automatically generated by FastAPI\n\n### Frontend Code Generation\n\nFrontend uses Orval to automatically generate API code from OpenAPI Schema:\n- After backend API changes, frontend runs `pnpm orval` to regenerate\n- Ensure OpenAPI Schema is complete and accurate\n\n---\n\n## 📋 Dependency Management\n\n### Using uv\n\nThe project uses uv as package manager:\n- `uv sync` - Sync dependencies\n- `uv add <package>` - Add dependency\n- `uv remove <package>` - Remove dependency\n- `uv run <command>` - Run command in virtual environment\n\n### Dependency Groups\n\n- Main dependencies: `dependencies` in `pyproject.toml`\n- Development dependencies: `dependency-groups.dev`\n- Optional dependencies: `dependency-groups.vector` (vector search functionality)\n\n---\n\n## 🔍 Debugging and Troubleshooting\n\n### Starting Development Server\n\n- `python -m lifetrace.server` - Direct start\n- `uvicorn lifetrace.server:app --reload` - Hot reload mode\n\n### API Documentation\n\n- Swagger UI: `http://localhost:8001/docs`\n- ReDoc: `http://localhost:8001/redoc`\n- OpenAPI JSON: `http://localhost:8001/openapi.json`\n\n### Log Viewing\n\n- Log files located at `lifetrace/data/logs/`\n- View via API: `GET /api/logs`\n- Adjust log level: modify `logging.level` in `config/config.yaml`\n\n---\n\n## ✅ Code Review Checklist\n\nBefore submitting code, ensure:\n\n- [ ] Code follows PEP 8 style guide\n- [ ] Running `uv run ruff check .` produces no errors\n- [ ] Running `uv run ruff format .` to format code\n- [ ] All functions and classes have type annotations\n- [ ] All public functions and classes have docstrings\n- [ ] Appropriate error handling has been added\n- [ ] Parameterized queries are used to prevent SQL injection\n- [ ] Necessary logging has been added\n- [ ] Relevant documentation has been updated\n- [ ] API changes are reflected in OpenAPI Schema", "variables": [], "notes": "Create new routes in the `lifetrace/routers/` directory: - Use `APIRouter` to define route prefixes and tags - Follow RESTful API design principles - Use dependency injection to get database sessions - Add complete type annotations and docstrings", "metadata": { "source": { "provider": "github-cursor-commands", "repository": "https://github.com/zzw4257/free-to-do-app", "path": ".cursor/commands/backend.md", "ref": "4312e3ff40b6f4f396d26e9b4cc41a38e41fae3f", "url": "https://github.com/zzw4257/free-to-do-app/blob/4312e3ff40b6f4f396d26e9b4cc41a38e41fae3f/.cursor/commands/backend.md", "key": "zzw4257/free-to-do-app/.cursor/commands/backend.md" } } }

About