# Project Architecture - Name GET routes using `read_` 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