Skip to content

docs: position ClearRoute as API workflow-state evidence #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Amyvdev1 merged 1 commit into from
Sep 5, 2026
Merged

docs: position ClearRoute as API workflow-state evidence #1

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
141 changes: 90 additions & 51 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 |
|---|---|---|
Expand All @@ -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.
Loading