From fa21519880bffd90e9052b00735794d4bd19ed9a Mon Sep 17 00:00:00 2001 From: Amy V Date: Sat, 5 Sep 2026 11:41:44 -0500 Subject: [PATCH] docs: standardize ClearRoute recruiter evidence path --- README.md | 141 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 90 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index a5bb5ad..d59357e 100644 --- a/README.md +++ b/README.md @@ -1,67 +1,56 @@ # ClearRoute API -> **A focused FastAPI workflow API demonstration with explicit task state, role-aware approval gates, and audit-friendly events.** +> **API design + explicit workflow state with typed validation, transition rules, role boundaries, and audit events.** -[Portfolio walkthrough](https://amy-villa-signal-gallery.vercel.app/projects/clearrout-api) · [Amy Villa on GitHub](https://github.com/Amyvdev1) · [Contact Amy](mailto:amyv.dev@gmail.com) +[Source](https://github.com/Amyvdev1/clearrout-api) · [Amy Villa on GitHub](https://github.com/Amyvdev1) · [Contact](mailto:amyv.dev@gmail.com) -ClearRoute models a small but common systems problem: a task needs a clear owner, an explicit state, an approval requirement, an audit trail, and a predictable next action. The project is intentionally narrow so its API contract and transition rules are easy to inspect. +## What it solves -## What Amy built +ClearRoute models a small but common backend problem: a task needs a clear owner, an explicit state, an approval rule, a predictable next action, and an audit trail that an API consumer can reason about. -| Capability | Implementation | -|---|---| -| **Task contract** | Pydantic request and response models define title, owner, state, approval requirement, timestamps, and audit data. | -| **Explicit workflow state graph** | New tasks begin in `planned`; legal transitions are `planned → in_review → approved → handed_off`, with a documented approval-free `in_review → handed_off` path. Skipped, repeated, and reverse transitions return `409 Conflict`. | -| **Visible role boundary** | An `X-Demo-Role` dependency models `builder` and `reviewer` behavior; approval and handoff require the reviewer role. | -| **Audit events** | Task creation and state changes create timestamped event records connected to the task. | -| **Next action** | A single function turns the current task state into `move_to_review`, `approval_required`, `handoff_ready`, or `complete`. | -| **Executable checks** | The test suite covers initial state, every approval-required transition, skipped/repeated/reverse-state rejection, approval-before-handoff, review authority, and invalid task creation. | -| **Local packaging** | Pinned requirements, Pytest configuration, and a Python 3.12 Dockerfile document a reproducible local run path. | +## Why it exists -## API surface +Workflow APIs become difficult to integrate when state changes are implicit or errors are inconsistent. ClearRoute keeps the state graph deliberately small so the contract is easy to inspect: legal transitions are explicit, role-gated actions are visible, invalid moves fail predictably, and every accepted change creates an audit event. -| Method | Endpoint | What it does | -|---|---|---| -| `GET` | `/health` | Returns a small health response for the portfolio API. | -| `POST` | `/v1/tasks` | Validates and creates a task, then records a creation event. | -| `GET` | `/v1/tasks` | Returns the tasks held by the in-memory demo store. | -| `PATCH` | `/v1/tasks/{task_id}` | Applies a controlled state update, enforcing role and approval rules. | -| `GET` | `/v1/tasks/{task_id}/audit` | Returns audit records associated with a known task. | +## Live demo -## Code map +**Production deployment: pending.** The API is fully inspectable locally through FastAPI's generated `/docs` interface and the automated test suite. No external credentials or services are required. -| File / area | What it explains | -|---|---| -| [`app/main.py`](app/main.py) | FastAPI initialization, models, an explicit allowed-transition graph, demo role dependency, next-action logic, endpoint behavior, and audit-event creation. | -| [`tests/test_main.py`](tests/test_main.py) | Behavioral checks for the API’s creation, permission, legal/illegal transitions, and validation rules. | -| [`requirements.txt`](requirements.txt) | Pinned FastAPI, Uvicorn, pytest, and HTTPX dependencies. | -| [`pyproject.toml`](pyproject.toml) | Pytest import/test-path configuration. | -| [`Dockerfile`](Dockerfile) | A compact Python 3.12 runtime image that starts Uvicorn on port 8000. | -| [`.github/workflows/ci.yml`](.github/workflows/ci.yml) | Runs the focused API regression suite on pushes and pull requests. | -| [`docs/API_CONSUMER_GUIDE.md`](docs/API_CONSUMER_GUIDE.md) | A consumer-oriented walkthrough of requests, controlled transitions, error contracts, audit events, and the explicit identity boundary. | - -For a behavior-level explanation of each source area, read the [technical code tour](docs/CODE_TOUR.md). - -## Run locally +## Architecture -```bash -python -m venv .venv -source .venv/bin/activate # Windows: .venv\Scripts\activate -pip install -r requirements.txt -uvicorn app.main:app --reload +```text +API consumer / FastAPI docs + │ + ▼ +FastAPI route layer + ├── Pydantic request validation + ├── demo role dependency + ├── task-state transition rules + └── predictable HTTP error contracts + │ + ▼ +In-memory demo store + ├── tasks + └── audit events ``` -Open [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) to inspect FastAPI’s generated API documentation. +### Stack -## Run tests +**Python · FastAPI · Pydantic · REST · pytest · HTTPX · Docker · GitHub Actions** -```bash -pytest -q -``` +## Key engineering decisions -The focused regression suite covers the transition contract and validation behavior described above. The [GitHub Actions workflow](https://github.com/Amyvdev1/clearrout-api/actions) runs the same API checks on pushes and pull requests. These checks protect the stated behaviors; they do not claim production completeness. +| Decision | Why it is here | +|---|---| +| **Explicit transition graph** | Makes legal and illegal state changes visible instead of scattering transition logic across endpoints. | +| **Typed Pydantic contracts** | Gives API consumers predictable request/response validation behavior. | +| **`409 Conflict` for invalid transitions** | Distinguishes a valid request shape from a request that conflicts with current resource state. | +| **Visible demo role boundary** | Demonstrates role-sensitive behavior without pretending a request header is production authentication. | +| **Audit event creation** | Preserves a reviewable record of task creation and accepted state changes. | +| **Single next-action function** | Converts backend state into a simple consumer-facing next step. | +| **In-memory persistence boundary** | Keeps the sample focused on API/state semantics and explicitly avoids claiming durable production storage. | -### State-transition contract +## State-transition contract | Current state | Allowed next state | Role / rule | |---|---|---| @@ -71,12 +60,62 @@ The focused regression suite covers the transition contract and validation behav | `approved` | `handed_off` | Reviewer demo role required. | | `handed_off` | None | Terminal demo state. | -The `X-Demo-Role` request header is a visible teaching boundary, not authentication. The graph demonstrates workflow invariants; it is not a substitute for a production identity system, durable audit controls, or real authorization. +## Failure behavior + +The API is designed so integration failures are distinguishable: + +- invalid request data → `422 Unprocessable Entity`, +- missing task → `404 Not Found`, +- insufficient demo role → `403 Forbidden`, +- skipped/repeated/reverse transition → `409 Conflict`, +- handoff before required approval → `409 Conflict`. + +The `X-Demo-Role` header is a teaching boundary, **not authentication**. It exists to make role-dependent behavior easy to inspect and test. + +## API surface + +| Method | Endpoint | What it does | +|---|---|---| +| `GET` | `/health` | Returns a small health response. | +| `POST` | `/v1/tasks` | Validates and creates a task, then records a creation event. | +| `GET` | `/v1/tasks` | Returns tasks held by the demo store. | +| `PATCH` | `/v1/tasks/{task_id}` | Applies a controlled state update, enforcing role and approval rules. | +| `GET` | `/v1/tasks/{task_id}/audit` | Returns audit records associated with a known task. | + +## Testing & CI + +```bash +pytest -q +``` + +The regression suite covers initial state, legal transitions, skipped/repeated/reverse-state rejection, approval-before-handoff, reviewer authority, missing resources, and invalid task creation. GitHub Actions runs the focused API suite on pushes and pull requests. + +## Security / evidence boundaries -## Intentional boundaries +ClearRoute is a **self-directed API engineering sample**, not production software. It uses module-level in-memory storage and a request-header demonstration role rather than a database, real authentication, identity-provider integration, durable audit controls, customer data, external execution, monitoring, or production deployment infrastructure. + +The scope is intentionally narrow so the API contract and workflow invariants remain easy to review. + +## 5-minute code review path + +1. [`app/main.py`](app/main.py) — Pydantic models, transition graph, role dependency, next-action logic, endpoints, and audit events. +2. [`tests/test_main.py`](tests/test_main.py) — legal/illegal transitions, permissions, validation, and failure contracts. +3. [`docs/API_CONSUMER_GUIDE.md`](docs/API_CONSUMER_GUIDE.md) — consumer-oriented request/response examples and integration boundaries. +4. [`docs/CODE_TOUR.md`](docs/CODE_TOUR.md) — behavior-level source walkthrough. +5. [`.github/workflows/ci.yml`](.github/workflows/ci.yml) — automated regression path. +6. [`Dockerfile`](Dockerfile) — compact Python 3.12 runtime packaging. + +## Run locally + +```bash +python -m venv .venv +source .venv/bin/activate # Windows: .venv\Scripts\activate +pip install -r requirements.txt +uvicorn app.main:app --reload +``` -ClearRoute is a **self-directed code sample**, not production software. It uses module-level in-memory storage and a request-header demonstration role rather than a database, real authentication, identity-provider integration, customer data, external execution, monitoring, or deployment infrastructure. The explicit scope makes the transition logic and API design easy to inspect. +Open `http://127.0.0.1:8000/docs` to inspect the generated API documentation. --- -Created by **Amy Villa** as a focused backend/API portfolio project. +Built by **Amy Villa** as an inspectable API Design & Workflow State engineering sample.