MarketMind

MarketMind is a market intelligence and paper-trading platform that combines live market data, ML-assisted analysis, and a web-based research workflow for equities and related asset classes.

Overview

MarketMind brings together market data, forecasting, evaluation, and portfolio simulation in a single codebase. The application includes a React frontend for interactive workflows and a Flask backend that handles market data retrieval, analytics, model execution, evaluation, and authenticated user state.

Core Capabilities

• Search equities and review price charts, quote data, and recent market context.
• Generate stock predictions and evaluate model behavior through rolling backtests.
• Review company fundamentals, filings, and screener-style market views.
• Manage paper-trading portfolios, watchlists, and alert workflows.
• Explore macro indicators, forex, cryptocurrency, and commodities data.
• Browse and simulate positions in supported prediction markets.

Architecture

MarketMind is structured as a browser-based frontend backed by a single Flask service. The frontend lives in frontend/ and is organized around page-level React components for dashboard, search, predictions, evaluation, fundamentals, paper trading, news, macro data, and related workflows. frontend/src/App.js acts as the page switchboard, while frontend/src/config/api.js centralizes backend endpoint construction so the UI uses a single API boundary.

Each large page is a thin orchestrator that owns its data-fetching and state, and delegates presentation to focused subcomponents grouped in a per-page folder under frontend/src/components/: landing/, getting-started/, search/, fundamentals/, paper/, marketmind-ai/, and prediction-markets/ each hold the cards, panels, and formatters for their page. Cross-page building blocks live in components/ui/ and components/charts/. Shared application concerns sit alongside the components: navigation and theme state in frontend/src/context/ (NavigationContext, DarkModeContext), reusable data-fetching in frontend/src/hooks/ (useApiData), static content in frontend/src/data/, and API/auth configuration in frontend/src/config/.

Authentication is handled with Clerk on the frontend and verified on the backend. The frontend installs a fetch interceptor through frontend/src/config/authFetch.js and frontend/src/components/AuthFetchBridge.js. That layer normalizes backend URLs, adds bearer tokens for authenticated requests, and retries once on 401 responses with a refreshed token. On the backend, backend/api_auth.py validates Clerk tokens and backend/authz.py gates user-specific capabilities. A development-only local identity follows the same authorization path without requiring Clerk.

The backend uses backend/api.py as its Flask composition root and route registry. Request lifecycle behavior lives in backend/api_runtime.py, input models live in backend/request_contracts.py, and feature logic is delegated to handler and service modules. Forecasting is split across backend/prediction_service.py and backend/models.py, while backend/professional_evaluation.py owns rolling backtests and backend/prediction_markets_fetcher.py owns prediction-market provider access.

At runtime, the Flask service sits between the frontend and several external providers. Market and historical pricing data primarily come from yfinance, with Alpha Vantage used for selected data workflows and fallback behavior. News retrieval uses Finnhub, and some fundamentals, filings, screener, and macro functionality can use optional OpenBB integrations where available. This makes the backend the single integration layer for third-party services, rather than having the frontend call providers directly.

Local development can store user state in lock-protected JSON files under backend/user_data/. Production refuses to start unless PERSISTENCE_MODE=postgres and DATABASE_URL points to PostgreSQL, preventing accidental ephemeral storage.

The high-level request path looks like this:

