Skip to content

feat: rebuild the web app on Next.js + FastAPI (0.3.0) - #16

Merged
Li-Evan merged 1 commit into
mainfrom
feat/web-app-0.3.0
Nov 13, 2026
Merged

Li-Evan merged 1 commit into
mainfrom
feat/web-app-0.3.0

Conversation

@Li-Evan

@Li-Evan Li-Evan commented Nov 13, 2026

Copy link
Copy Markdown
Owner

What

Rebuilds the self-hosted web app (0.3.0). The Markdown CLI tutor under skills/ is unchanged.

  • Frontend: Next.js 15 (App Router), React 19, Tailwind CSS 4, Chinese / English UI, light and dark themes. The browser only talks to a same-origin proxy (/api/backend).
  • Backend: FastAPI + SQLAlchemy 2 with Alembic migrations. SQLite by default (backend/storage/), Postgres supported.
  • Features: course creation from a goal (with clarifying questions), uploaded materials, project files or folders, web articles and PDF reading; outline review before lesson 1; adaptive lessons with teaching plans, review and feedback scopes; evaluation lesson and course summary; highlight Q&A, passage marks, selection translation, whole-lesson chat; knowledge map on a frozen Wikipedia Vital Articles (level 5) snapshot; next-step recommendations with a wishlist; user center with notes, activity heatmap and Markdown export; material courses as folders; browser web clipper.
  • Still single-user and self-hosted: no accounts, login, admin, billing or payments. The Next.js server signs short-lived tokens for one local user with BACKEND_JWT_SECRET; the backend rejects anything else. docker compose publishes only the frontend, on 127.0.0.1.
  • Models: one OpenAI-compatible gateway (LLM_BASE_URL, LLM_API_KEY, LLM_MODEL; optional LLM_FAST_MODEL, PDF_READING_MODEL).
  • Breaking: the old bloom.db is not migrated; the new version starts with an empty database.
  • Third-party licences (shadcn/ui, fonts, Wikipedia / Wikidata data) are listed in THIRD_PARTY_NOTICES.md.

How to verify

What was run for this PR:

  • Backend: uv run --frozen pytest -q → 1998 passed, 11 skipped. On a throwaway Postgres 18: alembic upgrade head, alembic check clean, the Postgres tests pass, downgrade and re-upgrade work.
  • Frontend: tsc --noEmit (also with --noUnusedLocals --noUnusedParameters), next lint, pnpm test → 621 passed.
  • End to end against a local fake OpenAI-compatible server: topic course from clarify to summary, highlight Q&A, whole-lesson chat, translation in the English UI, knowledge map update, recommendations, nickname, project files with a PDF and an image, PDF reading. A second user's token cannot read the first user's course or images; removed pages and APIs return 404.
  • gitleaks and trufflehog (no online verification) over every file in the commit: only test placeholders and knowledge-tree IDs.
  • docker compose up -d --build: images contain no .env or secret, the backend runs as a non-root user and is not published on the host, a course with two lessons was created through the stack, and data survived a restart.
  • scripts/secret-scan.sh passes with gitleaks and with its regex fallback (what CI uses).

To try it yourself:

make setup          # creates .env with a random BACKEND_JWT_SECRET
# fill LLM_API_KEY, LLM_BASE_URL and LLM_MODEL in .env
docker compose up -d --build
# open http://localhost:3000

How to roll back

  • git revert this PR's merge commit.
  • Data written by the new version stays in backend/storage/ (or the bloom-storage compose volume); the old bloom.db is not touched.

🤖 Generated with Claude Code

What:
- Replace the old React/Vite web app and its backend with the current Bloom
  app: Next.js 15 frontend (Chinese/English UI, light/dark themes, same-origin
  proxy to the backend) and a FastAPI backend with Alembic migrations.
- Features: course creation from a goal with clarifying questions, from
  uploaded materials, project files, web articles and PDF reading; outline
  review before lesson 1; adaptive lessons with teaching plans, review and
  feedback scopes; evaluation lesson and course summary; highlight Q&A,
  passage marks, selection translation, whole-lesson chat; knowledge map on a
  frozen Wikipedia Vital Articles level 5 snapshot; next-step recommendations
  and wishlist; user center with notes, activity and Markdown export;
  material courses as folders; browser web clipper.
- Still self-hosted and single-user: no accounts, login, admin, billing or
  payments. The Next.js server signs short-lived HS256 tokens for one local
  user with BACKEND_JWT_SECRET; the backend rejects anything else.
- One OpenAI-compatible model gateway (LLM_BASE_URL / LLM_API_KEY /
  LLM_MODEL, optional LLM_FAST_MODEL and PDF_READING_MODEL). SQLite by default
  under backend/storage, Postgres supported; images on local disk.
- docker compose publishes only the frontend on 127.0.0.1; make setup creates
  .env with a random secret. Third-party licences are listed in
  THIRD_PARTY_NOTICES.md.
- Breaking: the old bloom.db is not migrated; the new version starts empty.

How to verify:
- backend: uv run --frozen pytest -q -> 1998 passed, 11 skipped (in-memory
  SQLite); on a throwaway Postgres 18: alembic upgrade head, alembic check
  clean, 11 postgres tests passed, downgrade and re-upgrade OK.
- frontend: tsc --noEmit (with noUnusedLocals/Parameters) clean, next lint
  clean, pnpm test -> 621 passed, 0 failed.
- End to end with a local fake OpenAI-compatible server (no real model):
  created a topic course (clarify -> outline -> lessons 1-2 -> evaluation ->
  summary), highlight Q&A, whole-lesson chat, selection translation in the
  English UI, knowledge map update, recommendations and wishlist, nickname
  change, project files with a PDF and an image, PDF reading; a second user's
  token could not read the first user's course or image; removed pages and
  APIs return 404.
- Secret scans on the exact file set: gitleaks and trufflehog (no online
  verification) found only test placeholders and knowledge-tree IDs.
- docker compose: both images build; neither contains .env or the generated
  secret; the backend runs as a non-root user, is healthy and not published
  on the host; through the stack a course was created and two lessons were
  generated (streaming included); data survived a restart.
- scripts/secret-scan.sh passes both with gitleaks and with its regex
  fallback (the path CI takes).
- To re-check: make setup, fill LLM_* in .env, docker compose up -d --build,
  open http://localhost:3000.

How to roll back:
- git revert <this commit>
- Data created by the new version lives in backend/storage (or the
  bloom-storage compose volume); the old bloom.db is not touched.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Li-Evan
Li-Evan merged commit 6247535 into main Nov 13, 2026
4 checks passed
@Li-Evan
Li-Evan deleted the feat/web-app-0.3.0 branch November 13, 2026 10:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant