Merge branch 'main' of https://github.com/Promptly-Technologies-LLC/fastapi-jinja2-postgres-webapp

Author: chriscarrollsmith

.cursorrules

@@ -0,0 +1,75 @@
+# Project Architecture
+- Keep GET routes in main.py and POST routes in routers/ directory
+- 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
+
+# File Structure
+- main.py: Application entry point and GET routes
+- routers/: POST route modules
+- templates/: Jinja2 templates
+- static/: Static assets
+- tests/: Unit tests
+- utils/: Helper functions and models
+- docker-compose.yml: Test database configuration
+- .env: Environment variables
+
+# Python/FastAPI Guidelines
+- For all POST routes, define request models in a separate section at the top of the router file
+- Implement as_form() classmethod for all form-handling request models
+- Use Pydantic for request/response models with @field_validator and custom exceptions for custom form validation
+- Use middleware defined in main.py for centralized exception handling
+- Add type hints to all function signatures and variables
+- Follow mypy type checking standards rigorously
+
+# Form Validation Strategy
+- Implement thorough client-side validation via HTML pattern attributes where possible and Javascript otherwise
+- Use Pydantic models with custom validators as server-side fallback
+- Handle validation errors through middleware exception handlers
+- Render validation_error.html template for failed server-side validation
+
+# Database Operations
+- Use SQLModel for all database interactions
+- Use get_session() from utils/db.py for database connections
+- Define database relational models explicitly in utils/models.py
+- Inject database session as dependency in route handlers
+
+# Authentication System
+- JWT-based token authentication with separate access/refresh tokens and bcrypt for password hashing are defined in utils/auth.py
+- Password and email reset tokens with expiration and password reset email flow powered by Resend are defined in utils/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
+- Inject get_session as a dependency in all POST routes
+- Handle security-related errors without leaking information
+
+# Testing
+- Run mypy type checking before committing code
+- Write comprehensive unit tests using pytest
+- Test both success and error cases
+- Use test fixtures from tests/conftest.py: engine, session, client, test_user
+- set_up_database and clean_db fixtures are autoused by pytest to ensure clean database state
+
+# Error Handling
+- Use middleware for centralized exception handling
+- Define custom exception classes for specific error cases
+- Return appropriate HTTP status codes and error messages
+- Render error templates with context data
+- Log errors with "uvicorn.error" logger
+
+# Template Structure
+- Extend base.html for consistent layout
+- Use block tags for content sections
+- Include reusable components
+- Pass request object and context data to all templates
+- Keep form validation logic in corresponding templates
+- Use Bootstrap for styling
+
+# 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 Poetry for dependency management

docs/customization.qmd

@@ -25,7 +25,8 @@ The following fixtures, defined in `tests/conftest.py`, are available in the tes
 - `set_up_database`: Sets up the test database before running the test suite by dropping all tables and recreating them to ensure a clean state.
 - `session`: Provides a session for database operations in tests.
 - `clean_db`: Cleans up the database tables before each test by deleting all entries in the `PasswordResetToken` and `User` tables.
-- `client`: Provides a `TestClient` instance with the session fixture, overriding the `get_session` dependency to use the test session.
+- `auth_client`: Provides a `TestClient` instance with access and refresh token cookies set, overriding the `get_session` dependency to use the `session` fixture.
+- `unauth_client`: Provides a `TestClient` instance without authentication cookies set, overriding the `get_session` dependency to use the `session` fixture.
 - `test_user`: Creates a test user in the database with a predefined name, email, and hashed password.
 
 To run the tests, use these commands:

docs/installation.qmd

@@ -20,6 +20,8 @@ If you use VSCode with Docker to develop in a container, the following VSCode De
 
 Simply create a `.devcontainer` folder in the root of the project and add a `devcontainer.json` file in the folder with the above content. VSCode may prompt you to install the Dev Container extension if you haven't already, and/or to open the project in a container. If not, you can manually select "Dev Containers: Reopen in Container" from View > Command Palette.
 
+*IMPORTANT: If using this dev container configuration, you will need to set the `DB_HOST` environment variable to "host.docker.internal" in the `.env` file.*
+
 ## Install development dependencies manually
 
 ### Python and Docker
@@ -103,15 +105,32 @@ Set your desired database name, username, and password in the .env file.
 
 To use password recovery, register a [Resend](https://resend.com/) account, verify a domain, get an API key, and paste the API key into the .env file.
 
+If using the dev container configuration, you will need to set the `DB_HOST` environment variable to "host.docker.internal" in the .env file. Otherwise, set `DB_HOST` to "localhost" for local development. (In production, `DB_HOST` will be set to the hostname of the database server.)
+
 ## Start development database
 
+To start the development database, run the following command in your terminal from the root directory:
+
 ``` bash
 docker compose up -d
 ```
 
+If at any point you change the environment variables in the .env file, you will need to stop the database service *and tear down the volume*:
+
+``` bash
+# Don't forget the -v flag to tear down the volume!
+docker compose down -v
+```
+
+You may also need to restart the terminal session to pick up the new environment variables. You can also add the `--force-recreate` and `--build` flags to the startup command to ensure the container is rebuilt:
+
+``` bash
+docker compose up -d --force-recreate --build
+```
+
 ## Run the development server
 
-Make sure the development database is running and tables and default permissions/roles are created first.
+Before running the development server, make sure the development database is running and tables and default permissions/roles are created first. Then run the following command in your terminal from the root directory:
 
 ``` bash
 uvicorn main:app --host 0.0.0.0 --port 8000 --reload

index.qmd

@@ -107,6 +107,8 @@ To use password recovery, register a [Resend](https://resend.com/) account, veri
 
 ### Start development database
 
+To start the development database, run the following command in your terminal from the root directory:
+
 ``` bash
 docker compose up -d
 ```

main.py

@@ -8,7 +8,7 @@
 from fastapi.exceptions import RequestValidationError, HTTPException, StarletteHTTPException
 from sqlmodel import Session
 from routers import authentication, organization, role, user
-from utils.auth import get_authenticated_user, get_optional_user, NeedsNewTokens, get_user_from_reset_token, PasswordValidationError
+from utils.auth import get_authenticated_user, get_optional_user, NeedsNewTokens, get_user_from_reset_token, PasswordValidationError, AuthenticationError
 from utils.models import User
 from utils.db import get_session, set_up_db
 
@@ -37,6 +37,15 @@ async def lifespan(app: FastAPI):
 # -- Exception Handling Middlewares --
 
 
+# Handle AuthenticationError by redirecting to login page
+@app.exception_handler(AuthenticationError)
+async def authentication_error_handler(request: Request, exc: AuthenticationError):
+    return RedirectResponse(
+        url="/login",
+        status_code=status.HTTP_303_SEE_OTHER
+    )
+
+
 # Handle NeedsNewTokens by setting new tokens and redirecting to same page
 @app.exception_handler(NeedsNewTokens)
 async def needs_new_tokens_handler(request: Request, exc: NeedsNewTokens):
@@ -104,10 +113,6 @@ async def validation_exception_handler(request: Request, exc: RequestValidationE
 # Handle StarletteHTTPException (including 404, 405, etc.) by rendering the error page
 @app.exception_handler(StarletteHTTPException)
 async def http_exception_handler(request: Request, exc: StarletteHTTPException):
-    # Don't handle redirects
-    if exc.status_code in [301, 302, 303, 307, 308]:
-        raise exc
-
     return templates.TemplateResponse(
         request,
         "errors/error.html",

routers/authentication.py

@@ -114,7 +114,6 @@ class UserRead(BaseModel):
     organization_id: Optional[int]
     created_at: datetime
     updated_at: datetime
-    deleted: bool
 
 
 # -- Routes --

routers/organization.py

@@ -27,7 +27,6 @@ class OrganizationRead(BaseModel):
     name: str
     created_at: datetime
     updated_at: datetime
-    deleted: bool
 
 
 class OrganizationUpdate(BaseModel):
@@ -113,9 +112,7 @@ def delete_organization(
     if not db_org:
         raise HTTPException(status_code=404, detail="Organization not found")
 
-    db_org.deleted = True
-    db_org.updated_at = datetime.utcnow()
-    session.add(db_org)
+    session.delete(db_org)
     session.commit()
 
     return RedirectResponse(url="/organizations", status_code=303)

routers/role.py

@@ -31,7 +31,6 @@ class RoleRead(BaseModel):
     name: str
     created_at: datetime
     updated_at: datetime
-    deleted: bool
     permissions: List[ValidPermissions]
 
 
@@ -74,7 +73,7 @@ def create_role(
 @router.get("/{role_id}", response_model=RoleRead)
 def read_role(role_id: int, session: Session = Depends(get_session)):
     db_role: Role | None = session.get(Role, role_id)
-    if not db_role or not db_role.id or db_role.deleted:
+    if not db_role or not db_role.id:
         raise HTTPException(status_code=404, detail="Role not found")
 
     permissions = [
@@ -88,7 +87,6 @@ def read_role(role_id: int, session: Session = Depends(get_session)):
         name=db_role.name,
         created_at=db_role.created_at,
         updated_at=db_role.updated_at,
-        deleted=db_role.deleted,
         permissions=permissions
     )
 
@@ -99,7 +97,7 @@ def update_role(
     session: Session = Depends(get_session)
 ) -> RedirectResponse:
     db_role: Role | None = session.get(Role, role.id)
-    if not db_role or not db_role.id or db_role.deleted:
+    if not db_role or not db_role.id:
         raise HTTPException(status_code=404, detail="Role not found")
     role_data = role.model_dump(exclude_unset=True)
     for key, value in role_data.items():
@@ -131,8 +129,6 @@ def delete_role(
     db_role = session.get(Role, role_id)
     if not db_role:
         raise HTTPException(status_code=404, detail="Role not found")
-    db_role.deleted = True
-    db_role.updated_at = utc_time()
-    session.add(db_role)
+    session.delete(db_role)
     session.commit()
     return RedirectResponse(url="/roles", status_code=303)

routers/user.py

@@ -11,7 +11,8 @@
 # -- Server Request and Response Models --
 
 
-class UserProfile(BaseModel):
+class UpdateProfile(BaseModel):
+    """Request model for updating user profile information"""
     name: str
     email: EmailStr
     avatar_url: str
@@ -40,41 +41,40 @@ async def as_form(
 # -- Routes --
 
 
-@router.get("/profile", response_class=RedirectResponse)
-async def view_profile(
-    current_user: User = Depends(get_authenticated_user)
-):
-    # Render the profile page with the current user's data
-    return {"user": current_user}
-
-
-@router.post("/edit_profile", response_class=RedirectResponse)
-async def edit_profile(
-    name: str = Form(...),
-    email: str = Form(...),
-    avatar_url: str = Form(...),
+@router.post("/update_profile", response_class=RedirectResponse)
+async def update_profile(
+    user_profile: UpdateProfile = Depends(UpdateProfile.as_form),
     current_user: User = Depends(get_authenticated_user),
     session: Session = Depends(get_session)
 ):
     # Update user details
-    current_user.name = name
-    current_user.email = email
-    current_user.avatar_url = avatar_url
+    current_user.name = user_profile.name
+    current_user.email = user_profile.email
+    current_user.avatar_url = user_profile.avatar_url
     session.commit()
     session.refresh(current_user)
     return RedirectResponse(url="/profile", status_code=303)
 
 
 @router.post("/delete_account", response_class=RedirectResponse)
 async def delete_account(
-    confirm_delete_password: str = Form(...),
+    user_delete_account: UserDeleteAccount = Depends(
+        UserDeleteAccount.as_form),
     current_user: User = Depends(get_authenticated_user),
     session: Session = Depends(get_session)
 ):
-    if not verify_password(confirm_delete_password, current_user.hashed_password):
-        raise HTTPException(status_code=400, detail="Password is incorrect")
+    if not verify_password(
+        user_delete_account.confirm_delete_password,
+        current_user.hashed_password
+    ):
+        raise HTTPException(
+            status_code=400,
+            detail="Password is incorrect"
+        )
 
-    # Mark the user as deleted
-    current_user.deleted = True
+    # Delete the user
+    session.delete(current_user)
     session.commit()
-    return RedirectResponse(url="/", status_code=303)
+
+    # Log out the user
+    return RedirectResponse(url="/auth/logout", status_code=303)

templates/authentication/register.html

@@ -25,7 +25,7 @@
         <div class="mb-3">
             <label for="password" class="form-label">Password</label>
             <input type="password" class="form-control" id="password" name="password" 
-                   pattern="(?=.*\d)(?=.*[a-z])(?=.*[A-Z])(?=.*[@$!%*?&\{\}\<\>\.\,\\\\'#\-_=\+\(\)\[\]:;\|~])[A-Za-z\d@$!%*?&\{\}\<\>\.\,\\\\'#\-_=\+\(\)\[\]:;\|~]{8,}"
+                   pattern="(?=.*\d)(?=.*[a-z])(?=.*[A-Z])(?=.*[@$!%*?&\{\}\<\>\.\,\\\\'#\-_=\+\(\)\[\]:;\|~\/])[A-Za-z\d@$!%*?&\{\}\<\>\.\,\\\\'#\-_=\+\(\)\[\]:;\|~\/]{8,}"
                    title="Must contain at least one number, one uppercase and lowercase letter, one special character, and at least 8 or more characters" 
                    placeholder="Enter your password" required
                    autocomplete="new-password">