Documents Collector Static Flow

Static process map for human verification. No graph physics, no crossing connectors, no hidden branches.
static contract view

1. Local Backend Setup

Actor
Developer / tester
Run Bash
run_documents_api.sh
Python available?
python3 or python
Venv exists?
.venv-documents-api
Install deps
FastAPI / Uvicorn / multipart
Start FastAPI
127.0.0.1:8010

Python branch

YES
Continue to venv check.
NO
Stop. Backend cannot start.

Venv branch

YES
Use existing local venv.
NO
Create `.venv-documents-api`, then install dependencies.

Hosted entry

OK
Open browser at `http://127.0.0.1:8010/`.
NOT TARGET
Double-click `file://` has no backend persistence.

2. Browser To Backend Flow

Open hosted page
GET /
Serve HTML
DocumentsIntake.html
Select files
drag-drop or open dialog
POST upload
/api/documents

Current implementation

NOTE
Backend endpoint exists.
OK
HTML calls `POST /api/documents`.

Required behavior

TARGET
Browser submits selected files as multipart form data.
TARGET
Server returns JSON result to UI.

Out of scope

NO
No browser File API persistence as final architecture.
NO
No silent file writes from `file://`.

3. Server-Side Persistence Conditions

Files present?
multipart payload
Documents exists?
./Documents
Filename collision?
same saved name
Resolve name
file_1.ext if needed
Save files
server-side ./Documents
Return JSON
status=saved

Files present?

YES
Continue to folder check.
NO
Reject request. Nothing to persist.

Documents exists?

YES
Use existing folder.
NO
Create `Documents` dynamically during upload.

Filename collision?

NO
Save with original sanitized filename.
YES
Save with unique suffix, e.g. `file_1.ext`.

4. Verification Matrix

Contract Current status Evidence Validation
Bash runner creates runtime and starts FastAPI. PASS `run_documents_api.sh` Manual run / future smoke test.
Backend serves hosted HTML. PASS `documents_api.py`, `GET /` GET `/` returns HTML.
Backend accepts and saves files to dynamic `Documents` folder. PASS backend `POST /api/documents` API smoke test with multipart file.
Hosted HTML sends selected files to backend. NEEDS E2E `uploadToBackend()` uses `fetch('/api/documents')`. Playwright e2e after implementation.
Green: implemented expected path Amber: condition or pending branch Blue: setup/backend action Red: stop / not target / TODO