+--------------------+       HTTPS / fetch       +-------------------------+
| React frontend     | -----------------------> | Flask API               |
| frontend/src/*     |                          | backend/api.py          |
+--------------------+                          +-------------------------+
          |                                                |
          | Clerk auth UI                                  | Route handlers
          v                                                v
+--------------------+                          +-------------------------+
| Clerk session      |                          | Domain modules          |
| token retrieval    |                          | data_fetcher.py         |
+--------------------+                          | prediction_service.py   |
          |                                     | professional_evaluation |
          | Bearer token via                    | prediction_markets_*    |
          | authFetch interceptor               | prediction_markets_*    |
          v                                     +-------------------------+
+--------------------+                                      |
| Authenticated API  |                                      |
| requests           |                                      v
+--------------------+                          +-------------------------+
                                                  | External providers     |
                                                  | yfinance               |
                                                  | Finnhub               |
                                                  | Alpha Vantage         |
                                                  | OpenBB (optional)     |
                                                  +-------------------------+
                                                              |
                                                              v
                                                  +-------------------------+
                                                  | User-state persistence  |
                                                  | PostgreSQL (production) |
                                                  | JSON (local development)|
                                                  +-------------------------+

In practice, this means the frontend is primarily responsible for navigation, presentation, and authenticated request initiation, while the backend owns business logic, data-provider integration, model execution, portfolio state transitions, and persistence.

Repository Structure

MarketMind/
|-- backend/
|   |-- api.py
|   |-- api_runtime.py
|   |-- request_contracts.py
|   |-- alert_worker.py
|   |-- data_fetcher.py
|   |-- professional_evaluation.py
|   |-- prediction_markets_fetcher.py
|   |-- requirements.txt
|   `-- tests/
|-- docs/
|   |-- README.md
|   |-- backend/
|   |-- operations/
|   `-- product/
|-- frontend/
|   |-- package.json
|   |-- src/
|   |   |-- App.js
|   |   |-- components/            # page components + per-page subfolders
|   |   |   |-- landing/
|   |   |   |-- getting-started/
|   |   |   |-- search/
|   |   |   |-- fundamentals/
|   |   |   |-- paper/
|   |   |   |-- marketmind-ai/
|   |   |   |-- prediction-markets/
|   |   |   |-- charts/            # shared chart components
|   |   |   `-- ui/               # shared UI building blocks
|   |   |-- context/              # NavigationContext, DarkModeContext
|   |   |-- hooks/                # useApiData and other shared hooks
|   |   |-- data/                 # static content
|   |   |-- config/api.js
|   |   `-- config/authFetch.js
|   `-- public/
|-- .env.example
`-- README.md

Local Development

MarketMind is developed as two local processes: the Flask backend on port 5001 and the React frontend on port 3000.

1. Copy the example environment files and fill in the required values.

cp .env.example .env
cp frontend/.env.example frontend/.env

For Clerk-backed development, keep AUTH_MODE=clerk and configure the Clerk values in both environment files. For a self-contained local workspace, set matching development-only modes and tokens:

# .env
FLASK_ENV=development
AUTH_MODE=local
LOCAL_AUTH_USER_ID=local_development_user
LOCAL_AUTH_TOKEN=marketmind-local-development

# frontend/.env
VITE_AUTH_MODE=local
VITE_LOCAL_AUTH_USER_ID=local_development_user
VITE_LOCAL_AUTH_TOKEN=marketmind-local-development

Local mode creates one non-admin development identity and still enforces the backend's normal capability checks. The backend rejects local mode when FLASK_ENV=production.

2. Set up and start the backend.

cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python3 api.py

On macOS, XGBoost may require libomp:

brew install libomp

You can also start the backend with the helper script:

cd backend
./start_backend.sh

3. Set up and start the frontend.

cd frontend
npm install
npm start

When both processes are running, the frontend is available at http://localhost:3000 and the backend API is available at http://localhost:5001.

For Developers

If you are new to the repository, the fastest way to get oriented is to follow one feature from the UI to the backend. A good starting point is the search or predictions flow.

• Start with frontend/src/App.js to see how the main pages are wired together.
• Review frontend/src/config/api.js to understand how the frontend addresses backend routes.
• Review frontend/src/config/authFetch.js and frontend/src/components/AuthFetchBridge.js to understand how authenticated requests are sent.
• Use backend/api.py as the backend entrypoint for most feature work, since many routes and orchestration paths are defined there.
• For prediction and evaluation logic, read backend/professional_evaluation.py, backend/prediction_service.py, and backend/models.py.

Common development workflow:

1. Run the backend and frontend locally.
2. Pick a single page or endpoint and trace the full request path.
3. When changing a backend-powered feature, update the Flask route or supporting module first, then update the frontend API config, then update the consuming component.
4. When changing authenticated features, verify both Clerk-based auth behavior and user-specific persistence under backend/user_data/.

Useful local checks:

• Frontend checks: bash frontend/run_frontend_checks.sh
• Frontend browser journeys: cd frontend && npm run test:e2e
• Backend deterministic checks: PYTHON_BIN=backend/.venv/bin/python bash backend/run_deterministic_backend_checks.sh

Beginner-friendly tips:

• The frontend should call the Flask API, not third-party market providers directly.
• Hosted authentication requires Clerk configuration in both processes; local development can use the matching local auth settings shown above.
• On macOS, XGBoost-related backend issues are often caused by a missing libomp installation.
• If you are unsure where logic lives, search backend/api.py first and then follow imports into supporting modules.

Configuration

The root .env.example and frontend/.env.example files define the expected local configuration. Important values include:

• ALPHA_VANTAGE_API_KEY for market and reference data integrations.
• NEWS_API_KEY for news-related backend integrations where configured.
• FINNHUB_API_KEY for market news retrieval.
• FLASK_SECRET_KEY for backend session and security configuration.
• CORS_ORIGINS for allowed frontend origins in production-style deployments.
• CLERK_JWKS_URL for backend Clerk token verification when needed.
• CLERK_AUDIENCE for optional Clerk audience validation.
• AUTH_MODE for selecting clerk or development-only local authentication.
• LOCAL_AUTH_USER_ID and LOCAL_AUTH_TOKEN for the isolated local development identity.
• VITE_API_URL for the frontend's backend base URL.
• VITE_AUTH_MODE and matching local identity values for frontend local mode.
• VITE_CLERK_PUBLISHABLE_KEY for frontend Clerk initialization.

Keep local secrets out of version control and review provider-specific setup before deploying outside local development.

Additional Documentation

• Docs index
• API documentation
• Model data specifications
• Quality gates
• Release smoke checklist
• Monthly user journey simulation
• Production deployment checklist
• Production roadmap
• Code of conduct
• License

License

This project is licensed under the MIT License. See LICENSE for details.

Disclaimer

MarketMind is intended for research, education, and product development purposes. Forecasts, market signals, and simulated trading results should not be treated as investment advice or as guarantees of future performance.