System decisions
Data boundaries, source evidence, approval points, integration choices, and the evaluation plan. The proposed AI layer below is a design study.
AI ARCHITECTURE / DEVELOPMENT / SOLUTIONS ENGINEERING
Start with
the operation.
Make the decision clearer.
Then choose the technology.
My focus is oilfield and logistics workflows: who needs the information, where it comes from, what action it supports, and how the result can be checked.
01 / Evidence before titles
Three capabilities.
One practical focus.
Implementation evidence
Inspect ShiftLedger’s working UI and server behavior. The build is AI assisted; it does not currently run a language model or a predictive maintenance model.
Workflow fit
Map the operator’s task to the company’s decision. Define pilot measures and integration requirements before claiming business impact.
02 / Architecture walkthrough
Follow the record.
See the boundaries.
IMPLEMENTED / FICTIONAL, SESSION-ONLY DATA
- BrowserReadings, assigned people, review forms
- Server boundaryRoute access, origin checks, input validation
- Domain logicReconciliation, business measures, versioned service review
- Decision recordSource references, exceptions, draft reports
Public sample routes accept a fixed fictional scenario. Calculation source stays on the server. Production identity, durable storage, and integrations are next milestones.
DESIGN STUDY / NOT YET IMPLEMENTED
- Approved sourcesCompany documents and scoped job records
- Access filterCompany, role, crew and job permissions before retrieval
- Grounded draftSource-linked handover summary with uncertainty and abstention
- Human reviewNamed reviewer checks evidence before any approved write
Proposed use: summarize open work and relevant service history. Equipment control, diagnosis, equipment release, and autonomous billing are outside this design. Model/provider selection follows data policy, evaluation, and an agreed cost limit.
Showing the working prototype architecture.
03 / From the field to the code
Years of reading the numbers.
Rules in the system.
Each habit from the field maps to a rule the prototype enforces on the server. Choose one to see the rule and the automated test that proves it.
THE RULE IN SHIFTLEDGER
04 / A failure worth designing for
Slow answers arrive late.
The screen must not lie.
When a user edits twice quickly, the first answer can land after the second. Click “Edit threshold” twice, then turn the guard off and repeat. ShiftLedger discards a response if a newer edit exists, and a test covers it.
Screen showsnone yet
Simulation of the pattern with made-up latencies. It is not ShiftLedger’s code. The matching check is “an older response cannot enable acknowledgement after a newer edit” in client-state.test.mjs.
05 / Tools with evidence
What is built.
What comes next.
| Area | Evidence / status |
|---|---|
| Frontend | HTML, CSS, JavaScript; responsive layouts, labeled forms, keyboard navigation, progressive disclosure. |
| Backend | JavaScript Worker, server-side calculations, validated sample APIs, escaped report output, explicit access boundaries. |
| Validation | Node test runner; calculation, authorization, source exposure, stale response, and workflow-state checks. |
| Delivery | Private Git source, versioned deployment, isolated public sample data. No production customer data is used. |
| AI design study | Permission-aware retrieval, grounded summaries, evaluation cases, human approval. A model-free evaluation harness runs in the AI Lab. No deployed LLM, RAG pipeline, or predictive reliability model is claimed. |
| Integration plan | Agree source IDs, units, timestamps, read/write permissions, retry behavior, and reconciliation with the company’s systems before building connectors. |
06 / Architecture decisions
The reasoning
behind the system.
Keep calculations outside model output
Material balances, financial totals, and readiness rules use validated server calculations. A future model can explain a result but cannot invent quantities or silently replace the source of truth.
Require permissions before retrieval
A production AI search layer would filter authorized records before retrieval and generation. Evaluation must include cross-company, cross-crew and cross-job denial cases, including attempted instructions inside retrieved documents.
Make missing evidence visible
Unknown costs and missing readings remain unknown. A proposed assistant must cite the supporting record, identify conflicts and stale evidence, and decline unsupported answers.
Measure the AI layer before a pilot
Build a domain-reviewed test set with answerable, unanswerable, conflicting, outdated, and unauthorized scenarios. Measure source fidelity, supported claims, correct abstention, data leakage, review time, latency and cost per accepted draft. Baselines and acceptance thresholds must be agreed with the company.
07 / A second application
Field Notes
content assistant.
A recurring marketing-agent workflow prepares drafts on Monday, Wednesday and Friday mornings in Central time. It turns approved project evidence into LinkedIn drafts: a useful field observation, the workflow decision it suggests, and a concrete example readers can explore.
The workflow checks claims, keeps employer information private, and puts a human review before publication. Direct LinkedIn publishing is not connected. The portfolio’s live project and architecture study provide its starting evidence.
Follow Matthew on LinkedIn ↗08 / How this was built
AI-assisted,
human-directed.
Matthew supplies the field rules and decides what is true. Matthew directs the project. AI tools do drafting, coding and checking under those rules. This is the actual process, including what the tools did not do.
Claude and Claude Code
Wrote and revised the JavaScript, the tests, the evaluation harness and the documentation, working from written project instructions. A separate Claude session prepared the illustrated introduction. Scene artwork is AI-assisted illustration. No paid model API runs on this site and no keys are in it.
Written context, then tests
Every session starts from the same instruction and current-state files, so decisions and limits carry over instead of being re-explained. Rules become failing tests first. Safeguards are then removed on purpose (mutation checks) to confirm the tests catch it.
Checked in real browsers
Pages and downloads are exercised in headless Chromium at desktop and phone widths, under a strict content-security policy. A page check flags broken links. Failures found along the way, such as a policy violation that broke the layout, are fixed and logged.
What a person still decides
Field rules and domain truth (Matthew), project direction and approval of public wording (Matthew), and anything published. Claims on this site are limited to what exists and can be inspected. The AI Lab states what is not built: no deployed language model, no retrieval over a real corpus, no autonomous agent.