TradeFoundry
An evidence-first operating system for researching and governing global trade opportunities.
I framed the commercial thesis, defined the public domain and governance boundaries, and built the private local MVP and its acceptance structure.
- Role
- Product architect and independent builder
- Capability proof
- Shows product judgment, Python/backend system design, evidence modeling, constrained allocation, and approval-bound commercial governance.
- Technology
- Python · FastAPI · PostgreSQL · Alembic
Context
Global trade is not only a search problem. It is a portfolio of uncertain, constrained, evidence-dependent decisions made across policy, procurement, pricing, logistics, counterparties, cash, and time.
I began TradeFoundry after recognizing that quantitative research contributes something more useful than the language of trading: a discipline for stating hypotheses, controlling what was knowable at a point in time, allocating scarce resources, limiting downside, governing execution, and learning from every outcome—including failure.
Problem
Commercial evidence is fragmented, assumptions are often implicit, constraints interact, and feedback is selective. A spreadsheet can rank candidates, but it does not automatically preserve provenance, expose hindsight, compare opportunity cost, or prevent a confident model output from becoming an unauthorized real-world action.
TradeFoundry asks a narrower question: can global-trade decisions become more explicit, replayable, and governable without pretending that software removes human commercial judgment?
Thesis
The system applies quantitative decision discipline to global trade—not quantitative trading to foreign-trade products. Signals prioritize research. Hypotheses can be rejected. Replay protects the point-in-time record. Allocation makes opportunity cost visible. Risk limits constrain action. Execution remains approval-bound. Outcomes and failures return to the learning record.
What this proves
This private local MVP demonstrates how I turn an ambiguous commercial idea into a bounded product architecture: Python/backend modeling, evidence contracts, portfolio governance, human authority, acceptance identifiers, and an honest boundary between research software and real commercial operations.
Quant-to-trade
Method transfer, with boundaries
TradeFoundry is a private research MVP exploring quantitative decision discipline for global trade: structure evidence, state falsifiable hypotheses, allocate scarce resources, govern consequential execution, and learn from outcomes.
| Quantitative discipline | Global-trade application | Boundary |
|---|---|---|
| Signal | An evidence-supported candidate for further commercial research. | A signal prioritizes attention; it is not a price prediction or a promise of demand. |
| Falsifiable hypothesis | A product, country, route, or buyer thesis with evidence and explicit invalidation conditions. | A hypothesis is designed to be rejected; it is not a sales forecast. |
| Replay | A point-in-time review of what was knowable when a decision was made. | Replay checks process quality and leakage; it does not manufacture a future forecast. |
| Allocation | Distribution of research time, working capital, supplier capacity, and opportunity budget. | This is operating-resource allocation, not an investment product or securities portfolio. |
| Risk limit | Human-defined constraints for compliance, credit, cash flow, concentration, and supply-chain exposure. | Limits support review; they do not replace legal, compliance, finance, or executive judgment. |
| Governed execution | Approval-bound research, outreach, procurement, fulfilment, and settlement steps. | Consequential commercial actions remain under explicit human authority. |
| Attribution and learning | Comparison of hypotheses, decisions, actual outcomes, errors, and failure samples. | Learning improves the record; it does not imply a self-optimizing or profitable system. |
Governance
Constraints
Constraints that shape the system
- Policy, price, logistics, and company evidence change over time, so a decision must preserve what was knowable at the point it was made.
- Trade opportunities compete for working capital, research time, supplier capacity, and risk budget rather than existing as independent rankings.
- Outreach, procurement, payment, contracting, certification, and order actions carry consequences that software must not authorize silently.
- The implementation is private, so public proof must explain decisions and evidence boundaries without exposing code, internal paths, or sensitive operating detail.
Key decisions
Choices, alternatives, and trade-offs
Separate evidence from opportunity claims
- Context
- A promising narrative can otherwise become an opportunity record before its sources, timing, contradictions, and review state are visible.
- Choice
- Create a governed evidence layer before opportunity compilation and require claims to reference that evidence explicitly.
- Alternatives
- Score opportunities directly from source feeds; Keep supporting links in analyst notes or spreadsheets
- Trade-off
- The extra evidence discipline slows initial intake, but it makes later challenge, replay, and correction possible.
Make hypotheses falsifiable and replayable
- Context
- Commercial judgment becomes difficult to improve when assumptions are only reconstructed after the outcome.
- Choice
- Represent a hypothesis with supporting evidence, invalidation conditions, decision identifiers, and point-in-time replay boundaries.
- Alternatives
- Store only a final score; Write an unstructured recommendation memo
- Trade-off
- More structure creates authoring overhead, but it prevents hindsight from rewriting what the original decision meant.
Allocate under shared constraints
- Context
- The highest-scoring candidate may still be the wrong next action when cash, concentration, capacity, or compliance limits are considered together.
- Choice
- Treat opportunities as a governed operating portfolio with explicit budgets, risk limits, and versioned decision records.
- Alternatives
- Choose the top score independently; Let each route owner optimize a local objective
- Trade-off
- Portfolio governance is less immediately simple than a leaderboard, but it exposes opportunity cost and coupled risk.
Keep consequential execution approval-bound
- Context
- Research confidence does not grant authority to contact, purchase, pay, contract, certify, or place an order.
- Choice
- Compile approved decisions into controlled execution steps while reserving consequential actions for explicit human authorization.
- Alternatives
- Allow end-to-end autonomous commercial execution; Leave approval as an informal operational convention
- Trade-off
- Human gates reduce speed and autonomy, but they preserve accountability where legal, financial, and relationship consequences exist.
Architecture and failure behavior
Responsibility, input, output, and failure
- 01
Source governance
Register where evidence came from, when it was observed, and how it may be used.
- Input
- Reviewed public or licensed research inputs
- Output
- Versioned source records and ingestion decisions
- Failure
- Unidentified, stale, or policy-incompatible input is held outside decision evidence.
- 02
Evidence ledger
Preserve claims, provenance, contradictions, timing, and review state.
- Input
- Governed source records
- Output
- Traceable evidence available to hypotheses
- Failure
- Conflicting or missing support remains visible instead of being collapsed into confidence.
- 03
Commercial world model
Express products, countries, routes, parties, constraints, and time as reviewable relationships.
- Input
- Evidence and public domain definitions
- Output
- Versioned commercial state
- Failure
- Unresolved identity or incompatible state blocks dependent compilation.
- 04
Opportunity compiler
Turn evidence and hypotheses into comparable candidates with explicit uncertainty.
- Input
- Commercial state, hypothesis, and evidence references
- Output
- Opportunity candidates and diagnostics
- Failure
- Unsupported or internally inconsistent hypotheses are rejected or returned for research.
- 05
Portfolio governance
Allocate scarce operating resources under budgets, concentration, and risk limits.
- Input
- Comparable candidates and human-defined constraints
- Output
- Versioned allocation and approval decisions
- Failure
- Constraint conflicts remain unresolved until a human decision records the trade-off.
- 06
Governed execution
Translate approved decisions into controlled bilateral work and checkpoints.
- Input
- Approved allocation and action policy
- Output
- Execution records, receipts, and approval state
- Failure
- Missing authority, duplicate intent, or ambiguous effects halt consequential progress.
- 07
Outcome learning
Compare hypotheses and decisions with outcomes, errors, missing data, and failures.
- Input
- Decision records, execution evidence, and observed outcomes
- Output
- Attribution and learning records
- Failure
- An unverified result remains unknown rather than being counted as success.
Failure modes
How failure is detected, bounded, and escalated
| Trigger | Detection and response | Side effects and human boundary | Assurance |
|---|---|---|---|
| A source changes after an opportunity was evaluated. | The evidence reference retains its observed time and version rather than resolving silently to the newest value. Keep the original decision reproducible and require a new review for the changed evidence. | No existing approval is silently upgraded to the new source state. A reviewer decides whether the change invalidates the opportunity. | Verified |
| A hypothesis lacks sufficient or consistent evidence. | Compilation identifies missing support, contradiction, or unresolved model state. Return the candidate to research instead of converting uncertainty into a high score. | The candidate cannot enter governed execution from an unresolved state. A researcher may gather more evidence, narrow the claim, or reject it. | Verified |
| An attractive candidate breaches a shared portfolio limit. | Allocation evaluates cash, concentration, capacity, and risk constraints together. Keep the decision unresolved rather than letting one score override the constraint. | No downstream work is authorized from a conflicted allocation. A decision owner records which opportunity or limit changes and why. | Designed |
| The same governed action is submitted twice. | Decision and acceptance identifiers expose duplicate intent at the execution boundary. Return the existing action state or halt the conflict instead of creating another consequential step. | Duplicate submission does not imply duplicate outreach, purchase, payment, or order activity. Ambiguous identity is reviewed before any retry is authorized. | Designed |
| An action is requested without the required human authority. | The governed execution boundary checks approval state before consequential work. Block the action and retain a visible pending or denied state. | Research output alone cannot contact, purchase, pay, contract, certify, or order. An authorized person may approve, reject, or request more evidence. | Verified |
Project evidence
Evidence and its verification scope
Architecture
The local MVP has explicit boundaries from source governance through evidence, opportunity, portfolio decisions, bilateral execution, control, settlement, and learning.
Architecture implemented in a private local/MVP repository; not a production deployment.Private repository README and architecture checkpointKey choices for ingestion, evidence, the commercial world model, opportunity compilation, execution, governance, and learning are documented as ADRs.
Design rationale and local implementation boundaries.Private repository ADR indexVerification
The repository organizes deterministic fixtures and contract-level tests against explicit acceptance identifiers across all nine boards.
Local fixtures and mock transports; no live buyer, supplier, bank, ERP, or model contacted.Private repository verification sectionDisclosure
Outbound communication and consequential commercial actions remain approval-bound rather than silently autonomous.
Reference control path only; no authorization for real-world transactions.Private repository boundary statementHonest status
Implemented, not claimed, and still required
- Running status
- Private research
- Data
- Local deterministic fixtures and research records; no production, customer, buyer, or supplier data is claimed.
- External integrations
- Local or mock transports; no live buyer, supplier, bank, ERP, regulated provider, or autonomous model is contacted.
- Revenue claim
- No commercially actionable Alpha, customer revenue, closed transaction, ROI, or performance result is claimed.
- Source
- Private source
- Before production
- Live-source licensing, legal and compliance review, identity and secrets, operational approvals, audit, and a bounded real-world pilot remain required.
Research status: TradeFoundry is a private local/MVP system. It does not claim production data, a commercially actionable Alpha, regulatory approval, or a completed real-world trade loop.
Human authority: Outbound contact, purchasing, payment, contracting, certification, and order actions remain subject to explicit human approval.
Reflection and next priorities
What worked
Treating uncertainty, approval, and learning as first-class records turned a broad idea into a system that can be challenged rather than merely admired.
What I would change
I would narrow the first public pilot to one product-route hypothesis and one read-only evidence path before expanding the domain model.
Next priorities
- Freeze a legally reviewable public evidence pack for one bounded product-route hypothesis.
- Run a human-reviewed, read-only replay with explicit invalidation criteria.
- Design a pilot approval and audit boundary before any external commercial action.
Not worth doing yet: Autonomous outreach, payment, contracting, order placement, and broad data-provider integrations are not worth building before one governed pilot proves the evidence and review model.