How mental-wealth-academy/platform works
1. High-level shape
This repository is a multi-surface product platform built around a Next.js 14 app, a Solidity/Base mainnet protocol, and two auxiliary backends: a Node/TypeScript “blue-server” and a Python “simulation-backend.” The architecture is not a single app so much as a front-end shell plus several domain services coordinated through API routes, database tables, and onchain contracts.
2. Primary user interface
The app/ directory is the main user-facing surface. It uses the Next.js App Router for routes like home, courses, quests, profile, research, simulation, trades, chat, and admin. Most pages are thin route wrappers that assemble feature components from components/, while the top-level shell is composed through shared layout/navigation components.
3. Server boundary inside Next.js
The app/api/ tree is the primary backend boundary for the frontend. It exposes a large set of route handlers for authentication, course generation, quests, membership, treasury/trading, surveys, uploads, notifications, and agent operations. These routes are where browser actions become server-side mutations, validations, webhooks, and third-party service calls.
4. Domain partitioning in the frontend
The UI is organized by product domain rather than by technical layer: courses, quests, Blue/agent interactions, community/chat, treasury/trades, research, simulation, surveys, and membership. Reusable UI primitives live in components/, while domain-specific panels and modals are grouped by feature. This suggests the app is designed as a portal with many independently activated workflows.
5. Identity, auth, and account linking
Authentication is multi-channel: wallet signup, Farcaster sign-in, X/Twitter auth, Telegram verification, and account-linking/status flows all exist as first-class routes. lib/auth.ts, lib/wallet-auth.ts, lib/privy-auth.ts, and related helpers indicate a centralized identity layer that federates social identities, wallets, and academy accounts into one user record.
6. Content, learning, and progress system
Courses are a major subsystem with both consumption and authoring paths. The app includes course pages, personal/draft/generate/intake/progress APIs, VIP course management, content access gates, quizzes, and a course studio/builder UI. Data access is backed by dedicated helpers such as lib/course-content-db.ts, lib/vip-course-db.ts, lib/personal-course-db.ts, and schema-ensuring scripts, so course state is persisted server-side rather than being purely static content.
7. Quests, rewards, and community loops
Quests form the gamification core: users submit proofs, review USDC-backed quests, complete Twitter-linked tasks, forge quests, and track progress. Reward surfaces include diamonds, shards, loot boxes, leaderboard, shop purchases, and seasonal/progression features. This subsystem spans UI, database state, and server routes, implying a loop of action → verification/review → reward issuance → user progress update.
8. Blue/agent intelligence layer
The Blue persona and agent workflows are a distinct subsystem with chat, memory, field notes, reminders, daemon control, API keys/tokens, and “blue” calling/chat overlays. lib/blue-* modules cover knowledge, memory, RAG embeddings/graph/index, membership, wallet, and contract interactions. The blue-server/ service is a separate Node process that likely handles real-time agent behavior and data persistence beyond the Next.js request/response cycle.
9. Blockchain, treasury, and markets
Onchain functionality is central, not incidental. The repo includes contracts/ for Solidity/Fable/Foundry, Base mainnet deployment docs, and helpers for a diamond proxy and wallet contract. Treasury routes and libraries cover prices, balance, trade execution, distributions, Kalshi integration, and market debate, so the system bridges UI actions to both onchain contracts and offchain market APIs/workflows.
10. Simulation and research environments
The simulation stack is split into a Next.js UI (app/simulation/) and a separate Python backend in simulation-backend/. The Python service handles graph building, report generation, simulation configuration, runner/orchestration, substack integration, and Zep graph/memory tooling. The frontend simulation steps guide users through graph creation, environment setup, execution, reporting, and interaction, so the runtime boundary is clear: UI orchestration in Next.js, heavy compute/agent simulation in Python.
11. Data persistence and schema management
The repo uses database-first infrastructure with many schema-bootstrapping helpers (lib/ensure*Schema.ts) and SQL migration files under db/. The presence of Supabase utilities and storage helpers suggests Postgres-backed persistence with managed auth/storage and row-level security. This database layer is the shared state backbone for users, courses, quests, memberships, proposals, events, and agent memory.
12. External services and integration points
The architecture depends on several external systems that materially shape the design: Supabase/Postgres, Base mainnet, Stripe, Kalshi, Neynar/Farcaster, X auth, Telegram, IPFS/storage uploads, and email/webhook providers. These are surfaced through route handlers and lib/* adapters rather than being called directly from UI components, which keeps the integration boundary centralized.
13. Operational and deployment structure
Deployment is split across web app, contracts, and backends. vercel.json and the Next.js app indicate the main product is web-deployed; contracts/ includes Foundry deployment and verification tooling; blue-server/ and simulation-backend/ each have Dockerfiles and standalone configs for local/dev/prod execution. The repo also includes scripts for seeding, validation, snapshots, and operational checks, indicating a system that mixes interactive product features with protocol and data ops.
14. How to draw the architecture
A good diagram should show: users/browser → Next.js UI → Next.js API routes → shared lib/ service layer → Supabase/Postgres, onchain contracts/Base, and external services; plus separate arrows from the UI to blue-server and simulation-backend for agent/simulation workflows. The major bounded contexts are identity, content/learning, quests/rewards, Blue/agents, treasury/trading, and simulation/research.
Main entry points: api API routes · app App shell · lib Shared lib · contracts Contracts
Components 19
Next.js app
User-facing portal, routes, and shared UI components
- App shell · Main App Router surface and shared layout/navigation
app - Feature UI · Reusable domain-specific panels, modals, and page building blocks
components - Courses · Course content, intake, progress, VIP publishing, and studio workflows
app/course - Quests · Quest creation, proof submission, review, progress, and rewards
app/quests - Blue agent · Blue chat, memory, reminders, daemon control, and agent overlays
app/agents - Treasury · Balances, prices, trade execution, distributions, and market integrations
app/trades - Research · Research activation and related content/analysis surfaces
app/research - Surveys · Survey processing, quiz flows, and certificate minting
app/surveys
Server and data
API routes, shared libraries, and persistence layer
- API routes · Next.js backend boundary for auth, content, quests, treasury, surveys, and agents
app/api - Shared lib · Centralized helpers for auth, db access, course/quest logic, Blue, treasury, and integrations
lib - Database schema · SQL migrations and schema bootstrapping for persistent product state
db - External systems · Supabase, Stripe, Farcaster/Neynar, X, Telegram, Kalshi, storage, and email/webhooks
- Identity · Wallet, social sign-in, account linking, and user profile resolution
- Membership · Subscription, crypto confirmation, and membership status workflows
Blue and simulation
Auxiliary services for agent behavior and simulation
- Blue server · Separate Node process for Blue agent behavior, memory, and real-time workflows
blue-server - Simulation UI · Frontend orchestration for graph build, environment setup, simulation, reporting, and interaction
app/simulation - Simulation backend · Standalone Python runtime for graphing, simulation execution, reporting, and memory tooling
simulation-backend
Onchain protocol
Solidity contracts and deployment tooling
- Contracts · Foundry-based onchain contracts and deployment/verification tooling
contracts
Other components
- Browser · End users interacting with the product surface
Connections 22
- Browser → App shell: uses · Users navigate the portal through the Next.js app
- App shell → Feature UI: assembles · Pages compose shared and domain-specific components
- App shell → API routes: calls · Routes and actions reach server handlers
- API routes → Shared lib: delegates to · Handlers rely on shared business and integration helpers
- Shared lib → Database schema: persists to · Core logic reads and writes PostgreSQL-backed state
- Shared lib → External systems: integrates with · Adapters coordinate third-party APIs and storage
- API routes → Identity: implements · Auth, linking, and profile routes form the identity boundary
- API routes → Courses: supports · Course generation, access, progress, and authoring workflows
- API routes → Quests: supports · Proofs, reviews, completion, and reward issuance
- API routes → Blue agent: supports · Agent chat, memory, reminders, keys, and daemon ops
- API routes → Treasury: supports · Balances, pricing, trade execution, and market actions
- API routes → Membership: supports · Subscription and crypto confirmation flows
- API routes → Surveys: supports · Survey processing and certificate minting
- API routes → Research: supports · Research activation and analysis flows
- Blue agent → Blue server: extends into · Front-end agent experiences connect to the standalone Blue runtime
- Simulation UI → Simulation backend: orchestrates · UI steps proxy work to the Python simulation service
- Simulation backend → Database schema: reads/writes · Simulation state and outputs are stored alongside product data
- Contracts → External systems: deploys via · Onchain work depends on chain RPCs, wallets, and verification services
- Treasury → Contracts: executes onchain · Treasury actions bridge into protocol contracts and Base mainnet
- Quests → Contracts: mints/settles · Rewards and proof workflows connect to onchain assets and payouts
- Membership → External systems: billing · Membership flows depend on payments and verification providers
- Blue server → External systems: calls · Blue runtime likely reaches APIs and storage outside the app boundary