hello-web/AGENTS.md

AGENTS.md — hello-web

FastAPI backend + Vue 3 (Options API) + Vite frontend + PostgreSQL (async SQLAlchemy). UI text and HTML lang attribute are Korean.

Project structure

backend/
  app.py            — FastAPI app, static mount, CORS, lifespan auto-create tables
  database.py       — async engine + session factory (DATABASE_URL env or default)
  models.py         — Sample model (id, title, content, author, created_at)
  schemas.py        — SampleResponse, SampleCreate(required), SampleUpdate(optional)
  routers/samples.py— full CRUD: GET list, GET /{id}, POST, PUT /{id}, DELETE /{id}
  seed.py           — creates tables + idempotent INSERT of 5 sample rows
frontend/
  src/pages/        — SampleListPage, SampleDetailPage, SampleFormPage (+ Home, About)
  src/router.js     — 6 routes: /, /about, /samples, /samples/new, /samples/:id, /samples/:id/edit
  vite.config.js    — proxy /api → localhost:8000, outDir: dist
dev.sh              — runs uvicorn (:8000) + vite dev (:5173) concurrently, kill both on Ctrl+C

Commands

Action	From	Command
Dev (both servers)	root	./dev.sh
Backend dev	backend/	uvicorn app:app --reload --port 8000
Frontend dev	frontend/	npm run dev (port 5173)
Seed DB	root	python3 backend/seed.py
Frontend build	frontend/	npm run build (outputs to dist/)
Install backend deps	root	pip3 install -r backend/requirements.txt
Install frontend deps	frontend/	npm install

Workflow

• Dev (hot-reload): ./dev.sh — or run uvicorn + npm run dev in separate terminals. Visit localhost:5173. Vite proxies /api → uvicorn on 8000.
• Prod (FastAPI serves SPA): npm run build → uvicorn serves frontend/dist/ at localhost:8000.
• First-time setup: python3 backend/seed.py to create tables and insert sample data. Tables also auto-create on app startup via lifespan hook.
• CORS in backend/app.py allows dev server origins only (5173). Not needed when FastAPI serves the SPA directly.

Constraints

• No tests, no lint, no typecheck. Zero test infrastructure — do not look for it or run it.
• backend/app.py mounts StaticFiles(directory="../frontend/dist") — dist must exist before accessing via uvicorn.
• Vue uses Options API (data(), methods, mounted(), computed) — do not rewrite to Composition API unless asked.
• PostgreSQL must be reachable at 192.168.0.60:5432 (or override via DATABASE_URL env var).
• SampleUpdate has all-optional fields; SampleCreate has all-required fields.
• Behavioral guidelines: see CLAUDE.md and 클로드.md (Korean translation).