Social Forecasting & DeFi Liquidity dApp
Users submit price predictions and are ranked by how close they were, not merely whether they were right — which means scoring is a continuous distance calculation rather than a binary settlement. That difference drives the architecture: prediction monitoring, resolution, scoring, dashboard aggregation and notification state each run as their own worker module, and reward distribution is a whole separate deployable so a heavy payout run can never block the API.
Backend monorepo (API, chain listener, reward engine, socket gateway) plus separate public and admin web clients and a contract repository
Documented as an architecture record. The interesting parts are the worker decomposition and the scoring model, neither of which needs a live deployment to explain.
The life of a prediction
Each stage below is a distinct worker module. Watch how the work moves off the API and into the worker plane as soon as the user is done interacting.
Prediction submission, leaderboards, pools and staking, fully internationalised.
From a user's guess to a recorded, staked position.
Highlights
One API, three specialised worker planes
The lifecycle of a prediction is long: submitted, monitored, resolved, scored, rewarded, announced. Rather than run that as one cron job, each stage is its own module with its own state, so a failure in scoring does not stall monitoring and a slow payout does not stall anything.
Public client
Prediction submission, leaderboards, pools, staking surfaces and account management.
- Locale-scoped routing with full internationalisation.
- Six wallet connection paths behind one unified session model.
- Charts and dashboards read from pre-aggregated endpoints, not raw history.
Application API
Predictions, pools, staking, rewards, identity, permissions, media and public metadata.
- Modular NestJS layout with one module per bounded context.
- Owns validation and eligibility; the chain holds custody and settlement.
- Emits events for the socket gateway rather than managing connections itself.
Chain listener
Eleven worker modules covering monitoring, resolution, submission updates, pool updates and notification state.
- Separate modules for detecting an outcome, resolving it and updating submissions.
- Dashboard rollups are maintained here, off the request path.
- Notification state machines track what has been delivered rather than assuming success.
Reward engine
Its own deployable, dedicated to computing and distributing winnings.
- Isolated so a large payout batch cannot degrade the API.
- Reads scored results and writes allocations as auditable records.
Contracts and liquidity
On-chain custody, liquidity provisioning and treasury operations.
- Solidity contract suite deployed through a scripted, reproducible pipeline.
- AMM integration for liquidity provisioning alongside the forecasting game.
- Treasury actions run through a multisig with explicit nonce management.
Modules across both runtimes
The API owns request-path concerns; the listener owns everything asynchronous. Note that the prediction lifecycle is split into separate worker modules rather than one scheduled job. 42 units across 6 groups.
Forecasting domain
7Listener workers
10Value & liquidity
7Identity & access
5Messaging
3Content & platform
10Stack by layer
Delivered work
Client surfaces
- Prediction submission, leaderboards, pools and staking flows.
- Six wallet connection paths unified behind one session model.
- Internationalised routing with locale-scoped pages.
- Chart-driven dashboards reading from pre-aggregated endpoints.
Services and workers
- Modular API covering predictions, pools, staking, rewards, identity and permissions.
- Chain listener decomposed into eleven single-purpose worker modules.
- Reward engine split out as an independent deployable.
- Socket gateway for live leaderboard and notification delivery.
On-chain and treasury
- Solidity contract suite with a scripted, reproducible deployment pipeline.
- AMM liquidity provisioning integrated alongside the forecasting mechanics.
- Multisig treasury operations with explicit nonce handling.
- Airdrop and allocation records tracked as first-class data.
Modules and demo strategy
Distance scoring
Ranks forecasts by how close they landed.
- Continuous scoring rather than binary win/lose.
- Drives both the leaderboard and the reward split.
Worker decomposition
One module per lifecycle stage.
- Monitoring, resolution, submission updates, rollups and notification state are all separate.
- A stall in one stage leaves the others running.
Reward engine
Computes and distributes winnings in isolation.
- Its own deployable, with allocation records written before transfers.
- Reconciliation makes partial batches visible.
Notification state machines
Tracks what was actually delivered.
- Per-entity delivery state instead of fire-and-forget.
- Makes redelivery safe and duplicate sends detectable.