Mohshoo

A tutor photographs a student's schoolwork. The system reads it, matches it against the official curriculum, keeps a canonical record of what that child has mastered, and writes human-readable notes about it. Everything else exists to make that chain reliable.

Documentation

• docs/architecture.md — how the system works: the narrative, the flows, the one-way facts invariant. Start here.
• docs/production.md — production access, infrastructure, deploy.
• TODO.md — outstanding engineering work.
• deploy/DEPLOYMENT.md — canonical deployment guide.

Quick Start (Development)

Run locally

# Install Node 24.11.1 (managed via mise or nvm)
# mise:   mise install node@24.11.1
# nvm:    nvm install 24.11.1

# Clone and setup
git clone https://github.com/ofrades/mohshoo.git
cd mohshoo

# Copy environment template
cp .env.example .env

# One-time setup: install deps + migrate
bun install
bun run setup

# Terminal 1: API server
bun run dev:server

# Terminal 2: Vite web client
bun run dev:web

# Terminal 3: Expo native client, when needed
bun run dev:client

• API: http://localhost:3333
• Vite web client: http://localhost:8082
• Expo dev server: http://localhost:8081

bun run dev:server runs the API by itself.

bun run dev:web runs the browser client by itself.

bun run dev:client runs the Expo native client by itself.

If you need to refresh local state, run bun run dev:reset to re-run the local database setup.

Local development runs directly on your machine (Node 24 + Expo) and uses SQLite at ./data/homeschool.sqlite.

The predev, prestart, and pretest scripts under apps/api/package.json invoke scripts/ensure-native-binding.sh to automatically rebuild better-sqlite3 whenever the active Node ABI differs from the cached native binding.

Analysis worker

Background analysis (file analysis → requirements → prose) runs in a separate worker process:

bun run dev:analysis-worker

See docs/architecture.md for what it does and docs/production.md for operator controls (bun run pipeline status|run|interrupt|resume).

Local Authentication

Local development now uses the same Google OAuth flow as other environments. Set up GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, PUBLIC_BASE_URL, and ALLOWED_RETURN_TO_ORIGINS, then sign in with your Google account from the app.

Local development starts from your migrated database and Google sign-in only.

Google OAuth Setup

1. Create OAuth credentials in Google Cloud Console.
2. Add redirect URI: https://your-domain/api/auth/google/callback
3. Configure .env:

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-secret
PUBLIC_BASE_URL=https://your-domain
ALLOWED_RETURN_TO_ORIGINS=http://localhost:8082,http://localhost:3333,http://localhost:8081,https://your-app-domain

Production Deployment

Production runs natively on Cloudflare Workers with D1 and R2 and is managed by Alchemy:

bunx alchemy plan --stage prod
bunx alchemy deploy --stage prod

Canonical operations guide: docs/production.md.

Project Structure

├── apps/
│   ├── api/          # Effect API server + analysis worker + SQL migrations
│   │   ├── index.ts
│   │   ├── db/
│   │   └── src/
│   └── web/          # Vite web client
├── packages/
│   ├── api-client/
│   ├── contracts/
│   └── rendering/
├── scripts/          # operator CLI (pipeline), seeds, maintenance runners
├── docs/             # architecture, pipeline internals, production, pilot e2e
├── infra/            # Cloudflare Worker, D1, and R2 resources
└── alchemy.run.ts    # production infrastructure stack

Tech Stack

• Runtime: Cloudflare Workers + Effect 4 (pinned 4.0.0-rc.111)
• Database: Cloudflare D1
• Object storage: Cloudflare R2
• Web client: Vite + React + shadcn-style DOM components (apps/web)
• Auth: Google OAuth with PKCE
• Hosting: Cloudflare Workers

License

MIT