WaySightAI

WaySightAI is a privacy-first time-series forecasting app. The browser parses uploaded CSV files, runs preprocessing and forecasting through a Rust/WebAssembly engine, and renders the workflow in a React/Vite UI. The FastAPI backend handles authentication, saved project metadata, feedback, usage limits, and AI-agent endpoints; raw uploaded time-series rows are intended to stay in the browser.

Why It's Fun to Build With

• ⚡ Fast feedback loop: Upload a CSV and iterate on forecasts quickly in-browser.
• 🔒 Privacy-first by design: Raw time-series rows are intended to remain local to the browser.
• 🧠 Dual workflow modes: AI Agent Mode for guided forecasting and Expert Mode for hands-on control.
• 🦀 Rust + WASM core: Heavy lifting runs in a compiled forecasting engine for deterministic performance.
• 🧩 Full-stack extensibility: React frontend, FastAPI backend, and clear package boundaries for contributors.

What Is In This Repo

packages/
  web/        React 18 + TypeScript + Vite app
  wasm/       Rust forecasting engine compiled with wasm-pack
  api/        FastAPI backend with SQLAlchemy, Alembic, Clerk, Redis, Stripe hooks
scripts/      Build helper scripts
tests/data/   CSV fixtures used by tests and manual smoke checks
tests/web/    Playwright smoke test for the rendered app

The main forecasting path is:

1. Upload a CSV in the web app.
2. Select date and target columns during data review.
3. Choose AI Agent Mode or Expert Mode.
4. Run a browser-local forecast through packages/wasm.
5. Optionally call the API for account, project, feedback, usage, and agent features.

Prerequisites

• Node.js 18+ and npm 9+
• Rust plus wasm32-unknown-unknown
• wasm-pack
• Python 3.11+
• uv for the API development environment
• PostgreSQL and Redis for a full backend run

Install

npm install
cd packages/api
uv sync --extra dev

If this is a fresh Rust setup:

rustup target add wasm32-unknown-unknown
cargo install wasm-pack

Run Locally

Build the WASM package first, then start the web app:

npm run build:wasm
npm run dev -w @waysightai/web -- --host 127.0.0.1 --port 3000

The app runs at http://127.0.0.1:3000.

To run the API:

cd packages/api
cp .env.example .env
uv run alembic upgrade head
uv run uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

Set VITE_API_URL in packages/web/.env if the frontend should call a non-default API URL.

Environment

Frontend variables live in packages/web/.env.example.

Important frontend keys:

• VITE_API_URL
• VITE_CLERK_PUBLISHABLE_KEY
• VITE_POSTHOG_API_KEY
• VITE_ENABLE_AI_AGENT
• VITE_ENABLE_PROJECT_SAVE

Backend variables live in packages/api/.env.example. Never commit real secrets (especially provider API keys); use placeholders in all checked-in env files.

Important backend keys:

• DATABASE_URL
• REDIS_URL
• CLERK_SECRET_KEY
• CLERK_JWT_VERIFICATION_KEY
• ANTHROPIC_API_KEY
• GOOGLE_API_KEY
• STRIPE_SECRET_KEY

Commands

npm run build              # Build WASM, then build the web package
npm run build:wasm         # Compile packages/wasm into ./pkg
npm run test               # WASM node compile test, web unit tests, API tests
npm run test:web:unit      # Vitest unit/component tests
npm run test:web           # Playwright rendered smoke test
npm run test:api           # FastAPI pytest suite
npm run test:wasm          # wasm-pack test --node
npm run lint               # Turbo lint pipeline
npm run format:check       # Prettier check

Package-level commands:

npm run test:run -w @waysightai/web
cd packages/api && uv run --extra dev pytest -s
cd packages/wasm && wasm-pack test --node

Current Verification Status

The current checked workflow is:

• Production web build via npm run build.
• Web unit/component tests via npm run test:run -w @waysightai/web.
• API tests via cd packages/api && uv run --extra dev pytest -s.
• WASM node compile/test path via cd packages/wasm && wasm-pack test --node.
• Rendered app smoke through Playwright in tests/web/app-smoke.spec.ts.

wasm-pack test --node currently compiles the WASM target but reports no wasm-bindgen tests to run. The Rust crate also has native unit tests, but some integration paths use wasm_bindgen::JsValue and should be exercised through the WASM toolchain rather than plain native cargo test.

Notes For Maintainers

• The generated WASM package is written to the repo-level pkg/ directory and is ignored by git.
• packages/api/tests/conftest.py uses an in-memory SQLite database and overrides auth dependencies for endpoint tests.
• New users receive trial agent queries; /api/user/usage reports those trial queries in queries_remaining.
• Keep docs close to the code. This README is now the source of truth for setup, test, and run instructions.