# mental-wealth-academy/platform architecture

> Architecture diagram of the GitHub repository mental-wealth-academy/platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mental-wealth-academy/platform
- Repository: https://github.com/mental-wealth-academy/platform

## Overview

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: [`app/api`](https://github.com/mental-wealth-academy/platform/tree/main/app/api) (API routes), [`app`](https://github.com/mental-wealth-academy/platform/tree/main/app) (App shell), [`lib`](https://github.com/mental-wealth-academy/platform/tree/main/lib) (Shared lib), [`contracts`](https://github.com/mental-wealth-academy/platform/tree/main/contracts) (Contracts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Next.js app"]
  node_app_shell["App shell<br/>Next.js routes"]
  node_feature_ui["Feature UI<br/>domain components"]
  node_learning["Courses<br/>learning system"]
  node_quests["Quests<br/>reward loop"]
  node_blue["Blue agent<br/>assistant workflow"]
  node_treasury["Treasury<br/>trading system"]
  node_research["Research<br/>analysis workflow"]
  node_surveys["Surveys<br/>assessment loop"]
end

subgraph group_backend["Server and data"]
  node_api_routes["API routes<br/>server handlers"]
  node_lib_core["Shared lib<br/>service layer"]
  node_db_schema[("Database schema<br/>Postgres schema")]
  node_external_services["External systems<br/>integrations"]
  node_identity["Identity<br/>auth layer"]
  node_membership["Membership<br/>billing flow"]
end

subgraph group_agents["Blue and simulation"]
  node_blue_server["Blue server<br/>Node agent service"]
  node_simulation_ui["Simulation UI<br/>Next.js workflow"]
  node_simulation_backend["Simulation backend<br/>Python service"]
end

subgraph group_protocol["Onchain protocol"]
  node_contracts["Contracts<br/>Solidity protocol"]
end

node_browser(("Browser<br/>user client"))

node_browser -->|"uses"| node_app_shell
node_app_shell -->|"assembles"| node_feature_ui
node_app_shell -->|"calls"| node_api_routes
node_api_routes -->|"delegates to"| node_lib_core
node_lib_core -->|"persists to"| node_db_schema
node_lib_core -->|"integrates with"| node_external_services
node_api_routes -->|"implements"| node_identity
node_api_routes -->|"supports"| node_learning
node_api_routes -->|"supports"| node_quests
node_api_routes -->|"supports"| node_blue
node_api_routes -->|"supports"| node_treasury
node_api_routes -->|"supports"| node_membership
node_api_routes -->|"supports"| node_surveys
node_api_routes -->|"supports"| node_research
node_blue -->|"extends into"| node_blue_server
node_simulation_ui -->|"orchestrates"| node_simulation_backend
node_simulation_backend -->|"reads/writes"| node_db_schema
node_contracts -->|"deploys via"| node_external_services
node_treasury -->|"executes onchain"| node_contracts
node_quests -->|"mints/settles"| node_contracts
node_membership -->|"billing"| node_external_services
node_blue_server -->|"calls"| node_external_services

click node_app_shell "https://github.com/mental-wealth-academy/platform/tree/main/app"
click node_feature_ui "https://github.com/mental-wealth-academy/platform/tree/main/components"
click node_api_routes "https://github.com/mental-wealth-academy/platform/tree/main/app/api"
click node_lib_core "https://github.com/mental-wealth-academy/platform/tree/main/lib"
click node_db_schema "https://github.com/mental-wealth-academy/platform/tree/main/db"
click node_blue_server "https://github.com/mental-wealth-academy/platform/tree/main/blue-server"
click node_simulation_ui "https://github.com/mental-wealth-academy/platform/tree/main/app/simulation"
click node_simulation_backend "https://github.com/mental-wealth-academy/platform/tree/main/simulation-backend"
click node_contracts "https://github.com/mental-wealth-academy/platform/tree/main/contracts"
click node_learning "https://github.com/mental-wealth-academy/platform/tree/main/app/course"
click node_quests "https://github.com/mental-wealth-academy/platform/tree/main/app/quests"
click node_blue "https://github.com/mental-wealth-academy/platform/tree/main/app/agents"
click node_treasury "https://github.com/mental-wealth-academy/platform/tree/main/app/trades"
click node_research "https://github.com/mental-wealth-academy/platform/tree/main/app/research"
click node_surveys "https://github.com/mental-wealth-academy/platform/tree/main/app/surveys"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_shell,node_feature_ui,node_learning,node_quests,node_blue,node_treasury,node_research,node_surveys toneBlue
class node_api_routes,node_lib_core,node_db_schema,node_external_services,node_identity,node_membership toneAmber
class node_blue_server,node_simulation_ui,node_simulation_backend toneMint
class node_contracts toneRose
class node_browser toneNeutral
```

## Components

### Next.js app

User-facing portal, routes, and shared UI components

- [App shell](https://github.com/mental-wealth-academy/platform/tree/main/app): Next.js routes · Main App Router surface and shared layout/navigation · `app`
- [Feature UI](https://github.com/mental-wealth-academy/platform/tree/main/components): domain components · Reusable domain-specific panels, modals, and page building blocks · `components`
- [Courses](https://github.com/mental-wealth-academy/platform/tree/main/app/course): learning system · Course content, intake, progress, VIP publishing, and studio workflows · `app/course`
- [Quests](https://github.com/mental-wealth-academy/platform/tree/main/app/quests): reward loop · Quest creation, proof submission, review, progress, and rewards · `app/quests`
- [Blue agent](https://github.com/mental-wealth-academy/platform/tree/main/app/agents): assistant workflow · Blue chat, memory, reminders, daemon control, and agent overlays · `app/agents`
- [Treasury](https://github.com/mental-wealth-academy/platform/tree/main/app/trades): trading system · Balances, prices, trade execution, distributions, and market integrations · `app/trades`
- [Research](https://github.com/mental-wealth-academy/platform/tree/main/app/research): analysis workflow · Research activation and related content/analysis surfaces · `app/research`
- [Surveys](https://github.com/mental-wealth-academy/platform/tree/main/app/surveys): assessment loop · Survey processing, quiz flows, and certificate minting · `app/surveys`

### Server and data

API routes, shared libraries, and persistence layer

- [API routes](https://github.com/mental-wealth-academy/platform/tree/main/app/api): server handlers · Next.js backend boundary for auth, content, quests, treasury, surveys, and agents · `app/api`
- [Shared lib](https://github.com/mental-wealth-academy/platform/tree/main/lib): service layer · Centralized helpers for auth, db access, course/quest logic, Blue, treasury, and integrations · `lib`
- [Database schema](https://github.com/mental-wealth-academy/platform/tree/main/db): Postgres schema · SQL migrations and schema bootstrapping for persistent product state · `db`
- **External systems**: integrations · Supabase, Stripe, Farcaster/Neynar, X, Telegram, Kalshi, storage, and email/webhooks
- **Identity**: auth layer · Wallet, social sign-in, account linking, and user profile resolution
- **Membership**: billing flow · Subscription, crypto confirmation, and membership status workflows

### Blue and simulation

Auxiliary services for agent behavior and simulation

- [Blue server](https://github.com/mental-wealth-academy/platform/tree/main/blue-server): Node agent service · Separate Node process for Blue agent behavior, memory, and real-time workflows · `blue-server`
- [Simulation UI](https://github.com/mental-wealth-academy/platform/tree/main/app/simulation): Next.js workflow · Frontend orchestration for graph build, environment setup, simulation, reporting, and interaction · `app/simulation`
- [Simulation backend](https://github.com/mental-wealth-academy/platform/tree/main/simulation-backend): Python service · Standalone Python runtime for graphing, simulation execution, reporting, and memory tooling · `simulation-backend`

### Onchain protocol

Solidity contracts and deployment tooling

- [Contracts](https://github.com/mental-wealth-academy/platform/tree/main/contracts): Solidity protocol · Foundry-based onchain contracts and deployment/verification tooling · `contracts`

### Other components

- **Browser**: user client · End users interacting with the product surface

## Connections

- 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
