refactor: refactor project structure

first refactor project structure, add CLAUDE.md and AGENTS.md

Changelog: refactor

Author: remember-5

.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "Bash(uv run:*)"
+    ]
+  }
+}

.env .env.example.env renamed to .env.example

@@ -1,6 +1,6 @@
 # Domain
 # This would be set to the production domain with an env var on deployment
-# used by Traefik to transmit traffic and aqcuire TLS certificates
+# used by Traefik to transmit traffic and acquire TLS certificates
 DOMAIN=localhost
 # To test the local Traefik config
 # DOMAIN=localhost.tiangolo.com
@@ -18,6 +18,8 @@ STACK_NAME=full-stack-fastapi-project
 
 # Backend
 BACKEND_CORS_ORIGINS="http://localhost,http://localhost:5173,https://localhost,https://localhost:5173,http://localhost.tiangolo.com"
+
+# python -c "import secrets; print(secrets.token_urlsafe(32))"
 SECRET_KEY=changethis
 FIRST_SUPERUSER=admin@example.com
 FIRST_SUPERUSER_PASSWORD=changethis

.gitignore

@@ -5,3 +5,7 @@ node_modules/
 /playwright-report/
 /blob-report/
 /playwright/.cache/
+
+# Environment files (use .env.example as template)
+.env
+.env.local

AGENTS.md

@@ -0,0 +1,171 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Full-stack web application template: **FastAPI** backend + **React/TypeScript** frontend. Monorepo with `backend/` and `frontend/` as separate workspaces managed by **uv** (Python) and **bun** (JS).
+
+## Common Commands
+
+### Running the Stack (Docker Compose — recommended)
+```bash
+docker compose watch                    # Start all services with hot-reload
+docker compose up -d                    # Start in background
+docker compose logs backend -f          # Tail backend logs
+```
+
+### Backend
+```bash
+cd backend
+uv sync                                 # Install dependencies
+fastapi dev app/main.py                 # Dev server on :8000 (hot-reload)
+
+# Lint & type-check
+bash scripts/lint.sh                    # Runs: mypy app && ruff check app && ruff format app --check
+
+# Tests (requires running PostgreSQL — use docker compose for DB)
+bash scripts/test.sh                    # coverage run + pytest + report
+uv run pytest tests/                    # Run all tests
+uv run pytest tests/api/routes/test_items.py          # Single test file
+uv run pytest tests/api/routes/test_items.py::test_create_item  # Single test
+
+# Alembic migrations
+uv run alembic revision --autogenerate -m "description"
+uv run alembic upgrade head
+```
+
+### Frontend
+```bash
+cd frontend
+bun install                             # Install dependencies
+bun run dev                             # Dev server on :5173
+bun run build                           # TypeScript check + Vite build
+bun run lint                            # Biome check --write --unsafe
+bun run test                            # Playwright E2E tests
+```
+
+### Regenerate Frontend API Client
+```bash
+# Requires backend running (exports OpenAPI JSON, generates TypeScript client)
+bash scripts/generate-client.sh
+```
+
+### Pre-commit Hooks
+```bash
+cd backend && uv run prek install -f    # Install hooks (uses prek, not pre-commit)
+uv run prek run --all-files             # Run all hooks manually
+```
+
+## Architecture
+
+### Backend (`backend/`)
+- **FastAPI** with **SQLModel** (SQLAlchemy + Pydantic hybrid) ORM
+- **PostgreSQL 18** via `psycopg` (psycopg3) driver
+- **Alembic** for DB migrations (auto-runs on container start via `prestart` service)
+- **JWT auth** (HS256 via `pyjwt`) with **Argon2** password hashing (bcrypt legacy fallback via `pwdlib`)
+- API routes: `backend/app/api/routes/` — `login`, `users`, `items`, `utils`, `private` (local-only)
+- Settings via `pydantic-settings` reading from root `.env` file, split into sub-configs (`DatabaseSettings`, `EmailSettings`)
+- Email via `emails` library + Jinja2 templates (MJML source → compiled HTML in `email-templates/`)
+- Sentry integration (disabled in `local` environment)
+- API docs hidden in production (only available in `local`/`staging`)
+
+#### Domain-based structure
+Code is organized by domain, each with its own models, service, dependencies, and constants:
+
+```
+backend/app/
+├── main.py                     # App entry point, CORS, Sentry, global DomainError handler
+├── api/
+│   ├── main.py                 # Router mounting
+│   ├── deps.py                 # Common dependencies (SessionDep, CurrentUser, etc.)
+│   └── routes/                 # Thin route handlers (HTTP protocol only)
+│       ├── login.py
+│       ├── users.py
+│       ├── items.py
+│       ├── utils.py
+│       └── private.py          # Local-only, uses service layer
+├── core/
+│   ├── config.py               # Settings + DatabaseSettings + EmailSettings
+│   ├── security.py             # JWT token creation, password hashing
+│   └── db.py                   # Engine, naming convention, init_db
+├── common/
+│   ├── models.py               # Shared models (Message, Token, TokenPayload, NewPassword), get_datetime_utc
+│   └── exceptions.py           # DomainError base class, InvalidResetTokenError, CredentialsValidationError
+├── users/
+│   ├── models.py               # User, UserCreate, UserUpdate, UserPublic, etc.
+│   ├── service.py              # Business logic (create, update, authenticate, etc.)
+│   ├── dependencies.py         # valid_user_id, ValidUser
+│   ├── exceptions.py           # UserNotFoundError, UserAlreadyExistsError, etc.
+│   └── constants.py            # Success message constants (PASSWORD_UPDATED, USER_DELETED)
+├── items/
+│   ├── models.py               # Item, ItemCreate, ItemUpdate, ItemPublic, etc.
+│   ├── service.py              # Business logic (create, update, delete, get_items)
+│   ├── dependencies.py         # valid_item_id, ValidItem, valid_owned_item (chained)
+│   ├── exceptions.py           # ItemNotFoundError, ItemPermissionError
+│   └── constants.py            # Success message constants (ITEM_DELETED)
+├── utils.py                    # Email utilities (send, generate templates)
+├── initial_data.py             # Seed superuser
+└── backend_pre_start.py        # DB readiness check
+```
+
+Key conventions:
+- **Routes are thin** — only HTTP protocol handling, business logic in `service.py`
+- **Dependencies chain** — e.g. `valid_owned_item` depends on `valid_item_id` (FastAPI caches per request)
+- **Domain exceptions** — each domain defines exception classes inheriting `DomainError(status_code, detail)`; a single global handler in `main.py` converts any `DomainError` to the matching HTTP response. No `HTTPException` in the codebase.
+- **Constants are for success messages only** — error messages live in exception classes as the single source of truth
+- **Settings sub-configs** — access via `settings.db.POSTGRES_*`, `settings.email.SMTP_*`
+
+Key files:
+- `app/core/config.py` — `Settings`, `DatabaseSettings`, `EmailSettings`
+- `app/core/db.py` — Engine + DB naming convention (`pk_`, `fk_`, `ix_`, `uq_`, `ck_`)
+- `app/api/deps.py` — Dependency injection (`SessionDep`, `CurrentUser`)
+- `app/common/exceptions.py` — `DomainError` base class (all domain exceptions inherit from it, carrying `status_code` + `detail`)
+
+### Frontend (`frontend/`)
+- **React 19** + **TypeScript 5.9** + **Vite 7** (SWC plugin)
+- **TanStack Router** (file-based routing in `src/routes/`, auto-generates `routeTree.gen.ts`)
+- **TanStack Query** (React Query v5) for server state
+- **Tailwind CSS v4** + **shadcn/ui** components (in `src/components/ui/`)
+- **Biome v2** for linting/formatting
+- API client auto-generated from OpenAPI spec via `@hey-api/openapi-ts` → `src/client/`
+- Forms: `react-hook-form` + `zod v4` validation
+- Auth guard in `_layout.tsx` redirects unauthenticated users to `/login`
+
+### Auto-generated Files (do not edit manually)
+- `frontend/src/client/` — Generated API client (regenerate via `scripts/generate-client.sh`)
+- `frontend/src/routeTree.gen.ts` — Generated by TanStack Router plugin
+- `backend/app/email-templates/build/` — Compiled from MJML sources
+
+### Docker Services
+- `db` — PostgreSQL 18
+- `prestart` — Runs migrations + seeds superuser
+- `backend` — FastAPI (port 8000)
+- `frontend` — Nginx serving built React app (port 80→5173 in dev)
+- `mailcatcher` — Local email testing (SMTP 1025, Web UI 1080)
+- Traefik reverse proxy routes: `api.<DOMAIN>` → backend, `dashboard.<DOMAIN>` → frontend
+
+## Code Style & Conventions
+
+### Backend
+- Python ≥3.10, mypy strict mode
+- Ruff rules: pycodestyle, pyflakes, isort, flake8-bugbear, comprehensions, pyupgrade, no print statements
+- Alembic directory excluded from ruff and mypy
+- Alembic migration naming: `YYYY-MM-DD_slug_revid.py` (via `file_template` in `alembic.ini`)
+- DB index naming convention: `pk_<table>`, `fk_<table>_<col>_<ref_table>`, `ix_<col>`, `uq_<table>_<col>`, `ck_<table>_<name>`
+- Tests require a running PostgreSQL instance; CI enforces ≥90% coverage
+
+### Frontend
+- Biome excludes: `dist/`, `src/routeTree.gen.ts`, `src/client/`, `src/components/ui/`
+- Path alias: `@` maps to `src/`
+- Dark mode default via `next-themes`
+
+## Environment
+- **`.env.example`** — Committed template with safe placeholder values (`changethis`). Developers copy to `.env` locally.
+- **`.env`** — Local config (gitignored). Shared by backend (pydantic-settings) and Docker Compose.
+- **`.env.local`** — Optional personal overrides (gitignored). Values here override `.env`, just like frontend's `.env.local` pattern.
+- **Priority chain**: environment variables > `.env.local` > `.env` > code defaults
+- Settings via `pydantic-settings` with `env_file=("../.env", "../.env.local")` — later files override earlier ones
+- Sub-configs: `settings.db.POSTGRES_*`, `settings.email.SMTP_*`
+- Key variables: `DOMAIN`, `SECRET_KEY`, `FIRST_SUPERUSER`/`FIRST_SUPERUSER_PASSWORD`, `POSTGRES_*`, `SMTP_*`
+- Production/CI: inject via environment variables (highest priority), no env files needed

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

backend/alembic.ini

@@ -5,7 +5,7 @@
 script_location = app/alembic
 
 # template used to generate migration files
-# file_template = %%(rev)s_%%(slug)s
+file_template = %%(year)d-%%(month).2d-%%(day).2d_%%(slug)s_%%(rev)s
 
 # timezone to use when rendering the date
 # within the migration file as well as the filename.

backend/app/alembic/env.py

@@ -15,12 +15,10 @@
 
 # add your model's MetaData object here
 # for 'autogenerate' support
-# from myapp import mymodel
-# target_metadata = mymodel.Base.metadata
-# target_metadata = None
 
-from app.models import SQLModel  # noqa
-from app.core.config import settings # noqa
+from app.users.models import SQLModel  # noqa: E402
+from app.items.models import Item  # noqa: E402, F401
+from app.core.config import settings  # noqa: E402
 
 target_metadata = SQLModel.metadata
 
@@ -31,7 +29,7 @@
 
 
 def get_url():
-    return str(settings.SQLALCHEMY_DATABASE_URI)
+    return str(settings.db.SQLALCHEMY_DATABASE_URI)
 
 
 def run_migrations_offline():

backend/app/alembic/versions/1a31ce608336_add_cascade_delete_relationships.py

@@ -0,0 +1,55 @@
+"""Initialize models
+
+Revision ID: 0001
+Revises:
+Create Date: 2026-03-14
+
+"""
+
+import sqlalchemy as sa
+import sqlmodel.sql.sqltypes
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "0001"
+down_revision = None
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "user",
+        sa.Column("email", sa.String(length=255), nullable=False),
+        sa.Column("is_active", sa.Boolean(), nullable=False),
+        sa.Column("is_superuser", sa.Boolean(), nullable=False),
+        sa.Column("full_name", sa.String(length=255), nullable=True),
+        sa.Column("id", sa.Uuid(), nullable=False),
+        sa.Column(
+            "hashed_password", sqlmodel.sql.sqltypes.AutoString(), nullable=False
+        ),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=True),
+        sa.PrimaryKeyConstraint("id", name="pk_user"),
+    )
+    op.create_index("ix_user_email", "user", ["email"], unique=True)
+    op.create_table(
+        "item",
+        sa.Column("title", sa.String(length=255), nullable=False),
+        sa.Column("description", sa.String(length=255), nullable=True),
+        sa.Column("id", sa.Uuid(), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("owner_id", sa.Uuid(), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["owner_id"],
+            ["user.id"],
+            name="fk_item_owner_id_user",
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("id", name="pk_item"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("item")
+    op.drop_index("ix_user_email", table_name="user")
+    op.drop_table("user")