docs(readme): tighten mvp delivery copy

Clarify the README opening, add workflow diagrams, and make the public docs read less like an internal status report.

Keep the checked-in run summary aligned with the report writer template.

Tested:

- uv run ruff check .

- uv run ruff format --check .

- uv run basedpyright

- uv run pytest -v

- uv run pytest --cov=clean_data_export_api --cov-report=term-missing --cov-fail-under=90

- uv run python -m compileall src tests

- git diff --check

Author: jaeyeopme

README.md

@@ -1,19 +1,11 @@
 # Clean Data Export API
 
-Clean Data Export API is a local workflow for turning imperfect job records into
-review-ready CSV and JSON exports, with duplicate handling, rejected rows, run
-history, and handoff notes.
+Clean Data Export API turns incomplete FieldOps Desk job exports into files a
+team can review: clean CSV, matching JSON, rejected rows, run history, and a
+short run summary.
 
-The workflow is intentionally local and uses fictional data. It models an
-operations tool called **FieldOps Desk** and focuses on exporting `jobs` and
-related `job_updates` records. It does not connect to a real customer system or
-use real credentials.
-
-## Current Status
-
-The first local MVP is implemented. The repository includes deterministic
-FieldOps Desk fixture data, a reusable export service, FastAPI and CLI entry
-points, clean CSV/JSON outputs, rejected rows, SQLite run history, and tests.
+The project is local by design. It uses fictional data, reads only `jobs` and
+`job_updates`, and never connects to a real customer system.
 
 The demo export for `2026-06-01` through `2026-06-05` returns:
 
@@ -24,44 +16,45 @@ duplicate_count=1
 rejected_count=6
 ```
 
-## What the workflow delivers
+## What it does
 
-This is not a broad backend platform. The workflow focuses on one handoff-ready
-export package:
+This is one export workflow, not a broad backend platform. It:
 
-- pull a limited set of source records.
-- map source fields into a buyer-friendly output shape.
-- keep invalid records out of clean exports without hiding them.
-- remove duplicate records deterministically.
-- write output files that can be reviewed in a spreadsheet or handed to another
+- pulls a limited set of source records.
+- maps source fields into clean output columns.
+- keeps invalid records out of the clean export without hiding them.
+- removes later duplicate records for the same `job_id`.
+- writes files that can be reviewed in a spreadsheet or handed to another
   system.
-- record enough run history to explain what happened.
+- records run history in SQLite.
 
 ## Scenario
 
-A fictional operations team uses FieldOps Desk to manage field jobs. Their
-built-in export is limited, and manual spreadsheet updates have created missing
-fields and duplicate records.
+FieldOps Desk is a fictional operations tool for field jobs. Its export is
+limited, and manual spreadsheet edits have left missing fields and duplicate
+rows.
 
-They need a repeatable local workflow that produces:
+The local workflow produces:
 
 - a clean job export for review.
-- a JSON copy for technical handoff.
-- a rejected-row file explaining records that were not accepted.
+- a JSON copy with the same accepted records.
+- a rejected-row file that explains what failed.
 - a short run summary with counts and file paths.
 
 ## Workflow
 
-```text
-source fixture
-  -> paginated job fetch
-  -> related job update fetch
-  -> field mapping
-  -> validation
-  -> duplicate handling
-  -> output files
-  -> SQLite run history
-  -> API/CLI response
+```mermaid
+flowchart LR
+  source["FieldOps Desk fixture"]
+  fetch["Fetch jobs and updates"]
+  map["Map fields"]
+  validate["Validate rows"]
+  dedupe["Remove later duplicates"]
+  write["Write CSV, JSON, and rejected rows"]
+  history["Store run history"]
+  response["Return API or CLI summary"]
+
+  source --> fetch --> map --> validate --> dedupe --> write --> history --> response
 ```
 
 The FastAPI endpoint and CLI use the same export service, so both entry points
