web/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

WebPreview is a web-based tutorial/challenge platform where users view tutorials and submit HTML/CSS/JS code for challenges. It has a Django API backend and a Vue 3 frontend, deployed via Docker Compose with Caddy as reverse proxy.

Architecture

• api/ — Django backend using django-ninja for REST APIs and Django Channels (Daphne/ASGI) for WebSocket support

  • api/api/ — Django project config (settings, urls, asgi)
  • api/account/ — User auth (login/logout, profiles, batch creation). Three roles: super, admin, normal — affects scoring weights
  • api/task/ — Tutorial and Challenge models (single Task base model with task_type), with separate tutorial.py and challenge.py router files
  • api/submission/ — Code submission + Rating model. Submission score is a weighted average of ratings by role: super×0.5, admin×0.3, normal×0.2. Profile.recalculate_total_score() uses best-score-per-challenge
  • api/prompt/ — LLM chat feature: WebSocket consumer streams DeepSeek responses, Conversation/Message models store history, code blocks extracted from responses
  • api/utils/upload.py — Image upload endpoint
  • API routers are registered in api/api/urls.py under /api/ prefix
  • Uses AUTH_USER_MODEL = "account.User" (custom user model)
  • Dev mode uses SQLite (ENV != "production"); production uses PostgreSQL + Redis (sessions, caching, channel layers)

• client/ — Vue 3 + TypeScript SPA built with Rsbuild

  • UI framework: Naive UI (auto-imported via unplugin-vue-components)
  • src/api.ts — Axios-based API client with CSRF and auth interceptors; exports Account, Tutorial, Challenge, Submission, Prompt, Helper objects
  • src/router.ts — Vue Router with auth guards; routes under /dashboard require login
  • src/store/ — Reactive state (plain Vue refs, not Vuex/Pinia)
  • src/pages/ — Route-level views (Home, Dashboard, ChallengeHome, TutorialEditor, ChallengeEditor, Submissions, Leaderboard, MyScores)
  • src/components/ — Shared components: Task.vue, Tutorial.vue, Challenge.vue, Editors.vue (CodeMirror), Preview.vue (live HTML preview), Toolbar.vue, PromptPanel.vue (LLM chat)

• Caddyfile — Routes /api*, /admin*, /ws* to backend; serves SPA and static/media files

• docker-compose.yaml — Services: caddy, api, postgres, redis

Development Commands

Client (from client/)

npm run start        # Dev server (Rsbuild)
npm run build        # Production build
npm run fmt          # Format with Prettier

Frontend env vars used at build time: PUBLIC_BASE_URL, PUBLIC_ADMIN_URL, PUBLIC_WS_URL.

API (from api/)

uv run manage.py runserver    # Dev server
uv run manage.py migrate      # Run migrations
uv run manage.py createsuperuser  # Create admin user

Uses uv for Python dependency management (pyproject.toml + uv.lock). Set ENV=dev in .env (default) for SQLite.

Docker (from project root)

docker compose up -d          # Start all services
docker compose up -d --build  # Rebuild and start

Key Technical Details

• Backend API pattern: each Django app has api.py (or named router files like task/tutorial.py, task/challenge.py) with django-ninja routers, plus schemas.py for Pydantic models. Routers mount under /api/<prefix>/
• WebSocket: prompt/consumers.py handles LLM chat at ws://<host>/ws/prompt/<task_id>/. Django Channels is configured; in dev, channel layer is in-memory (no Redis needed)
• LLM config: LLM_API_KEY, LLM_BASE_URL (default: DeepSeek), LLM_MODEL set via .env
• Task display field: integer used as URL slug for tutorials/challenges (unique per task type), not the DB id
• Submission IDs: UUIDs (not integers)
• Frontend dev server proxies /media to PUBLIC_WEB_URL env var; API calls go to BASE_URL defined in src/utils/const.ts
• Environment config via .env file in api/ (referenced by docker-compose and Django's python-dotenv)
• Language/locale is Chinese (zh-hans, Asia/Shanghai timezone)
• Client build output goes to build/ directory, served by Caddy in production