127 lines
4.5 KiB
Markdown
127 lines
4.5 KiB
Markdown
# AI Guidelines — Domotique Rust/Leptos
|
|
|
|
## Project overview
|
|
|
|
Home automation dashboard built with Leptos (full-stack Rust). Exposes a web UI for managing quick links and controlling shutters via HTTP API to IoT devices. Runs as a systemd service with SSR + WASM hydration.
|
|
|
|
## Tech stack
|
|
|
|
| Layer | Technology |
|
|
|---|---|
|
|
| Framework | Leptos 0.6 (SSR + hydration) |
|
|
| Server | Axum 0.7 + Tokio |
|
|
| Database | MySQL via SQLx 0.8 (compile-time checked queries) |
|
|
| Frontend | WASM (wasm-bindgen), Tailwind CSS 4 |
|
|
| Build | cargo-leptos, Makefile |
|
|
|
|
## Architecture
|
|
|
|
### Dual-target compilation
|
|
|
|
- `ssr` feature: binary target, runs Axum, has DB access, pre-renders HTML
|
|
- `hydrate` feature: lib target compiled to WASM, mounts into DOM
|
|
|
|
Gate all server-only code (database, filesystem, secrets) with `#[cfg(feature = "ssr")]`.
|
|
|
|
### Directory layout
|
|
|
|
```
|
|
src/
|
|
app.rs # App component, router, nav
|
|
lib.rs # WASM entry point (hydrate feature)
|
|
main.rs # Binary entry point (ssr feature)
|
|
setup.rs # Axum server initialization
|
|
database.rs # Global MySqlPool (OnceLock)
|
|
models/ # Data models + SQL queries
|
|
routes/ # Page components + server functions
|
|
migrations/ # SQLx migrations (timestamp-named)
|
|
style/ # Compiled Tailwind output
|
|
input.css # Tailwind source
|
|
```
|
|
|
|
### Data flow
|
|
|
|
1. Page component defines a `Resource` that calls a server function
|
|
2. Server function (`#[server]`) queries the DB via `sqlx::query!`
|
|
3. Mutations use `create_server_action` or `create_action`
|
|
4. After mutation, increment a version signal to trigger resource refetch
|
|
|
|
## Coding conventions
|
|
|
|
### Language & naming
|
|
|
|
- UI labels and user-facing strings are in **French** (e.g., `Liens`, `Volets`)
|
|
- Rust identifiers follow standard conventions: `snake_case` for functions/variables, `PascalCase` for types and components
|
|
- Server function names are descriptive PascalCase (e.g., `GetLinksAction`, `LinkAction`)
|
|
|
|
### Components
|
|
|
|
- One `#[component]` per logical unit, small and single-responsibility
|
|
- Use `create_rw_signal` / `create_signal` for local state
|
|
- Use `Resource` for async data; include a version signal for cache invalidation
|
|
- Modal pattern for forms: single component toggled between create/edit mode
|
|
|
|
### Server functions
|
|
|
|
```rust
|
|
#[server(MyAction, "/api", "GetJson")] // or "Cbor" for mutations
|
|
pub async fn my_action(...) -> Result<T, ServerFnError> {
|
|
// DB access gated by ssr feature implicitly via #[server]
|
|
}
|
|
```
|
|
|
|
- Return `Result<T, ServerFnError>`
|
|
- Log errors with `tracing::error!` before returning a generic error to the client
|
|
- Never expose internal error details to the client
|
|
|
|
### Database
|
|
|
|
- Use `sqlx::query!` / `sqlx::query_as!` for compile-time checked SQL
|
|
- Access the pool via the global `get_db()` helper in `database.rs`
|
|
- Keep queries in the model file for the relevant type (`models/link.rs`)
|
|
- Connection pool max: 4 connections — avoid holding connections across await points
|
|
|
|
### Styling
|
|
|
|
- Tailwind utility classes only — no custom CSS except CSS variables in `input.css`
|
|
- Dark-first design; use `dark:` variants when needed
|
|
- Custom color tokens (defined in `input.css`, OKLCH color space):
|
|
- `prim`, `prim-light` — primary accent
|
|
- `second`, `second-dark` — secondary
|
|
- `third`, `third-light` — tertiary accent
|
|
- `fourth`, `green` — utility
|
|
- Responsive breakpoints: `xs:`, `sm:`, `md:`, `lg:`
|
|
|
|
### Error handling
|
|
|
|
- Server functions: `Result<T, ServerFnError>`, log then return generic message
|
|
- Components: handle `None` / error states explicitly in the view
|
|
- Avoid `unwrap()` in production paths; use `?` or explicit error handling
|
|
|
|
## Development workflow
|
|
|
|
```bash
|
|
# Start dev server (auto-reload)
|
|
cargo leptos watch
|
|
|
|
# Watch Tailwind in parallel
|
|
npx tailwindcss -i input.css -o ./style/output.css --watch
|
|
|
|
# Run DB migrations
|
|
sqlx migrate run
|
|
|
|
# Production deploy
|
|
make install # builds Tailwind + WASM + binary, restarts systemd service
|
|
```
|
|
|
|
Environment variables are loaded from `.env` (`DATABASE_URL` required).
|
|
|
|
## Key patterns to follow
|
|
|
|
- **No new dependencies** without a clear reason — the stack is intentionally minimal
|
|
- **No JavaScript** — all interactivity through Leptos/WASM
|
|
- **Keep components in `routes/`** unless genuinely reusable across multiple pages
|
|
- **New DB tables** require a migration file in `migrations/`
|
|
- **External API calls** (e.g., shutters) go through server functions, never from WASM directly
|
|
- **Do not add features** beyond what is asked; this is a personal tool, not a framework
|