Extra Work CaptureField record system
For engineering reviewersReview the build Portfolio demoSynthetic data only
← Demo index

System evidence packet · Revision 04

Engineering
record.

One narrow construction workflow, made inspectable from browser intent to business history. This page separates working proof from the architecture proposed for a real authenticated product.

FastAPI command trace · Verified locally

What happens when the field submits to Python

A synthetic request crosses five explicit boundaries. Each one owns a different kind of decision.

  1. 01

    HTTP perimeter

    POST /api/demo/tickets

    Checks same-origin intent, validates the payload, and requires an idempotency key.
    Observable proof

    Cross-origin mutations are rejected before application work begins.

  2. 02

    Generated contract

    createTicket(OpenAPI command)

    The Next.js boundary sends one typed command and the opaque workspace identifier to FastAPI.
    Observable proof

    The committed generated client is checked against the exported OpenAPI document in CI.

  3. 03

    FastAPI application service

    draft → submitted → response requested

    The state machine permits only explicit transitions and rejects stale or invalid actions.
    Observable proof

    The complete browser workflow runs against Python-owned commands in CI.

  4. 04

    Repository port

    mutate one isolated workspace

    The process-memory adapter scopes tickets, tokens, retries, and sequence counters to one demo session.
    Observable proof

    Cross-browser tests prove a scoped link can cross sessions without exposing another workspace.

  5. 05

    Business history

    append ticket events

    The current state stays convenient to query while meaningful actions remain inspectable.
    Observable proof

    Actor, time, transition, and human-readable detail travel with the record.

Architecture · Truth before aspiration

Running today. Designed next.

One configuration boundary selects the command owner. A request never writes to both runtimes.

Running todayStage 4 deployment profiles
Local APINext.js BFF→Generated client→FastAPI command service
Public SiteNext route handlers→TypeScript service→D1 session

The FastAPI profile owns every command in local and CI runs. The public portfolio Site keeps its bounded D1 implementation until Python hosting is deliberately added.

Designed nextAuthenticated product layer
Next.js UI / BFF→Hosted FastAPI→PostgreSQL+Private R2 evidence

The normalized PostgreSQL schema and isolation tests now run locally and in CI. Repository wiring, OIDC identity, private uploads, and outbox delivery remain explicit next steps.

Lifecycle contract

The UI does not invent status

CommandFromToInvariant
CapturedraftsubmittedField records the requested scope.
Requestsubmittedresponse_requestedSystem issues one scoped response link.
Respondresponse_requestedacknowledged / declinedRequester sees only the safe projection.
Completeacknowledgedwork_completedOffice records labor, crew, material, and equipment actuals.
Pricework_completedpricedOffice records a proposed amount and basis.
Outcomepricedapproved / disputedCommercial outcome is added without erasing disagreement.

Decision register

Tradeoffs, recorded

Choices are tied to the current portfolio boundary and include an explicit review trigger.

BOUNDARY 01

Acknowledgment is not approval

The requester confirms the recorded description. The interface does not claim a signature, final price, or replacement for the parties’ contract.

ADR 002

Ports before providers

Ticket, response, evidence, notification, and packet behavior is expressed as narrow contracts before database or delivery SDKs enter the application.

ADR 003

Bounded D1 for the public demo

Each visitor gets an isolated 24-hour synthetic workspace. This is durable demo state, not the production tenant model.

ADR 004

Commands cross as one boundary

Create, respond, actuals, pricing, outcome, idempotency, transitions, and audit events move together. When FastAPI is configured, write failures stop at that boundary rather than falling through to a second command owner.

ADR 005

Database guardrails before database claims

The PostgreSQL migration is executed against a real database and proves RLS isolation, hashed-token constraints, and immutable events before FastAPI is allowed to select the durable adapter.

Failure ledger

Bad paths have an owner

The demo models failures that reveal architectural behavior without pretending to provide production operations.

FailureSystem behaviorStatus
Duplicate mutationReturn the original resultDemonstrated
Invalid transitionReject without changing the recordDemonstrated
Configured repository failureShow an error and accept a corrected retryDemonstrated
Expired or unknown linkReveal no unrelated project informationDemonstrated
Configured FastAPI write outageFail closed; never retry through a second backendDemonstrated
Stale D1 revisionReturn refresh-and-retry conflictImplemented
Cross-tenant PostgreSQL queryHide and reject records through forced RLSDemonstrated
Audit-event rewriteReject update or deletion in PostgreSQLDemonstrated
Evidence upload failureRetain pending metadata; expose retryDesigned

Claim ledger

What this build proves—and does not

Recruiter-facing evidence is useful only when demonstrated, designed, and deferred work remain distinguishable.

Demonstrated

Server-owned lifecycle

Pure state machine plus route and repository tests.

Demonstrated

Visitor isolation

Opaque session cookie, bounded D1 snapshot, and cross-browser E2E coverage.

Demonstrated

Requester data minimization

Public routes return a seven-field requester projection.

Deferred

Real file evidence

R2 is not connected; evidence remains synthetic metadata.

Deferred

Authenticated organizations

No accounts or production tenant authorization exist in this portfolio build.

Demonstrated

FastAPI command ownership

All five commands, idempotency, isolation, audit events, live contract tests, and the full browser workflow.

Demonstrated

PostgreSQL schema guardrails

Real migration replay, tenant RLS, hashed-token, and append-only-event integration tests.

Planned

Durable FastAPI repository

The Python command service still selects deterministic process memory.

Migration record

Move command truth without splitting it.

  1. 01

    Complete · Contract FastAPI OpenAPI surface and generated TypeScript client.

  2. 02

    Complete · Read path Workspace-scoped office listing through the generated client and BFF.

  3. 03

    Complete · Command path Python owns lifecycle rules, idempotency, workspace isolation, and audit-event creation when configured.

  4. 04

    Complete · Database guardrails Apply PostgreSQL migrations and prove tenant RLS, token hashing, and immutable events.

  5. 05

    Next · Durable repository Replace process memory with transactional PostgreSQL commands before hosting the backend.