Documented VSCode configuration

Author: chriscarrollsmith

docs/customization.qmd

@@ -15,6 +15,8 @@ The project uses Poetry to manage dependencies:
 - Install dependencies: `poetry install`
 - Update all dependencies: `poetry update`
 
+If you are using VSCode or Cursor as your IDE, you will need to select the Poetry-managed Python version as your interpreter for the project. To find the location of the Poetry-managed Python interpreter, run `poetry env info` and look for the `Path` field. Then, in VSCode, go to `View > Command Palette`, search for `Python: Select Interpreter`, and either select Poetry's Python version from the list (if it has been auto-detected) or "Enter interpreter path" manually.
+
 ### Testing
 
 The project uses Pytest for unit testing. It's highly recommended to write and run tests before committing code to ensure nothing is broken!
@@ -96,7 +98,7 @@ We name our GET routes using the convention `read_<name>`, where `<name>` is the
 We divide our GET routes into authenticated and unauthenticated routes, using commented section headers in our code that look like this:
 
 ```python
-# -- Authenticated Routes --
+# --- Authenticated Routes ---
 ```
 
 Some of our routes take request parameters, which we pass as keyword arguments to the route handler. These parameters should be type annotated for validation purposes.
@@ -243,11 +245,16 @@ SQLModel is an Object-Relational Mapping (ORM) library that allows us to interac
 Our database models are defined in `utils/models.py`. Each model is a Python class that inherits from `SQLModel` and represents a database table. The key models are:
 
 - `Organization`: Represents a company or team
-- `User`: Represents a user account
-- `Role`: Represents a discrete set of user permissions within an organization
-- `Permission`: Represents specific actions a user can perform
-- `RolePermissionLink`: Maps roles to their allowed permissions
-- `PasswordResetToken`: Manages password reset functionality
+- `User`: Represents a user account with name, email, and avatar
+- `Role`: Represents a set of permissions within an organization
+- `Permission`: Represents specific actions a user can perform (defined by ValidPermissions enum)
+- `PasswordResetToken`: Manages password reset functionality with expiration
+- `UserPassword`: Stores hashed user passwords separately from user data
+
+Two additional models are used by SQLModel to manage many-to-many relationships; you generally will not need to interact with them directly:
+
+- `UserRoleLink`: Maps users to their roles (many-to-many relationship)
+- `RolePermissionLink`: Maps roles to their permissions (many-to-many relationship)
 
 Here's an entity-relationship diagram (ERD) of the current database schema, automatically generated from our SQLModel definitions:
 
@@ -297,6 +304,17 @@ async def get_users(session: Session = Depends(get_session)):
 
 The session automatically handles transaction management, ensuring that database operations are atomic and consistent.
 
+There is also a helper method on the `User` model that checks if a user has a specific permission for a given organization. Its first argument must be a `ValidPermissions` enum value (from `utils/models.py`), and its second argument must be an `Organization` object or an `int` representing an organization ID:
+
+```python
+permission = ValidPermissions.CREATE_ROLE
+organization = session.exec(select(Organization).where(Organization.name == "Acme Inc.")).first()
+
+user.has_permission(permission, organization)
+```
+
+You should create custom `ValidPermissions` enum values for your application and validate that users have the necessary permissions before allowing them to modify organization data resources.
+
 #### Cascade deletes
 
 Cascade deletes (in which deleting a record from one table deletes related records from another table) can be handled at either the ORM level or the database level. This template handles cascade deletes at the ORM level, via SQLModel relationships. Inside a SQLModel `Relationship`, we set:

docs/installation.qmd

@@ -18,7 +18,7 @@ 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.
+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.*
 
@@ -69,6 +69,12 @@ poetry shell
 
 (Note: You will need to activate the shell every time you open a new terminal session. Alternatively, you can use the `poetry run` prefix before other commands to run them without activating the shell.)
 
