chore: symlink CLAUDE.md to AGENTS.md
This commit is contained in:
parent
fcb5a127d4
commit
fce16288b5
127
CLAUDE.md
127
CLAUDE.md
@ -1,127 +0,0 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Project Overview
|
||||
|
||||
Yggdrasil is a Dioxus 0.7 fullstack web application — a blog system with user authentication. It compiles to both a WASM frontend and a native server backend from a single Rust codebase.
|
||||
|
||||
## Development Commands
|
||||
|
||||
```bash
|
||||
# Development server (Tailwind CSS watch + dx serve)
|
||||
make dev
|
||||
|
||||
# Production build (minified CSS + release binary)
|
||||
make build
|
||||
|
||||
# Build CSS only
|
||||
make css
|
||||
|
||||
# Watch CSS only
|
||||
make css-watch
|
||||
|
||||
# Standard Rust commands
|
||||
cargo build
|
||||
cargo clippy
|
||||
cargo test
|
||||
cargo clean && make clean
|
||||
|
||||
# Dioxus CLI commands
|
||||
dx serve # Dev server
|
||||
dx build --release # Release build
|
||||
dx check # Type-check the project
|
||||
```
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rust 1.95+ with `wasm32-unknown-unknown` target
|
||||
- `dx` CLI (Dioxus CLI) — install via `cargo install dioxus-cli`
|
||||
- `tailwindcss` CLI v4 — standalone binary needed for `make dev`/`make build`
|
||||
- PostgreSQL database running locally
|
||||
|
||||
## Environment Setup
|
||||
|
||||
Create a `.env` file with:
|
||||
|
||||
```
|
||||
DATABASE_URL=postgres://postgres:postgres@localhost:5432/yggdrasil
|
||||
```
|
||||
|
||||
Run the migration in `migrations/001_init.sql` to set up the `users` and `sessions` tables.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Fullstack Dioxus
|
||||
|
||||
The project uses Dioxus's fullstack mode with two Cargo features:
|
||||
|
||||
- **`web`** (`dioxus/web`): Compiles the frontend to WASM. Activated by default.
|
||||
- **`server`** (`dioxus/server`): Compiles the server-side code. Activated by default.
|
||||
|
||||
Server functions are defined with `#[server(Name, "/api")]` in `src/api/auth.rs`. These are callable from both client and server code. Dioxus handles the HTTP transport automatically.
|
||||
|
||||
### Conditional Compilation
|
||||
|
||||
Code is gated by two mechanisms:
|
||||
|
||||
- `#[cfg(feature = "server")]` — server-only code (database, background tasks, env loading). The `db` and `tasks` modules are entirely server-gated.
|
||||
- `#[cfg(target_arch = "wasm32")]` — browser-only code (localStorage, cookie manipulation, DOM APIs).
|
||||
|
||||
The `db::pool` module provides a `DummyPool` stub when the `server` feature is disabled, so the code compiles for WASM.
|
||||
|
||||
### Authentication Flow
|
||||
|
||||
1. **Registration** (`src/api/auth.rs:register`): First registration creates the admin account. Subsequent registrations are rejected (`"Registration is closed"`). Passwords are hashed with Argon2.
|
||||
2. **Login** (`src/api/auth.rs:login`): Validates credentials against the `users` table, creates a session record with a UUID token, returns the token.
|
||||
3. **Session Storage**: The token is stored in a browser cookie (client-side, not HttpOnly). The server checks the `sessions` table for valid, non-expired tokens.
|
||||
4. **Logout** (`src/api/auth.rs:logout`): Clears the client cookie and deletes expired sessions from the database.
|
||||
|
||||
### Database
|
||||
|
||||
- PostgreSQL via `tokio-postgres` with `deadpool-postgres` connection pooling.
|
||||
- The pool is a `LazyLock` global in `src/db/pool.rs`, initialized from `DATABASE_URL`.
|
||||
- Pool max size is 10 connections.
|
||||
|
||||
### Background Tasks
|
||||
|
||||
On server startup (`src/main.rs`), a background thread runs `tasks::session_cleanup::run_cleanup()`, which deletes expired sessions every hour.
|
||||
|
||||
### Routing
|
||||
|
||||
Routes are defined in `src/router.rs` using `#[derive(Routable)]`:
|
||||
|
||||
- `/` — Home (landing page with login/register links)
|
||||
- `/login` — Login page
|
||||
- `/register` — Registration page
|
||||
- `/admin` — Admin dashboard (redirects to `/login` if not authenticated)
|
||||
|
||||
### Styling
|
||||
|
||||
- Tailwind CSS v4, compiled from `input.css` (`@import "tailwindcss"`) to `public/style.css`.
|
||||
- Dark mode is implemented via the `dark:` variant with a `data-theme` attribute on the `<html>` element.
|
||||
- The `ThemeToggle` component persists the preference in `localStorage`.
|
||||
|
||||
## Key Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `src/router.rs` | Route definitions and root app component with theme wrapper |
|
||||
| `src/api/auth.rs` | Server functions: `register`, `login`, `logout`, `get_current_user` |
|
||||
| `src/db/pool.rs` | Database connection pool (`LazyLock<Pool>`) |
|
||||
| `src/auth/password.rs` | Argon2 password hashing and verification |
|
||||
| `src/auth/session.rs` | UUID token generation and expiry calculation |
|
||||
| `src/models/user.rs` | `User` struct and `UserRole` enum (`Admin` / `Blocked`) |
|
||||
| `src/pages/admin.rs` | Admin dashboard with auth check and logout |
|
||||
| `src/tasks/session_cleanup.rs` | Hourly background job to purge expired sessions |
|
||||
| `src/theme.rs` | Dark/light theme state management and toggle button |
|
||||
| `migrations/001_init.sql` | Database schema (users + sessions tables) |
|
||||
| `Dioxus.toml` | Dioxus app config (default platform = web) |
|
||||
| `Makefile` | Convenience targets for dev/build/css |
|
||||
|
||||
## Important Notes
|
||||
|
||||
- The session cookie is set client-side via `web_sys::HtmlDocument::set_cookie`, which means it is **not HttpOnly**. This is a known limitation of the current implementation.
|
||||
- `get_current_user` returns the most recently created valid session (not necessarily the one matching the current request's cookie). The admin page relies on this for authentication state.
|
||||
- The `#[allow(dead_code)]` attributes on auth utilities are needed because the compiler sees them as unused in WASM builds where server functions are stripped.
|
||||
- `rand` with `getrandom` and `getrandom` with `js` feature are required for Argon2 salt generation in WASM builds.
|
||||
Loading…
x
Reference in New Issue
Block a user