Skip to content

docs(predict): add PredictNext architecture and migration plan #28702

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
matallui wants to merge 5 commits into
base: main
Choose a base branch
from
Draft

docs(predict): add PredictNext architecture and migration plan #28702

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a43a3d4
docs: add PredictNext architecture and migration plan
matallui Apr 11, 2026
037d631
docs: revise hook architecture to granular query hooks with domain fo…
matallui Apr 11, 2026
6d7dab8
docs: clarify hook usage per component tier
matallui Apr 11, 2026
5843381
docs: revise migration plan to inside-out strategy with vertical UI s…
matallui Apr 11, 2026
ab340d5
docs: add ASCII diagrams to PredictNext architecture docs
matallui Apr 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
126 changes: 126 additions & 0 deletions app/components/UI/PredictNext/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,126 @@
# PredictNext

Predict integrates prediction market platforms like Polymarket and future Kalshi into MetaMask Mobile. Users browse events, place bets on outcomes, and manage positions. The feature also supports depositing and withdrawing funds.

## Architecture Overview

The system uses a four layer architecture. Components sit at the top, followed by hooks. Controllers and services handle the logic. Adapters connect to external protocols.

### Services

Six deep services manage the domain logic. TradingService handles orders. MarketDataService and PortfolioService extend BaseDataService for data fetching. TransactionService tracks on chain activity. LiveDataService provides real time updates. AnalyticsService records user interactions.

### Orchestration

A thin PredictController orchestrates write operations. It delegates tasks to the underlying services.

### Adapters

Protocol adapters like PolymarketAdapter and the future KalshiAdapter handle external communication.

### Hooks

Hooks are organized by domain in co-located folders with barrel exports. Data hooks are granular — each triggers exactly one query so components only fetch what they need. Imperative hooks (useTrading, useTransactions, useLiveData) remain deep since they manage complex stateful workflows. Domains include events, portfolio, trading, transactions, live-data, navigation, and guard.

### Components

Components follow a three tier structure. Primitives like EventCard and OutcomeButton form the base. Widgets like EventFeed and OrderForm combine primitives. Views like PredictHome and EventDetails represent full screens.

## Directory Structure

```
PredictNext/
├── README.md
├── UBIQUITOUS_LANGUAGE.md
├── index.ts # Public API
├── docs/
│ ├── architecture.md
│ ├── services.md
│ ├── adapters.md
│ ├── components.md
│ ├── hooks.md
│ ├── testing.md
│ ├── state-management.md
│ ├── error-handling.md
│ └── migration/
│ ├── README.md
│ └── phase-1-*.md
│ └── phase-2-*.md
│ └── phase-3-*.md
│ └── phase-4-*.md
│ └── phase-5-*.md
│ └── phase-6-*.md
│ └── phase-7-*.md
├── compat/ # Temporary translation layer (deleted in Phase 7)
│ ├── mappers.ts
│ ├── types.ts
│ └── index.ts
├── types/
├── controller/
├── services/
│ ├── trading/
│ ├── market-data/
│ ├── portfolio/
│ ├── transactions/
│ ├── live-data/
│ └── analytics/
├── adapters/
│ ├── types.ts
│ ├── polymarket/
│ └── kalshi/ (future)
├── hooks/
│ ├── events/
│ ├── portfolio/
│ ├── trading/
│ ├── transactions/
│ ├── live-data/
│ ├── navigation/
│ └── guard/
├── components/
│ ├── EventCard/
│ ├── OutcomeButton/
│ ├── PositionCard/
│ ├── PriceDisplay/
│ ├── Scoreboard/
│ ├── Chart/
│ └── Skeleton/
├── widgets/
│ ├── EventFeed/
│ ├── FeaturedCarousel/
│ ├── PortfolioSection/
│ ├── OrderForm/
│ └── ActivityList/
├── views/
│ ├── PredictHome/
│ ├── EventDetails/
│ ├── OrderScreen/
│ └── TransactionsView/
├── routes/
├── selectors/
├── constants/
└── utils/
```

## Public API

The index.ts file defines the public API. It exports views for navigation and components for embedding. Hooks for data access, types, and selectors are also available. Internal modules like services and adapters remain private.

## Design Principles

Modules are deep with slim interfaces. We use compound components similar to the Vercel style. Read services extend BaseDataService. We define errors out of existence. The team uses DDD ubiquitous language for consistency.

## Documentation Index

- [Architecture](docs/architecture.md)
- [Services](docs/services.md)
- [Adapters](docs/adapters.md)
- [Components](docs/components.md)
- [Hooks](docs/hooks.md)
- [Testing](docs/testing.md)
- [State Management](docs/state-management.md)
- [Error Handling](docs/error-handling.md)
- [Migration](docs/migration/README.md)

## Migration Status

This feature is being built using an inside-out migration from the original Predict directory. The new adapter and services replace internals first while the old UI stays unchanged, then UI migrates as vertical slices. Check the [migration documentation](docs/migration/README.md) for details.
95 changes: 95 additions & 0 deletions app/components/UI/PredictNext/UBIQUITOUS_LANGUAGE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
# Ubiquitous Language

## Core Data Model