@@ -77,12 +70,12 @@ outputs/
   run_summary.md
 ```
 
-`clean_jobs.csv` is the main spreadsheet-ready export. `clean_jobs.json` carries
-the same accepted records in JSON form. `rejected_jobs.csv` keeps invalid or
-duplicate records visible with reason codes. `run_summary.md` gives a
-human-readable handoff summary.
+`clean_jobs.csv` is the spreadsheet export. `clean_jobs.json` contains the same
+accepted records in JSON form. `rejected_jobs.csv` keeps invalid and duplicate
+records visible with reason codes. `run_summary.md` records the run counts and
+file paths.
 
-## Project Structure
+## Project structure
 
 ```text
 clean-data-export-api/
@@ -116,7 +109,7 @@ clean-data-export-api/
   tests/
 ```
 
-## Usage
+## Run it
 
 Run the CLI export:
 
@@ -154,9 +147,8 @@ local runs.
 
 ## Safety and limits
 
-This project does not use real third-party credentials, scraping, login bypass,
-paid APIs, or real customer data. All sample data should be fictional and safe
-to share.
+This project does not use real credentials, scraping, login bypass, paid APIs,
+or customer data. All sample data is fictional.
 
 This project should not claim readiness for live operations, guaranteed business
 outcomes, advanced security guarantees, or support for a real vendor API before

docs/ARCHITECTURE.md

@@ -2,21 +2,31 @@
 
 ## Purpose
 
-This document describes the technical design for Clean Data Export API. The
-design keeps the workflow small, local, deterministic, and reusable from both
-FastAPI and the CLI.
+This document describes how Clean Data Export API is wired. The design keeps the
+workflow local, deterministic, and shared by both FastAPI and the CLI.
 
 ## System overview
 
-```text
-FastAPI / CLI
-  -> export service
-  -> source fixture API
-  -> mapping
-  -> validation
-  -> duplicate handling
-  -> report writers
-  -> SQLite run repository
+```mermaid
+flowchart LR
+  entry["FastAPI / CLI"]
+  service["export_service.py"]
+  source["source_api.py"]
+  mapping["mapping.py"]
+  validation["validation.py"]
+  reports["reports.py"]
+  repository["repository.py"]
+  outputs["CSV / JSON / summary"]
+  sqlite["SQLite run history"]
+
+  entry --> service
+  service --> source
+  service --> mapping
+  service --> validation
+  service --> reports
+  service --> repository
+  reports --> outputs
+  repository --> sqlite
 ```
 
 The export service is the core boundary. API and CLI code should only parse
@@ -31,7 +41,7 @@ inputs, call the service, and return the summary.
 - Keep output files easy to inspect in a spreadsheet.
 - Avoid abstractions that are not needed for the first export type.
 
-## Package Layout
+## Package layout
 
 ```text
 src/clean_data_export_api/
@@ -88,7 +98,7 @@ Expected settings:
 
 ### `models.py`
 
-Defines typed data models for the workflow.
+Defines typed data models.
 
 Models include:
 
@@ -104,7 +114,7 @@ Models include:
 
 ### `source_api.py`
 
-Simulates a small vendor API over local fixture files.
+Simulates a small source API over local fixture files.
 
 Responsibilities:
 
@@ -114,8 +124,8 @@ Responsibilities:
 - return related `job_updates`.
 - expose imperfect data for validation and duplicate tests.
 
-This module should feel like a documented API client, but it must not call a
-real external service.
+This module should behave like an API client. It must not call a real external
+service.
 
 ### `mapping.py`
 
@@ -161,12 +171,12 @@ Workflow:
 10. Remove the run history row if report writing fails.
 11. Return summary.
 
-This module coordinates the workflow but should delegate specialized logic to
-mapping, validation, reports, and repository modules.
+This module coordinates the workflow. Mapping, validation, report writing, and
+SQLite writes stay in their own modules.
 
 ### `reports.py`
 
-Writes handoff files.
+Writes output files.
 
 Expected files:
 
@@ -175,7 +185,7 @@ Expected files:
 - `rejected_jobs.csv`
 - `run_summary.md`
 
-Report writing should be deterministic so tests can compare expected output.
+Report writing must be deterministic so tests can compare output bytes.
 
 ### `repository.py`
 
@@ -339,5 +349,5 @@ Fields:
 Expected bad source data should become rejected rows.
 
 Unexpected runtime failures, such as unreadable fixture files, invalid output
-paths, or SQLite write failures, should return clear errors with enough context
-to debug the local run.
+paths, or SQLite write failures, should keep enough context to debug the local
+run.

docs/DELIVERY.md

@@ -2,11 +2,10 @@
 
 ## Purpose
 
-This document defines the handoff package for the finished delivery.
+This document defines the files a reviewer should expect after a demo export.
 
-The delivery shows more than working code. It shows how a buyer would receive a
-clean export workflow: output files, rejected rows, a run summary, and enough
-notes to rerun or extend the work.
+The package includes the generated outputs, rejected rows, a run summary, and
+the notes needed to rerun or extend the workflow.
 
 ## Delivery package
 
@@ -34,7 +33,7 @@ outputs/
 
 ### `clean_jobs.csv`
 
-Spreadsheet-ready export of accepted job records.
+Spreadsheet export of accepted job records.
 
 Required columns:
 
@@ -50,12 +49,12 @@ Required columns:
 
 JSON version of the accepted job records.
 
-The JSON file should contain the same records and fields as `clean_jobs.csv`.
-It exists for technical handoff, API-style review, or downstream processing.
+The JSON file contains the same records and fields as `clean_jobs.csv`. It is
+useful when the export needs to feed another tool.
 
 ### `rejected_jobs.csv`
 
-Rejected-row export for records that were not written to clean outputs.
+Rows that were not written to clean outputs.
 
 Required columns:
 
@@ -74,12 +73,11 @@ Required reason codes:
 - `invalid_date`
 - `duplicate_record`
 
-`raw_record` should preserve enough source data to understand what failed
-without requiring a debugger.
+`raw_record` should preserve enough source data to understand what failed.
 
 ### `run_summary.md`
 
-Human-readable summary of the export run.
+Readable summary of one export run.
 
 Required sections:
 
@@ -92,9 +90,9 @@ Required sections:
 - known limits.
 - suggested next steps.
 
-## Buyer-facing handoff standard
+## Review standard
 
-The delivery should answer these questions without requiring a meeting:
+The delivery should answer these questions from the files alone:
 
 - What does this workflow do?
 - What source data does it read?
@@ -106,9 +104,9 @@ The delivery should answer these questions without requiring a meeting:
 - How can the workflow be rerun?
 - What can be extended later?
 
-## Technical handoff standard
+## Technical review standard
 
-The repository should also make the implementation easy to review:
+The repository should also make the implementation easy to inspect:
 
 - API and CLI entry points should call the same export service.
 - mapping and validation should be testable without FastAPI or Typer.
@@ -129,17 +127,16 @@ When implementation changes:
   criteria change.
 - update `docs/PRD.md` if scope or acceptance criteria change.
 
-Do not add a new long-form document unless existing docs become too large to
-keep clear.
+Do not add another long document unless the current set becomes hard to read.
 
-## Next-step options
+## Next steps worth considering
 
 Realistic follow-up work may include:
 
 - connect the workflow to a real documented API.
 - write directly to Google Sheets.
 - add scheduled runs.
-- add buyer-specific validation rules.
+- add project-specific validation rules.
 - support larger files.
 - deploy the workflow to a server.
 - add another export type.
@@ -156,7 +153,7 @@ Avoid promising:
 
 The delivery is ready when:
 
-- the README explains the buyer problem, current status, and run path.
+- the README explains the problem, implemented scope, and run path.
 - source fixtures include valid, invalid, and duplicate records.
 - the output files exist and match this contract.
 - invalid and duplicate records are visible in rejected output.