Skip to main content

Tech Stack

Backend​

  • FastAPI — Python async web framework
  • psycopg2-binary — PostgreSQL driver (synchronous)
  • Pydantic v2 — Data validation
  • python-jose — JWT creation/verification (HS256)
  • bcrypt — Direct bcrypt import (ARM64-compatible, avoids passlib self-test bug)
  • SQLAlchemy 2.0 — ORM (User, Lesson, Presentation models)
  • PVC storage — zhiheng-user-data-pvc (shared, per-user subPath)
  • httpx — Async HTTP client for LLM/embedding APIs
  • python-pptx — PPTX generation and slide counting
  • Redis — Rate limiting (500 req/min per IP per path), session cache, token store

Frontend​

  • Vue 3.5 + Vite — SPA with Vue Router 4
  • Tailwind CSS — Utility-first CSS with OKLCH design system tokens
  • react-i18next — Internationalization (zh primary, en secondary, JSON locale files)
  • Docusaurus — Documentation site

AI / ML​

  • vLLM (External) — Remote LLM endpoint (Qwen3.6-35B-A3B-FP8 via vllm-fast.cxr-insight.com) — streaming generation via SSE
  • RAG: LightRAG (vendor fork, PostgreSQL + pgvector + AGE graph, port 9621) — fully integrated
  • KohakuRAG — Local RAG engine (embedded in backend, medical X-ray image understanding)
  • Embedding model — Qwen3-Embedding-8B via OpenRouter (qwen/qwen3-embedding-8b) — fully integrated
  • Chat Agent — DeerFlow (SSE streaming, PPT generation)
  • Speech recognition — Planned: local fine-tuned model with educational terminology correction

Infrastructure​

  • PVC storage — zhiheng-user-data-pvc (shared, sandbox-rwx RWX, per-user subPath)
  • PostgreSQL 16 — Primary database (Docker, pgvector + AGE graph extensions)
  • Nginx — Reverse proxy (frontend + API, security headers, CSP, HSTS, gzip)
  • Kubernetes (k3s) — Production deployment (nginx, frontend, backend, db, redis, lightrag, deerflow, deerflow-mcp, sandbox-provisioner)
  • Cloudflare Tunnel — TLS termination → zhiheng.app
  • Cloudflare Worker — Session cookie auth gate (zhiheng-auth-gate)
  • Cloudflare Pages — Docs site hosting (docs-zhiheng.gxnu-agent.com)
  • Redis 7 — Rate limiting, chat thread storage, token store
  • DeerFlow — AI agent platform (PPT generation, multi-tenant, sandbox)

Implemented API Endpoints​

  • Auth: POST /auth/register, POST /auth/login, GET /auth/me, PUT /auth/me, POST /auth/change-password
  • Lessons: CRUD /lessons, POST /lessons/:id/generate (SSE → vLLM)
  • Knowledge: GET /knowledge/health, POST /knowledge/qa (streaming), POST /knowledge/search, POST /knowledge/ingest, POST /knowledge/upload
  • Chat: POST /chat (SSE streaming), GET /chat/threads, GET /chat/files/:name
  • Presentations: CRUD /presentations, POST /presentations/:id/generate (DeerFlow PPT generation)
  • Internal: GET /internal/lessons, GET /internal/presentations (service-to-service)
  • Health: GET /health

Design System​

  • DESIGN.md — Formal token spec (OKLCH, WCAG validated, CJK-first)
  • Tailwind export — DESIGN.tailwind.json for frontend integration
  • Reference style — Mintlify-inspired, adapted for Chinese education context