| Term | Definition | Aliases to avoid |
| :----------- | :------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------- |
| **Event** | A group of related binary markets on a single topic. For example, "2026 NBA Finals" or "Will ETH hit $5k?" | Market (old codebase term), PredictMarket (old type name) |
| **Market** | A single binary question within an event, resolved as Yes or No. For example, "Lakers to win Game 7" | Outcome (old codebase term), PredictOutcome (old type name), condition |
| **Outcome** | One side of a binary market, representing a tradeable position. Usually labeled "Yes" or "No" but may have custom labels. | OutcomeToken (old codebase term), token, share |
| **Position** | A user's holdings in a specific outcome, measured in shares. | Bet, wager, stake |
| **Order** | A request to buy or sell outcome shares at a specified price. | Trade, transaction |

## Order Lifecycle

| Term | Definition | Aliases to avoid |
| :---------------- | :--------------------------------------------------------------------------------------------------------------------------- | :----------------------------- |
| **Active Order** | An order currently being processed through the placement pipeline. This includes preview, deposit, place, and confirm steps. | Pending order, in-flight order |
| **Order Preview** | A price quote showing estimated cost, fees, and potential return before placement. | Quote, estimate |
| **Cash Out** | Selling an existing position before event resolution. | Sell, exit |
| **Claim** | Collecting winnings from a resolved market where the user held the winning outcome. | Redeem, collect |

## Financial Terms

| Term | Definition | Aliases to avoid |
| :------------ | :--------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------- |
| **Deposit** | Transferring USDC from the user's wallet to their prediction market account. This usually goes to a Polymarket proxy wallet. | Fund, top up |
| **Withdraw** | Transferring USDC from the prediction market account back to the user's wallet. | Cash out (ambiguous, also means selling positions) |
| **Balance** | The user's available USDC in their prediction market account, ready for placing orders. | Funds, wallet balance (ambiguous, could mean main wallet) |
| **Volume** | Total USDC traded on a market or event across all users. | Liquidity (different concept) |
| **Liquidity** | The depth of available orders in a market's order book. Higher liquidity means less price slippage. | Volume (different concept) |

## Platform Terms

| Term | Definition | Aliases to avoid |
| :--------------- | :---------------------------------------------------------------------------------------------------------- | :--------------------------------------- |
| **Provider** | An external prediction market platform integrated as a data source. Examples include Polymarket and Kalshi. | Platform, exchange, source |
| **Adapter** | The code module that translates between a provider's native API and Predict's canonical data model. | Provider (overloaded), bridge, connector |
| **Proxy Wallet** | A smart contract wallet created on the provider's platform to hold user funds and execute trades. | Account, sub-wallet |

## UI Terms

| Term | Definition | Aliases to avoid |
| :----------------- | :--------------------------------------------------------------------------------- | :----------------------------------- |
| **Event Card** | A card component displaying an event with its markets and outcomes. | Market card (old term) |
| **Outcome Button** | A tappable button representing one outcome of a market, showing the current price. | Bet button (old term), action button |
| **Position Card** | A card displaying a user's position in a specific market, including P&L. | Position row, position detail |

## Architecture Terms

| Term | Definition | Aliases to avoid |
| :------------- | :-------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------- |
| **Service** | A deep module encapsulating a specific domain with a slim public interface. Examples include trading and market data. | Controller (different role), manager, handler |
| **Controller** | A thin orchestrator that delegates to services. It serves as the entry point for write operations from the UI. | Service (different role) |

## Relationships

- Each **Event** contains one or more **Markets**.
- A **Market** contains exactly two **Outcomes**, typically Yes and No.
- Every **Position** is tied to exactly one **Outcome**.
- An **Order** targets exactly one **Outcome**.
- The **Provider** is accessed through exactly one **Adapter**.
- An **Event** originates from exactly one **Provider**.

## Example Dialogue

> **Dev:** "When a user taps a market card and sees the details..."
>
> **Domain expert:** "That's an **Event Card**. This component shows an Event. For example, 'Will ETH hit $5k?' One Event may contain one or more Markets. In this case there's just one Market, the binary Yes/No question."
>
> **Dev:** "So when they tap the Yes button at $0.65 to place a bet..."
>
> **Domain expert:** "They're tapping an **Outcome Button** for the Yes Outcome. Such an action creates an Order to buy shares of that Outcome. We don't call it a 'bet' in code, it's an **Order**."
>
> **Dev:** "And after the order goes through, their holdings show up as a position?"
>
> **Domain expert:** "Exactly. The Order creates a Position. Users now hold shares of the Yes Outcome in that Market. If the Market resolves Yes, they can Claim their winnings."

## Flagged Ambiguities

- "market" was used in the old codebase to mean what is now an **Event**. In the new codebase, **Market** specifically means a single binary question within an **Event**.
- "outcome" was used in the old codebase to mean what is now a **Market**. In the new codebase, **Outcome** specifically means one side of a **Market**.
- "cash out" is ambiguous. It could mean **Withdraw**, moving USDC back to the wallet, or selling a **Position**. Use the specific term.
- "balance" is ambiguous without context. Always qualify as "prediction market **Balance**", funds in the proxy wallet, versus "wallet balance", the main MetaMask wallet.
- "provider" can mean the platform or the code module. Use **Provider** for the platform and **Adapter** for the code module.

## Provider Terminology Mapping

| Canonical Term | Polymarket Term | Kalshi Term |
| :------------- | :---------------------- | :------------------- |
| Event | Event | Event |
| Market | Market / Condition | Market / Contract |
| Outcome | Outcome token | Yes/No contract |
| Position | Position | Position |
| Order | Order | Order |
| Proxy Wallet | Polymarket proxy (Safe) | N/A (direct trading) |
Loading
Loading