Structured repository context for dummy-backend

gistfile1.txt

# Dummy Backend Repository Context

## Purpose

`dummy-backend` is a small FastAPI service that exposes CRUD and workflow endpoints for todo list items. It is intended as a simple backend API backed by SQLite, with SQLModel used for both ORM mapping and response/request schema support.

## Technology Stack

- Language: Python 3.10+
- Web framework: FastAPI
- Database/ORM: SQLite via SQLModel and SQLAlchemy
- Validation/schema layer: SQLModel/Pydantic-style models
- Test stack: pytest, FastAPI TestClient, httpx
- Project metadata: `pyproject.toml`
- FastAPI entrypoint: `app.main:app`

## Repository Layout

- `app/main.py`
  - Creates the FastAPI application.
  - Registers the application lifespan hook.
  - Creates database tables on startup.
  - Includes the todo list router.
  - Provides a root health-style endpoint at `GET /`.

- `app/db.py`
  - Defines database configuration and session wiring.
  - Uses `DATABASE_URL` from the environment when present.
  - Defaults to `sqlite:///./data/todos.db`.
  - Ensures the SQLite database directory exists for file-backed SQLite URLs.
  - Exposes `create_db_and_tables()` and `get_session()`.

- `app/models.py`
  - Defines the persistent SQLModel table model.
  - `TodoList` has:
    - `id`
    - `title`
    - `description`
    - `is_completed`
    - `created_at`
    - `updated_at`
  - Timestamps are timezone-aware UTC datetimes generated by `utc_now()`.

- `app/schemas.py`
  - Defines request and response schemas.
  - Create schema: `TodoListCreate`
  - Partial update schema: `TodoListUpdate`
  - Full replacement schema: `TodoListReplace`
  - Read schema: `TodoListRead`
  - List response metadata: `TodoListListMeta`
  - Echoed filter metadata: `TodoListListFilters`
  - Paginated list response: `TodoListListResponse`
  - Aggregate summary response: `TodoListSummary`

- `app/routers/todo_lists.py`
  - Contains all `/todo-lists` API routes.
  - Implements CRUD, filtering, ordering, pagination, summary aggregation, recent items, and completion lifecycle operations.

- `tests/test_todo_lists.py`
  - Contains API-level tests using FastAPI `TestClient`.
  - Overrides the app database dependency with an in-memory SQLite database per test fixture.
  - Verifies create, list, search, filter, order, summary, read, patch, replace, lifecycle, delete, not-found, and validation behavior.

## API Surface

- `GET /`
  - Returns `{"message": "Todo List API is running"}`.

- `POST /todo-lists`
  - Creates a todo list item.
  - Request body: `title`, optional `description`, optional `is_completed`.
  - Returns `201 Created`, a `TodoListRead` payload, and a `Location` header pointing to the created resource.

- `GET /todo-lists`
  - Returns a paginated list response.
  - Query parameters:
    - `offset`: integer offset, default `0`
    - `limit`: integer page size, default `100`, valid range `1..100`
    - `q`: optional search term matched against title and description
    - `title_prefix`: optional case-insensitive title prefix filter
    - `is_completed`: optional boolean completion filter
    - `order_by`: one of `created_at_desc`, `created_at_asc`, `title_asc`, `title_desc`, `updated_at_desc`, `updated_at_asc`
  - Response includes `items`, `pagination`, and `filters`.

- `GET /todo-lists/summary`
  - Returns aggregate counts:
    - `total`
    - `completed`
    - `pending`

- `GET /todo-lists/recent`
  - Returns the most recently created todo list items.
  - Query parameter:
    - `limit`: default `5`, valid range `1..20`

- `GET /todo-lists/{todo_list_id}`
  - Returns one todo list item.
  - Returns `404` with `{"detail": "Todo list not found"}` when missing.

- `PUT /todo-lists/{todo_list_id}`
  - Fully replaces mutable todo list fields.
  - Uses `TodoListReplace`.
  - Updates `updated_at`.

- `PATCH /todo-lists/{todo_list_id}`
  - Partially updates mutable todo list fields.
  - Uses `TodoListUpdate` with `exclude_unset=True`.
  - Accepts a `notify` query parameter but currently ignores it.
  - Updates `updated_at`.
  - Route declares `202 Accepted`, but current tests expect `200 OK`; this is a behavioral inconsistency worth preserving or resolving deliberately.

- `POST /todo-lists/{todo_list_id}/complete`
  - Marks an item complete.
  - Updates `updated_at`.

- `POST /todo-lists/{todo_list_id}/reopen`
  - Marks an item incomplete.
  - Updates `updated_at`.

- `DELETE /todo-lists/{todo_list_id}`
  - Deletes an item.
  - Returns `204 No Content`.

## Data Model Semantics

Todo list items are simple task records. `title` is required and indexed. `description` is optional. `is_completed` represents lifecycle state. `created_at` is set when the SQLModel object is created, and `updated_at` is refreshed manually by `_save_and_refresh()` for update, replacement, complete, and reopen operations.

## Database Behavior

The production/default database URL is `sqlite:///./data/todos.db`. The app creates required tables during FastAPI startup through the lifespan hook. The session dependency yields a SQLModel `Session` bound to a module-level engine. Tests override this dependency with an in-memory SQLite engine using `StaticPool`.

## Error Handling

Missing todo list resources raise `HTTPException` with status `404` and detail `"Todo list not found"`. Request validation errors are handled by FastAPI/Pydantic and return `422`.

## Test Coverage Summary

The tests cover:

- Successful creation and `Location` header behavior.
- Paginated list response shape.
- Filtering by completion state.
- Ordering by title descending.
- Search by query text.
- Summary aggregate counts.
- Reading one item.
- Partial update behavior.
- Full replacement behavior.
- Complete and reopen lifecycle endpoints.
- Delete behavior and empty `204` body.
- Consistent `404` behavior for missing resources.
- Validation failure when `title` is omitted.

## Important Implementation Notes For Embedding/Retrieval

- The central business behavior lives in `app/routers/todo_lists.py`.
- The persistent shape of todo records lives in `app/models.py`.
- API contracts are split into explicit schema classes in `app/schemas.py`.
- Database lifecycle and dependency injection are in `app/db.py`.
- Tests are valuable related context because they document expected external API behavior.
- `README.md` is short but accurately describes the service as FastAPI APIs for todo lists with SQLite storage and richer workflow/list features.

## Potential Follow-Up Areas

- Decide whether `PATCH /todo-lists/{todo_list_id}` should return `200 OK` or `202 Accepted`; the route decorator and current tests disagree.
- Add explicit validation constraints to request schemas if create/update/replace payloads should enforce the same title and description limits as the table model.
- Add tests for `title_prefix`, `recent`, and `updated_at` ordering if those behaviors are important API contracts.
- Consider migrations if the service grows beyond a simple SQLite-backed demo.