> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heygaia.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Code Style Guide

> Coding standards and best practices for GAIA development

## Python Style Guide

### General Guidelines

* Follow [PEP 8](https://peps.python.org/pep-0008/) for Python code style
* Use type hints for all function parameters and return values
* Include comprehensive docstrings for all modules, classes, and functions
* Run `mise lint` before committing to ensure code quality

### Linting and Formatting

Check code quality:

```bash theme={null}
mise lint
```

Auto-fix issues:

```bash theme={null}
mise lint:fix
```

Format code:

```bash theme={null}
mise format
```

Type checking:

```bash theme={null}
mise mypy
```

### Route Handler Best Practices

Route handlers should be thin wrappers around service functions:

```python theme={null}
@router.post("/resource", response_model=ResourceResponse)
async def create_resource_endpoint(
    resource: ResourceModel,
    user: dict = Depends(get_current_user)
):
    """
    Create a new resource.

    Args:
        resource: The resource data
        user: The authenticated user information

    Returns:
        The created resource
    """
    return await create_resource(resource, user["user_id"])
```

### Service Function Best Practices

Service functions should contain the business logic:

```python theme={null}
async def create_resource(resource: ResourceModel, user_id: str) -> ResourceResponse:
    """
    Create a new resource in the database.

    Args:
        resource: The resource data model
        user_id: The ID of the user creating the resource

    Returns:
        ResourceResponse: The created resource with additional metadata

    Raises:
        HTTPException: If resource creation fails
    """
    # Implementation logic here
    return resource_response
```

## TypeScript/JavaScript Style Guide

### Web Standards

* Use TypeScript for all new code
* Follow Biome configuration for formatting and linting
* Prefer functional components and hooks

### Linting and Formatting

Check code quality:

```bash theme={null}
mise lint
```

Auto-fix issues:

```bash theme={null}
mise lint:fix
```

Format code:

```bash theme={null}
mise format
```

Type checking:

```bash theme={null}
mise type
```

## Commit Message Format

Follow [conventional commits](/configuration/conventional-commits) format:

```
type(scope): description

[optional body]

[optional footer]
```

**Types:**

* `feat`: New feature
* `fix`: Bug fix
* `docs`: Documentation changes
* `style`: Code style changes (formatting, etc.)
* `refactor`: Code refactoring
* `test`: Adding or updating tests
* `chore`: Maintenance tasks

**Example:**

```bash theme={null}
git commit -m "feat(auth): add OAuth2 token refresh endpoint"
```

## Testing Standards

* Write tests for all new features and bug fixes
* Maintain or improve code coverage
* Both unit and integration tests are encouraged

Run tests:

```bash theme={null}
mise test
```

## Additional Resources

* [FastAPI Documentation](https://fastapi.tiangolo.com/)
* [Pydantic Documentation](https://docs.pydantic.dev/)
* [Next.js Documentation](https://nextjs.org/docs)
* [TypeScript Documentation](https://www.typescriptlang.org/docs/)