Prerequisites: Node 22.x · pnpm · a Neon Postgres database

pnpm install
cp .env.example .env.local   # fill in the keys (see Environment below)

pnpm db:push                 # sync schema to Neon
pnpm seed                    # seed 108 lessons from content/*.md
pnpm dev                     # → http://localhost:3006  🎉

That's the full app — no separate backend server. Chat calls DeepSeek directly from the Next route (set DEEPSEEK_API_KEY); article / prep / flashcard / course-review generation are offline Rust bins (see AI generation).

graph TD
    Browser --> Next["Next.js on Vercel<br/>pages · API routes · server actions"]
    Next --> Adapter["data.ts adapter"]
    Adapter -->|"DATA_SOURCE=db"| DB[("Neon Postgres<br/>+ pgvector + checkpoints")]
    Adapter -->|"DATA_SOURCE=fs"| FS["content/*.md"]
    Next -->|"BACKEND_URL + bearer"| Rust["Rust knowledge-server :7860<br/>6 LangGraph graphs"]
    Rust --> DeepSeek["DeepSeek API"]
    Rust --> SQLite[("SQLite + LanceDB<br/>knowledge.db · courses.db")]
    Next --> R2["Cloudflare R2<br/>audio files"]
    Next --> D1["Cloudflare D1<br/>audio progress"]

Request paths: lesson pages read through data.ts (DB or filesystem) and pull related lessons via pgvector cosine similarity. Chat does FTS + vector retrieval in Next.js, then POSTs snippets + history to the Rust knowledge-server, which merges them with its own SQLite + LanceDB retrieval and calls DeepSeek (stateless — history is supplied by the caller).

• Content generation (article_generate) — research → outline → draft → review → revise, with a conditional revision loop (max 2) gated on word count, code blocks, cross-refs, ≥5 xyflow diagrams, and mandatory sections. Run via the gen-article Rust bin (pnpm generate:rust) or over /runs/wait.
• RAG chat (chat) — SQLite lexical + LanceDB vector retrieval merged with caller snippets → format context → one DeepSeek call.
• Course review (course_review) — 10 expert evaluators run concurrently, then a weighted aggregator computes score + verdict.

app/                  Next.js App Router (lessons, AWS hub, applications, coursework, problems, api/*)
components/           React components (search, audio-player, toc, …)
content/              Markdown lesson files
src/db/               Neon client + Drizzle schema (22 tables)
src/lib/              backend-client (typed POST /runs/wait)
lib/                  data.ts adapter, db queries, r2.ts, d1.ts, server actions
crates/ml/            Rust workspace — knowledge-server (6 graphs, gen-article,
                      seed-topic-courses), core (seed/export), audio-guide
scripts/              seed, scrape, review-courses, e2e
sql/ · migrations/    Neon setup + D1 migrations

pnpm dev                       # start on :3006
pnpm db:push / db:studio       # sync schema / open Drizzle Studio
pnpm seed / seed:courses       # seed lessons / Udemy catalog
pnpm scrape:udemy              # scrape AI/ML Udemy topics → external_courses

pnpm generate <slug>           # generate a lesson via LangGraph
pnpm generate:dry <slug>       # preview without saving
pnpm generate:batch            # generate all missing lessons
pnpm review:courses            # batch-review unreviewed courses

pnpm backend:rust              # run knowledge-server on :7860 (Rust)
pnpm backend:rust:index        # (re)build the LanceDB section index
pnpm generate:rust <args>      # gen-article bin (research→…→finalize)
pnpm seed:courses <args>       # seed-topic-courses bin → data/courses.db
pnpm audio:meta <args>         # markdown → AudioMeta JSON (deterministic)

pnpm backend:test              # cargo test (knowledge-server + audio-guide)
pnpm test:e2e                  # smoke the running server

There is no long-running backend server. Chat is a direct DeepSeek call in app/api/chat/route.ts (via lib/chat-llm.ts — 1:1 port of the old Rust chat prompt; needs DEEPSEEK_API_KEY in the Next env / Vercel). All other AI generation runs offline as one-shot aer-ml bins that write Neon / SQLite:

pnpm prep:loop -- --slug <slug>     # interview prep (deepseek agent → Neon)
pnpm prep:rust  / prep:owner:rust   # prep variants (static artifact / owner)
pnpm prep:memorize -- --slug <slug> # flashcards → concepts + applications row
pnpm review:courses [--dry-run]     # course_review → data/courses.db
pnpm generate:rust -- --slug <s>    # article generation

Env for the bins: DEEPSEEK_API_KEY (monorepo-root .env) and, for the ones that persist, DATABASE_URL (auto-exported by the npm scripts). Course data is scraped/reviewed into data/courses.db and surfaced to the frontend as JSON via pnpm export:content (Rust → data/content/*.json).

The application /prep page reads interviewQuestions from Neon. In prod that DB-backed path is dormant (no Rust backend is deployed; the public page falls back to the committed data/app-prep/<slug>.json seed). To regenerate real prep and push it into the row — which, since DATABASE_URL is the shared Neon, also updates the live owner view — one full-Rust command does generate → validate → persist:

pnpm prep:loop                 # ECB SSM Cockpit Developer (default slug)
pnpm prep:loop -- --slug <slug>            # another application
pnpm prep:loop -- --slug <slug> --no-db    # regenerate + validate only

prep:loop runs the gen-app-prep-loop Rust bin (crates/ml). It: (1) runs a deepseek agent in-process (deepseek::run, only the builtin Read/Write tools, AcceptEdits) that reads the job description from data/app-prep/<slug>.json and rewrites the artifact's prep fields; (2) validates the result in Rust — exactly 4 ## sections, techStack a JSON string whose every category ∈ app_prep::CATEGORIES, valid relevance; (3) connects to Neon over Postgres (sqlx) and updates the applications row (interviewQuestions/techStack, plus jobDescription backfill if the row had none), then reads back to confirm. It mutates the live row — not a dry run; the agent step and the validation gate must both pass first, so Neon is untouched on failure.

The npm script exports DEEPSEEK_API_KEY from the monorepo-root /Users/vadimnicolai/Public/ai-apps/.env and DATABASE_URL from .env.local (the Rust process does not load .env*); >1 rows for a slug → --user-id <id>. (prep:rust — the gen-app-prep bin, static artifact only — and backend:rust:local remain valid alternatives. pnpm test:app-prep still exists as the seed-loader / public-render contract test.)

DATABASE_URL=             # Neon connection string
OPENAI_API_KEY=
DEEPSEEK_API_KEY=         # required by the Next runtime for /api/chat + the AI bins
NEXT_PUBLIC_DATA_SOURCE=  # "db" | "fs"
NEXT_PUBLIC_R2_DOMAIN=    # audio CDN domain
R2_ACCOUNT_ID= R2_ACCESS_KEY_ID= R2_SECRET_ACCESS_KEY= R2_BUCKET_NAME=
CLOUDFLARE_ACCOUNT_ID= CLOUDFLARE_AUDIO_D1_ID= CLOUDFLARE_D1=