HalalTrade AI¶
A private, local-first AI investment research and paper-trading platform with Shariah compliance as a hard constraint.
Design phase
This repository contains architecture, product, and delivery design only. No application code has been written yet — that is deliberate. The design is the deliverable that has to be right first.
Start here¶
If you read three things, read these:
- Vision & Scope — what this is, who it's for, and what it explicitly is not
- System Architecture — components, boundaries, and how a recommendation is produced
- Shariah Compliance Engine — the constraint that shapes everything else
The three ideas that shape the rest¶
Compliance is a gate, not a vote. The Shariah Advisor does not contribute a weighted opinion that strong financials can outvote. It returns COMPLIANT, NON_COMPLIANT, or UNCERTAIN, and anything other than compliant terminates the pipeline. This also removes capabilities from the trading engine itself — no short selling, no margin, no interest on idle cash, no conventional derivatives. See ADR-0004.
The LLM explains the decision; it does not compute it. Twelve language models averaging their opinions is an unauditable and poorly calibrated estimator. Analyst agents emit structured, evidence-cited signals; a deterministic, walk-forward-calibrated aggregator produces the score; the Supervisor writes the explanation and may veto with a stated reason — but cannot invent a score. See ADR-0003.
Ingested text is hostile until proven otherwise. News articles, social posts, and filings are attacker-controlled surfaces flowing into models that influence trades. Content-analysis agents run with no tool access, inside a quarantine boundary, and emit schema-validated output only. See ADR-0005.
Full contents¶
| # | Document | What it answers |
|---|---|---|
| 00 | Vision & Scope | What we are building, for whom, and what we are explicitly not building |
| 01 | System Architecture | Components, boundaries, deployment topologies, repository layout |
| 02 | Technology Decisions | Every stack choice with the alternatives that lost and why |
| 03 | Data Platform | Sources, ingestion, point-in-time storage, feature store, licensing |
| 04 | AI Agent System | The twelve agents, their contracts, and how the Supervisor actually decides |
| 05 | Shariah Compliance Engine | Rule packs, ratio screens, purification, how it constrains the system |
| 06 | Paper Trading Engine | Order lifecycle, fills, slippage, fees, corporate actions |
| 07 | Risk Management | Position sizing, exposure limits, circuit breakers, drawdown control |
| 08 | Backtesting | Engine design and the biases it is built to make hard to commit |
| 09 | Web Experience | Information architecture, the five sections, explainability UI |
| 10 | Security & Privacy | Threat model, key management, prompt-injection containment |
| 11 | Learning & Evaluation | How the system improves without fooling itself |
| 12 | Roadmap | Six phases, with exit criteria for each |
| 13 | API & Event Contracts | Core domain types, REST surface, event schemas |
Architecture Decision Records record the decisions that would be expensive to reverse.
Not financial advice¶
This is a research and simulation tool for personal use. The compliance engine mechanically applies published screening methodologies — it is not a religious ruling, and its conclusions should be reviewed by a qualified scholar.