01 / PROBLEM STATEMENT
Why this work exists
Moroccan investors need portfolio tracking and research tooling that respects Casablanca-market data constraints instead of silently fabricating unavailable prices, fundamentals, or benchmark history.
Data and source material
- Immutable cash, trade, dividend, fee, and tax transactions
- Published or provisional OHLCV records and Moroccan security metadata
- Optional MASI-family indices, company documents, annual reports, and fundamentals when rights and data are available
02 / SOLUTION OVERVIEW
From input to usable output
The platform separates an immutable transaction ledger from derived analytics, supports real-tracking and simulation portfolios, and makes missing or stale data explicit.
- 01
Record real-tracking or simulation transactions
- 02
Replay the ledger with exact-decimal weighted-average-cost accounting
- 03
Build derived snapshots through locked, retryable worker jobs
- 04
Value positions and calculate performance only when required market data exists
- 05
Stage and publish prices through a distinct second-admin review
03 / TECHNICAL ARCHITECTURE
Implemented components
v1 (public SaifInvest repo): Python ingestion and a FastAPI quant service with 8 routes for factor scoring, data quality, optimisation and backtesting
v2: Next.js in a pnpm/Turborepo workspace
Supabase Auth and owner-isolated PostgreSQL records
Worker-generated snapshots with locking and retries
Private ingestion tables and public-safe market views
Vitest, migration and live-database checks
04 / METHODOLOGY & IMPLEMENTATION
Decisions that shape the system
- The transaction ledger is authoritative; corrections are immutable counter-entries visible at correction time.
- Derived snapshots are disposable caches and cannot replace a newer valid generation.
- TWR and XIRR cover multiple periods; risk and concentration views appear only with sufficient data.
- Owner isolation uses PostgreSQL Row Level Security, while public-safe views separate published data from private ingestion tables.
Implemented capabilities
- Real-tracking and simulation portfolios
- Weighted-average-cost accounting and deterministic replay
- TWR/XIRR, portfolio risk and concentration analytics
- Moroccan security directory with OHLCV charting
- Two-admin price staging/publication
- Optional AI explanations with deterministic fallback
05 / RESULTS & EVIDENCE
What the source supports
- The repository documents a final MVP spanning authentication, ledger accounting, CSV import, valuation, performance, market research, and administration.
- English, French, and Arabic—including right-to-left presentation—are in scope.
- Market facts remain explicitly unavailable when a trusted source or redistribution right is missing.
Results preserve the repository’s units, evaluation framing, and stated limitations. Missing evidence is not converted into a claim.
06 / CHALLENGES & LIMITATIONS
Where the evidence stops
- SaifInvest is not a brokerage or custodian and never represents recorded transactions as market orders.
- Production market-data display depends on appropriate exchange and redistribution rights.
- Optional AI explanation has a deterministic fallback and is not the source of financial calculations.
07 / WHAT THIS DEMONSTRATES
Engineering signal
Financial domain modelling, exact accounting, data governance, multilingual product engineering, and explicit handling of incomplete market data.
08 / SOURCE & RELATED WORK
Trace the evidence
0675f048b6ab49455ab40a27ce4ea2296d7500cc ↗README.md · docs/MVP_STATUS.md · docs/FINAL_MVP_RUNBOOK.md · docs/BVC_PUBLIC_TESTING.md · packages/portfolio-engine/