Merge branch 'main' into 46-document-how-to-do-frontend-bootstrap-styling-in-customization-docs

Author: chriscarrollsmith

.github/workflows/test.yml

@@ -12,7 +12,6 @@ jobs:
       fail-fast: false
       matrix:
         python-version: ["3.12"]
-        poetry-version: [latest]
         os: [ubuntu-latest]
 
     runs-on: ${{ matrix.os }}
@@ -35,15 +34,16 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - uses: actions/setup-python@v5
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
 
-      - name: Install and configure Poetry
-        uses: snok/install-poetry@v1
-
       - name: Install project
-        run: poetry install
+        run: uv sync --all-extras --dev
 
       - name: Set env variables for pytest
         run: |
@@ -54,6 +54,7 @@ jobs:
           echo "DB_NAME=test_db" >> $GITHUB_ENV
           echo "SECRET_KEY=$(openssl rand -base64 32)" >> $GITHUB_ENV
           echo "BASE_URL=http://localhost:8000" >> $GITHUB_ENV
+          echo "RESEND_API_KEY=resend_api_key" >> $GITHUB_ENV
         
       - name: Verify environment variables
         run: |
@@ -63,10 +64,11 @@ jobs:
           [ -n "$DB_HOST" ] && \
           [ -n "$DB_PORT" ] && \
           [ -n "$DB_NAME" ] && \
-          [ -n "$SECRET_KEY" ]
+          [ -n "$SECRET_KEY" ] && \
+          [ -n "$RESEND_API_KEY" ]
 
       - name: Run type checking with mypy
-        run: poetry run mypy .
+        run: uv run mypy .
 
       - name: Run tests with pytest
-        run: poetry run pytest -s tests/
+        run: uv run pytest tests/

.gitignore

@@ -9,4 +9,5 @@ _docs/
 node_modules
 package-lock.json
 package.json
-.specstory
+.specstory
+.cursorrules

README.md

@@ -55,7 +55,7 @@ to deploy to any major cloud hosting platform.
 
 **Additional technologies:**
 