+### Configure IDE
+
+If you are using VSCode or Cursor as your IDE, you will need to select the Poetry-managed Python version as your interpreter for the project. To find the location of the Poetry-managed Python interpreter, run `poetry env info` and look for the `Path` field. Then, in VSCode, go to `View > Command Palette`, search for `Python: Select Interpreter`, and either select Poetry's Python version from the list (if it has been auto-detected) or "Enter interpreter path" manually.
+
+It is also recommended to install the [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) and [Quarto](https://marketplace.visualstudio.com/items?itemName=quarto.quarto) IDE extensions.
+
 ## Install documentation dependencies manually
 
 ### Quarto CLI

docs/static/documentation.txt

@@ -192,9 +192,11 @@ with open(output_path, 'w', encoding='utf-8') as f:
     f.write(final_content)
 ```
 
-In line with the [llms.txt standard](https://llmstxt.org/), we have provided a Markdown-formatted prompt—designed to help LLM agents understand how to work with this template—as a [text file](docs/static/llms.txt). One use case for this file is to rename it to `.cursorrules` and place it in your project directory is using the Cursor IDE (see the [Cursor docs](https://docs.cursor.com/context/rules-for-ai) on this for more information).
+In line with the [llms.txt standard](https://llmstxt.org/), we have provided a Markdown-formatted prompt—designed to help LLM agents understand how to work with this template—as a text file: [llms.txt](docs/static/llms.txt).
 
-We have also exposed the full Markdown-formatted project documentation as a [single text file](docs/static/documentation.txt) for easy downloading and embedding.
+One use case for this file, if using the Cursor IDE, is to rename it to `.cursorrules` and place it in your project directory (see the [Cursor docs](https://docs.cursor.com/context/rules-for-ai) on this for more information). Alternatively, you could use it as a custom system prompt in the web interface for ChatGPT, Claude, or the LLM of your choice.
+
+We have also exposed the full Markdown-formatted project documentation as a [single text file](docs/static/documentation.txt) for easy downloading and embedding for RAG workflows.
 
 ## Contributing
 
@@ -517,7 +519,7 @@ 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.
+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.*
 
@@ -568,6 +570,12 @@ poetry shell
 
 (Note: You will need to activate the shell every time you open a new terminal session. Alternatively, you can use the `poetry run` prefix before other commands to run them without activating the shell.)
 
+### Configure IDE
+
+If you are using VSCode or Cursor as your IDE, you will need to select the Poetry-managed Python version as your interpreter for the project. To find the location of the Poetry-managed Python interpreter, run `poetry env info` and look for the `Path` field. Then, in VSCode, go to `View > Command Palette`, search for `Python: Select Interpreter`, and either select Poetry's Python version from the list (if it has been auto-detected) or "Enter interpreter path" manually.
+
+It is also recommended to install the [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) and [Quarto](https://marketplace.visualstudio.com/items?itemName=quarto.quarto) IDE extensions.
+
 ## Install documentation dependencies manually
 
 ### Quarto CLI
@@ -659,6 +667,8 @@ The project uses Poetry to manage dependencies:
 - Install dependencies: `poetry install`
 - Update all dependencies: `poetry update`
 
+If you are using VSCode or Cursor as your IDE, you will need to select the Poetry-managed Python version as your interpreter for the project. To find the location of the Poetry-managed Python interpreter, run `poetry env info` and look for the `Path` field. Then, in VSCode, go to `View > Command Palette`, search for `Python: Select Interpreter`, and either select Poetry's Python version from the list (if it has been auto-detected) or "Enter interpreter path" manually.
+
 ### Testing
 
 The project uses Pytest for unit testing. It's highly recommended to write and run tests before committing code to ensure nothing is broken!
@@ -692,9 +702,11 @@ We find that mypy is an enormous time-saver, catching many errors early and grea
 
 ### Developing with LLMs
 
-In line with the [llms.txt standard](https://llmstxt.org/), we have provided a Markdown-formatted prompt—designed to help LLM agents understand how to work with this template—as a [text file](static/llms.txt). One use case for this file is to rename it to `.cursorrules` and place it in your project directory is using the Cursor IDE (see the [Cursor docs](https://docs.cursor.com/context/rules-for-ai) on this for more information).
+In line with the [llms.txt standard](https://llmstxt.org/), we have provided a Markdown-formatted prompt—designed to help LLM agents understand how to work with this template—as a text file: [llms.txt](static/llms.txt).
+
+One use case for this file, if using the Cursor IDE, is to rename it to `.cursorrules` and place it in your project directory (see the [Cursor docs](https://docs.cursor.com/context/rules-for-ai) on this for more information). Alternatively, you could use it as a custom system prompt in the web interface for ChatGPT, Claude, or the LLM of your choice.
 
-We have also exposed the full Markdown-formatted project documentation as a [single text file](static/documentation.txt) for easy downloading and embedding.
+We have also exposed the full Markdown-formatted project documentation as a [single text file](static/documentation.txt) for easy downloading and embedding for RAG workflows.
 
 ## Project structure
 
@@ -738,7 +750,7 @@ We name our GET routes using the convention `read_<name>`, where `<name>` is the
 We divide our GET routes into authenticated and unauthenticated routes, using commented section headers in our code that look like this:
 
 ```python
-# -- Authenticated Routes --
+# --- Authenticated Routes ---
 ```
 
 Some of our routes take request parameters, which we pass as keyword arguments to the route handler. These parameters should be type annotated for validation purposes.
@@ -885,11 +897,16 @@ SQLModel is an Object-Relational Mapping (ORM) library that allows us to interac
 Our database models are defined in `utils/models.py`. Each model is a Python class that inherits from `SQLModel` and represents a database table. The key models are:
 
 - `Organization`: Represents a company or team
-- `User`: Represents a user account
-- `Role`: Represents a discrete set of user permissions within an organization
-- `Permission`: Represents specific actions a user can perform
-- `RolePermissionLink`: Maps roles to their allowed permissions
-- `PasswordResetToken`: Manages password reset functionality
+- `User`: Represents a user account with name, email, and avatar
+- `Role`: Represents a set of permissions within an organization
+- `Permission`: Represents specific actions a user can perform (defined by ValidPermissions enum)
+- `PasswordResetToken`: Manages password reset functionality with expiration
+- `UserPassword`: Stores hashed user passwords separately from user data
+
+Two additional models are used by SQLModel to manage many-to-many relationships; you generally will not need to interact with them directly:
+
+- `UserRoleLink`: Maps users to their roles (many-to-many relationship)
+- `RolePermissionLink`: Maps roles to their permissions (many-to-many relationship)
 
 Here's an entity-relationship diagram (ERD) of the current database schema, automatically generated from our SQLModel definitions:
 
@@ -939,6 +956,17 @@ async def get_users(session: Session = Depends(get_session)):
 
 The session automatically handles transaction management, ensuring that database operations are atomic and consistent.
 
+There is also a helper method on the `User` model that checks if a user has a specific permission for a given organization. Its first argument must be a `ValidPermissions` enum value (from `utils/models.py`), and its second argument must be an `Organization` object or an `int` representing an organization ID:
+
+```python
+permission = ValidPermissions.CREATE_ROLE
+organization = session.exec(select(Organization).where(Organization.name == "Acme Inc.")).first()
+
+user.has_permission(permission, organization)
+```
+
+You should create custom `ValidPermissions` enum values for your application and validate that users have the necessary permissions before allowing them to modify organization data resources.
+
 #### Cascade deletes
 
 Cascade deletes (in which deleting a record from one table deletes related records from another table) can be handled at either the ORM level or the database level. This template handles cascade deletes at the ORM level, via SQLModel relationships. Inside a SQLModel `Relationship`, we set: