From eadfbeab35ce676ea068cf894abdf5110cd6f3b6 Mon Sep 17 00:00:00 2001 From: curo1305 Date: Sun, 12 Apr 2026 15:14:44 +0200 Subject: [PATCH] Add README, changelog directory, and changelog convention to CLAUDE.md Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 14 ++++ README.md | 93 ++++++++++++++++++++++++ changelog/2026-04-12_initial-scaffold.md | 63 ++++++++++++++++ 3 files changed, 170 insertions(+) create mode 100644 README.md create mode 100644 changelog/2026-04-12_initial-scaffold.md diff --git a/CLAUDE.md b/CLAUDE.md index 3dfcf0e..87ca763 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -88,6 +88,20 @@ Browser → Vite dev server (:5173) 2. Token stored in `localStorage`, attached to every request by the Axios interceptor 3. Protected routes call `GET /api/users/me`; `get_current_user` dep validates the token on the server +## Changelog convention + +Every time files are added or modified, append an entry to the relevant file in `changelog/` (one file per date, named `YYYY-MM-DD_.md`). If a file for today already exists, append to it rather than creating a new one. + +Each entry must include: +- A heading with the date and a short description +- `**Timestamp:**` in ISO-8601 format +- A **Summary** sentence +- A **Files Added / Modified / Deleted** list with one-line descriptions + +The `README.md` **Current State** section should be kept up to date whenever significant features are added or removed. + +--- + ### Adding a new resource 1. Add ORM model in `app/models/`, import it in `app/models/__init__.py` diff --git a/README.md b/README.md new file mode 100644 index 0000000..22ef0e1 --- /dev/null +++ b/README.md @@ -0,0 +1,93 @@ +# destroying_sap + +A fullstack SaaS web application built with FastAPI, React, and PostgreSQL. + +## Stack + +| Layer | Tech | +|---|---| +| Backend | FastAPI (async), SQLAlchemy 2, Alembic, PostgreSQL 16 | +| Auth | JWT bearer tokens, bcrypt password hashing | +| Frontend | React 18, TypeScript, Vite, React Router v6, TanStack Query | + +## Current State + +- User registration and login (JWT auth) +- Protected dashboard route +- `/api/users/me` — authenticated user info +- Vite dev server proxies `/api` to FastAPI — no CORS issues in development + +## Installation + +### Prerequisites + +- Python 3.11+ +- Node.js 18+ +- PostgreSQL 16 (or Docker) + +### Option A — Docker (recommended) + +```bash +git clone +cd destroying_sap +cp .env.example backend/.env +docker compose up --build +``` + +- Frontend: http://localhost:5173 +- Backend / API docs: http://localhost:8000/docs + +### Option B — Local + +**1. Start PostgreSQL** + +```bash +docker compose up db -d +# or use a local PostgreSQL instance and update backend/.env +``` + +**2. Backend** + +```bash +cd backend +python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate +pip install -e ".[dev]" +cp ../.env.example .env # edit DATABASE_URL and SECRET_KEY as needed +alembic upgrade head +uvicorn app.main:app --reload +``` + +**3. Frontend** + +```bash +cd frontend +npm install +npm run dev +``` + +## Environment Variables + +Copy `.env.example` to `backend/.env` and adjust: + +| Variable | Default | Description | +|---|---|---| +| `DATABASE_URL` | `postgresql+asyncpg://postgres:password@localhost:5432/destroying_sap` | Async PostgreSQL URL | +| `SECRET_KEY` | `change-me-in-production` | JWT signing key | +| `CORS_ORIGINS` | `["http://localhost:5173"]` | Allowed frontend origins | + +## Development + +```bash +# Backend lint + format +cd backend && ruff check . && ruff format . + +# Backend tests +cd backend && pytest + +# Frontend type check + lint +cd frontend && npm run typecheck && npm run lint + +# New DB migration (after changing models) +cd backend && alembic revision --autogenerate -m "describe change" +cd backend && alembic upgrade head +``` diff --git a/changelog/2026-04-12_initial-scaffold.md b/changelog/2026-04-12_initial-scaffold.md new file mode 100644 index 0000000..2a859a9 --- /dev/null +++ b/changelog/2026-04-12_initial-scaffold.md @@ -0,0 +1,63 @@ +# 2026-04-12 — Initial project scaffold + +**Timestamp:** 2026-04-12T14:22:00 + +## Summary + +Created the initial fullstack SaaS project structure from scratch. + +## Files Added + +### Backend +- `backend/pyproject.toml` — project dependencies (FastAPI, SQLAlchemy, Alembic, pydantic-settings, python-jose, passlib) +- `backend/alembic.ini` — Alembic configuration +- `backend/alembic/env.py` — async Alembic migration environment +- `backend/alembic/script.py.mako` — migration file template +- `backend/app/__init__.py` +- `backend/app/main.py` — FastAPI app, CORS middleware, router mounts +- `backend/app/database.py` — async SQLAlchemy engine, session factory, `Base` +- `backend/app/deps.py` — `get_current_user` FastAPI dependency (JWT validation) +- `backend/app/core/__init__.py` +- `backend/app/core/config.py` — `Settings` via pydantic-settings, reads `.env` +- `backend/app/core/security.py` — bcrypt password hashing, JWT encode/decode +- `backend/app/models/__init__.py` +- `backend/app/models/user.py` — `User` ORM model (id, email, hashed_password, full_name, is_active, is_superuser) +- `backend/app/schemas/__init__.py` +- `backend/app/schemas/user.py` — `UserCreate`, `UserOut`, `Token` Pydantic schemas +- `backend/app/routers/__init__.py` +- `backend/app/routers/auth.py` — `POST /api/auth/register`, `POST /api/auth/login` +- `backend/app/routers/users.py` — `GET /api/users/me` + +### Frontend +- `frontend/package.json` — dependencies (React 18, TypeScript, Vite, React Router v6, TanStack Query, Axios) +- `frontend/vite.config.ts` — Vite config, `/api` proxy to `:8000` +- `frontend/tsconfig.json` — strict TypeScript config +- `frontend/index.html` +- `frontend/src/main.tsx` — React root, QueryClientProvider, BrowserRouter +- `frontend/src/App.tsx` — route tree, `PrivateRoute` guard +- `frontend/src/api/client.ts` — Axios instance, auth interceptor, `login`, `register`, `getMe` +- `frontend/src/hooks/useAuth.ts` — JWT token state, `login`, `logout` +- `frontend/src/pages/LoginPage.tsx` +- `frontend/src/pages/RegisterPage.tsx` +- `frontend/src/pages/DashboardPage.tsx` + +### Root +- `docker-compose.yml` — postgres, backend, frontend services +- `.env.example` +- `.gitignore` +- `CLAUDE.md` + +--- + +# 2026-04-12 — Added README and changelog + +**Timestamp:** 2026-04-12T14:45:00 + +## Summary + +Added project README with overview and installation guide. Created `changelog/` directory and this initial entry. + +## Files Added + +- `README.md` — project overview, stack table, current state, Option A (Docker) and Option B (local) install guides, env variable reference, dev commands +- `changelog/2026-04-12_initial-scaffold.md` — this file