# Project Architecture
- Name GET routes using `read_<name>` convention
- Follow Post-Redirect-Get (PRG) pattern for all form submissions
- Use Jinja2 HTML templates for server-side rendering and minimize client-side JavaScript
- Use forms for all POST routes
- Validate form data comprehensively on the client side as first line of defense, with server-side Pydantic validation as fallback
- Use middleware defined in main.py for centralized exception handling
- Add type hints to all function signatures and variables for static type checking

# File Structure
- `main.py`: Application entry point and GET routes
- `routers/core`: Base webapp template API routes
- `routers/app`: Application API routes that extend the template
- `utils/core`, `utils/app`: Helper functions, FastAPI dependencies, database models
- `templates/`: Jinja2 templates
- `static/`: Static assets
- `tests/`: Unit tests
- `docker-compose.yml`: Test database configuration
- `.env`: Environment variables
- `docs/`: Quarto documentation website source files

# Database Operations
- Use SQLModel for all database interactions
- Use `get_session()` FastAPI dependency from `utils/core/dependencies.py` for database connections

# Authentication System
- JWT-based token authentication with separate access/refresh tokens and bcrypt for password hashing are defined in `utils/core/auth.py`
- Password and email reset tokens with expiration and password reset email flow powered by Resend are defined in `utils/core/auth.py`
- HTTP-only cookies are implemented with secure flag and `SameSite=strict`
- Inject `common_authenticated_parameters` as a dependency in all authenticated GET routes
- Inject `common_unauthenticated_parameters` as a dependency in all unauthenticated GET routes

# Contributing Guidelines
- Follow existing code style and patterns
- Preserve existing comments and docstrings
- Ensure all tests pass before submitting PR
- Update .qmd documentation files for significant changes
- Use uv for dependency management
- Run `uv run mypy .` to ensure code passes a static type check