| --- |
| title: PraxaLing |
| emoji: 🦜 |
| colorFrom: yellow |
| colorTo: gray |
| sdk: docker |
| app_port: 7860 |
| pinned: false |
| hf_oauth: true |
| hf_oauth_scopes: |
| - email |
| - inference-api |
| --- |
| |
| # PraxaLing |
|
|
| Learn languages through short stories and the world around you, powered by HuggingFace for identity and inference. |
|
|
| Two clients, one backend: |
| - **Web** — Next.js 16 App Router (also acts as the shared API). |
| - **Mobile** — Flutter (latest stable), calls the same HTTP endpoints. |
|
|
| Three flows: |
| 1. **Sign in with HuggingFace** (OAuth). |
| 2. **Practice** — read short stories matched to your CEFR level and target language; tap any word for a translation. Generate new stories on demand. |
| 3. **Camera** — take or upload a photo; the backend runs BLIP captioning, DETR detection, NLLB translation, and Mistral-generated example sentences. |
|
|
| ## Stack |
|
|
| | Concern | Tech | |
| |---|---| |
| | Web | Next.js 16.2 · React 19 · Tailwind v4 · Turbopack | |
| | Mobile | Flutter 3.41 · Riverpod · go_router · dio | |
| | Auth | HuggingFace OAuth (`arctic`) · JWT (`jose`) | |
| | DB | Postgres · Drizzle ORM | |
| | Storage | Vercel Blob (optional) | |
| | Inference | `@huggingface/inference` · Mistral-7B-Instruct · BLIP · DETR · NLLB-200 | |
| |
| ## Getting started (web) |
| |
| ```bash |
| # 1. Install deps |
| npm install |
| |
| # 2. Bring up Postgres |
| docker compose up -d |
| |
| # 3. Configure env — copy and fill in |
| cp .env.example .env.local |
| |
| # 4. Apply schema |
| npm run db:push |
| |
| # 5. (Optional) seed stories |
| npm run db:seed |
| |
| # 6. Run dev server |
| npm run dev |
| ``` |
| |
| Required env: |
| - `AUTH_SECRET` — any 32+ char random string (`openssl rand -base64 32`) |
| - `HF_OAUTH_CLIENT_ID` / `HF_OAUTH_CLIENT_SECRET` — from https://huggingface.co/settings/applications/new, or use the Space metadata `hf_oauth: true` and the app will read Hugging Face's injected `OAUTH_CLIENT_ID` / `OAUTH_CLIENT_SECRET` |
| - `HF_TOKEN` — read token from https://huggingface.co/settings/tokens |
| - Optional: `BLOB_READ_WRITE_TOKEN` for Vercel Blob |
|
|
| Redirect URIs to register on the HF OAuth app: |
| - `http://localhost:3000/api/auth/callback/huggingface` |
| - `http://localhost:3000/api/auth/callback/huggingface?client=mobile` |
| - `https://<SPACE_HOST>/api/auth/callback/huggingface` |
| - `https://<SPACE_HOST>/api/auth/callback/huggingface?client=mobile` |
|
|
| For the hosted Space, use the direct `*.hf.space` host, not the `huggingface.co/spaces/...` page, for redirect URIs and mobile `API_BASE_URL`. |
|
|
| ## Getting started (mobile) |
|
|
| ```bash |
| cd mobile |
| flutter pub get |
| |
| # iOS simulator — host loopback is 127.0.0.1 by default |
| flutter run --dart-define=API_BASE_URL=http://127.0.0.1:3000 |
| |
| # Android emulator — host loopback is 10.0.2.2 (default) |
| flutter run |
| |
| # Hosted backend / physical device |
| flutter run --dart-define=API_BASE_URL=https://<SPACE_HOST> |
| ``` |
|
|
| See `docs/API.md` for the endpoints the app consumes. |
|
|
| ## Architecture notes |
|
|
| - **Auth**: both clients exchange an HF OAuth code for our own short-lived JWT. Web stores it in an httpOnly cookie; mobile in `flutter_secure_storage`. `lib/auth/session.ts#getSession()` handles both. |
| - **Next.js 16 specifics**: `middleware.ts` is now `proxy.ts`; dynamic APIs (`cookies`, `headers`, `params`) are async; Turbopack is default. See `node_modules/next/dist/docs/01-app/02-guides/upgrading/version-16.md`. |
| - **Data flow for camera**: multipart → BLIP + DETR in parallel → dedupe labels → translate each to target lang → Mistral generates 3 sentences keyed on caption + objects → persisted in `vision_jobs`. |
|
|
| ## Scripts |
|
|
| | Command | Purpose | |
| |---|---| |
| | `npm run dev` | Next.js dev server | |
| | `npm run build` | Production build | |
| | `npm run db:push` | Apply schema to Postgres | |
| | `npm run db:generate` | Generate migration from schema | |
| | `npm run db:migrate` | Apply pending migrations | |
| | `npm run db:seed` | Insert hand-curated stories | |
| | `npm run db:studio` | Drizzle Studio UI | |
|
|
