Initial Commit

2026-06-11 15:05:08 +08:00
commit ea8e41e688
21 changed files with 2317 additions and 0 deletions
@@ -0,0 +1,67 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+NexHome — a modern American-style second-hand house sales website built with FastAPI + Jinja2 templates. Features user authentication, property listings with search/filter, property CRUD with image upload, favorites, contact info with international phone formatting, and a user dashboard.
+
+## Running the App
+
+```bash
+source .venv/bin/activate
+
+# Recreate DB tables (first time or after model changes)
+python -c "from database import engine; from models import Base; Base.metadata.drop_all(bind=engine); Base.metadata.create_all(bind=engine)"
+
+# Start the dev server
+uvicorn main:app --reload
+```
+
+**Prerequisites:**
+- Python 3.14
+- MySQL server running locally with a `NexHome` database
+- Set the `SECRET_KEY` environment variable (used by `auth.py` for JWT signing)
+
+## Architecture
+
+**`main.py`** — FastAPI entry point. Creates the app, includes auth and properties routers, creates DB tables on startup, serves the homepage.
+
+**`auth.py`** — Authentication router (`/auth` prefix). User registration, login (JWT in HttpOnly cookie), logout. `get_current_user()` checks cookie first, then bearer token, returns `None` for anonymous users.
+
+**`config.py`** — Shared config: `SECRET_KEY`, `templates`, `bcrypt_context`, `oauth2_bearer`. Jinja2 cache disabled for Python 3.14 compatibility.
+
+**`database.py`** — SQLAlchemy setup with MySQL engine, `SessionLocal`, `Base`.
+
+**`models.py`** — ORM models: `User` (with email/full_name/phone), `Property` (with contact_email/contact_phone), `PropertyImage`, `Favorite`.
+
+**`properties.py`** — Property CRUD, search/filter, favorites, dashboard. Static paths (`/properties/new`) must be defined before parameterized paths (`/properties/{prop_id}`).
+
+## Data Flow
+
+Request → Router → dependency injection (`get_current_user`, `get_db`) → SQLAlchemy → Jinja2 template → HTML response.
+
+**TemplateResponse API:** `templates.TemplateResponse(request, "template.html", {"user": user, ...})` — request is first arg (Starlette 1.x).
+
+## Key Conventions
+
+- DB sessions: `Annotated[Session, Depends(get_db)]` (the `db_dependency` alias).
+- Redirect after POST: `RedirectResponse(url="...", status_code=303)`.
+- Image uploads: saved to `static/properties/` with UUID filenames, max 5MB.
+- USD currency: prices stored as integer dollars, displayed as `${:,}`.
+- Phone input: `templates/components/phone_input.html` — JS-powered country code selector with flags, dynamic placeholders, auto-formatting.
+- Route ordering: static paths before parameterized paths in `properties.py`.
+
+## Template Structure
+
+- `templates/base.html` — Tailwind CSS CDN layout with navbar + footer
+- `templates/components/` — navbar, footer, property_card macro, phone_input
+- `templates/auth/` — login, register
+- `templates/properties/` — list, detail, create, edit
+- `templates/dashboard/` — user dashboard (my listings + favorites)
+
+## Known Issues
+
+- `database.py` exports the engine as `engin` (typo).
+- No `requirements.txt` or `pyproject.toml`.
+- Database credentials hardcoded in `database.py`.