-- [Poetry](https://python-poetry.org/): Python dependency manager
+- [uv](https://docs.astral.sh/uv/): Python dependency manager
 - [Pytest](https://docs.pytest.org/en/7.4.x/): testing framework
 - [Docker](https://www.docker.com/): development containerization
 - [Github Actions](https://docs.github.com/en/actions): CI/CD pipeline
@@ -72,56 +72,73 @@ to deploy to any major cloud hosting platform.
 For comprehensive installation instructions, see the [installation
 page](https://promptlytechnologies.com/fastapi-jinja2-postgres-webapp/docs/installation.html).
 
-### Python and Docker
+### uv
 
-- [Python 3.12 or higher](https://www.python.org/downloads/)
-- [Docker and Docker Compose](https://docs.docker.com/get-docker/)
+MacOS and Linux:
 
-### PostgreSQL headers
+``` bash
+wget -qO- https://astral.sh/uv/install.sh | sh
+```
 
-For Ubuntu/Debian:
+Windows:
 
 ``` bash
-sudo apt update && sudo apt install -y python3-dev libpq-dev
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
 ```
 
-For macOS:
+See the [uv installation
+docs](https://docs.astral.sh/uv/getting-started/installation/) for more
+information.
+
+### Python
+
+Install Python 3.12 or higher from either the official [downloads
+page](https://www.python.org/downloads/) or using uv:
 
 ``` bash
-brew install postgresql
+# Installs the latest version
+uv python install
 ```
 
-For Windows:
+### Docker and Docker Compose
 
-- No installation required
+Install Docker Desktop and Coker Compose for your operating system by
+following the [instructions in the
+documentation](https://docs.docker.com/compose/install/).
 
-### Python dependencies
+### PostgreSQL headers
 
-1.  Install Poetry
+For Ubuntu/Debian:
 
 ``` bash
-pipx install poetry
+sudo apt update && sudo apt install -y python3-dev libpq-dev
 ```
 
-2.  Install project dependencies
+For macOS:
 
 ``` bash
-poetry install
+brew install postgresql
 ```
 
-3.  Activate shell
+For Windows:
+
+- No installation required
+
+### Python dependencies
+
+From the root directory, run:
 
 ``` bash
-poetry shell
+uv venv
+uv sync
 ```
 
-(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.)
+This will create an in-project virtual environment and install all
+dependencies.
 
 ### Set environment variables
 
-Copy .env.example to .env with `cp .env.example .env`.
+Copy `.env.example` to `.env` with `cp .env.example .env`.
 
 Generate a 256 bit secret key with `openssl rand -base64 32` and paste
 it into the .env file.
@@ -134,6 +151,9 @@ account, verify a domain, get an API key, and paste the API key into the
 
 ### Start development database
 
+To start the development database, run the following command in your
+terminal from the root directory:
+
 ``` bash
 docker compose up -d
 ```
@@ -155,14 +175,31 @@ Navigate to http://localhost:8000/
 mypy .
 ```
 
-### Contributing
+## 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:
+[llms.txt](docs/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](docs/static/documentation.txt) for easy
+downloading and embedding for RAG workflows.
+
+## Contributing
 
 Your contributions are welcome! See the [issues
 page](https://github.com/promptly-technologies-llc/fastapi-jinja2-postgres-webapp/issues)
 for ideas. Fork the repository, create a new branch, make your changes,
 and submit a pull request.
 
-### License
+## License
 
 This project is created and maintained by [Promptly Technologies,
 LLC](https://promptlytechnologies.com/) and licensed under the MIT

docs/architecture.qmd

@@ -102,18 +102,16 @@ Here are some patterns we've considered for server-side error handling:
   border-collapse: collapse;
 }
 
-.styled-table th:nth-child(1) { width: 5%; }
-.styled-table th:nth-child(2) { width: 50%; }
-.styled-table th:nth-child(3), 
-.styled-table th:nth-child(4),
-.styled-table th:nth-child(5) { width: 15%; }
-.styled-table th:nth-child(6) { width: 10%; }
+.styled-table th:nth-child(1) { width: 50%; }
+.styled-table th:nth-child(2), 
+.styled-table th:nth-child(3),
+.styled-table th:nth-child(4) { width: 15%; }
+.styled-table th:nth-child(5) { width: 10%; }
 </style>
 
 <table class="styled-table">
   <thead>
     <tr>
-      <th>ID</th>
       <th>Approach</th>
       <th>Returns to same page</th>
       <th>Preserves form inputs</th>
@@ -123,39 +121,34 @@ Here are some patterns we've considered for server-side error handling:
   </thead>
   <tbody>
     <tr>
-      <td>1</td>
       <td>Validate with Pydantic dependency, catch and redirect from middleware (with exception message as context) to an error page with "go back" button</td>
       <td>No</td>
       <td>Yes</td>
       <td>Yes</td>
       <td>Low</td>
     </tr>
     <tr>
-      <td>2</td>
       <td>Validate in FastAPI endpoint function body, redirect to origin page with error message query param</td>
       <td>Yes</td>
       <td>No</td>
       <td>Yes</td>
       <td>Medium</td>
     </tr>
     <tr>
-      <td>3</td>
       <td>Validate in FastAPI endpoint function body, redirect to origin page with error message query param and form inputs as context so we can re-render page with original form inputs</td>
       <td>Yes</td>
       <td>Yes</td>
       <td>Yes</td>
       <td>High</td>
     </tr>
     <tr>
-      <td>4</td>
       <td>Validate with Pydantic dependency, use session context to get form inputs from request, redirect to origin page from middleware with exception message and form inputs as context so we can re-render page with original form inputs</td>
       <td>Yes</td>
       <td>Yes</td>
       <td>Yes</td>
       <td>High</td>
     </tr>
     <tr>
-      <td>5</td>
       <td>Validate in either Pydantic dependency or function endpoint body and directly return error message or error toast HTML partial in JSON, then mount error toast with HTMX or some simple layout-level Javascript</td>
       <td>Yes</td>
       <td>Yes</td>