Gitea Bootstrap
105 lines
5.0 KiB
Markdown
105 lines
5.0 KiB
Markdown
# Mountainridge Leptos + Matterhorn Template – AI Coding Agent Instructions
|
||
|
||
**Purpose**
|
||
This is the **single source of truth**.
|
||
Every AI coding agent **must** follow these rules exactly.
|
||
Any deviation breaks the template contract, Matterhorn codegen pipeline, Keycloak integration, Tauri desktop build, or
|
||
embedding mechanism.
|
||
|
||
## Core Overview
|
||
|
||
- Rust + **Leptos** (latest stable) **CSR-only** reactive web application
|
||
- Data layer: **Matterhorn entities** (JSON-schema driven)
|
||
- Styling: **Standalone TailwindCSS** + **DaisyUI** components (no `tailwind.config.js`)
|
||
- Corporate theme: **"mountainridge"** (locked in `styles.css`)
|
||
- Authentication: **Keycloak OAuth2**
|
||
- Desktop variant: enabled with feature flag **`desktop`** (uses Tauri)
|
||
|
||
## Agent Tool Usage (Mandatory)
|
||
|
||
All agents have the following **injected tools** and **must** use them exclusively:
|
||
|
||
- `mridge_craft_add_matterhorn_entity` – add new Matterhorn data entities
|
||
- `mridge_craft_build` – full build / serve / watch / desktop package (Cargo + Trunk + Tauri)
|
||
- Git commit & push
|
||
- Create issues for the craft
|
||
|
||
**Never** execute raw shell commands (`cargo`, `trunk`, `git`, `tauri`, etc.).
|
||
All GitHub operations are fully wrapped — repo details are irrelevant.
|
||
|
||
## Project Structure & Immutable Rules
|
||
|
||
| Path | Purpose | Modification Rules |
|
||
|------------------------|------------------------------------------------------------------------|---------------------------------------------------------------------|
|
||
| `./assets/` | Extra CSS, fonts, images, static assets | Add only |
|
||
| `./schemas/` | JSON schemas for Matterhorn entities | **Never edit manually** – use add-entity tool |
|
||
| `./src/codegen/` | **Auto-generated only** (structs, API client, helpers) | **Never touch** |
|
||
| `./src/codegen/api.rs` | Generated type-safe Matterhorn client (list/read/create/update/delete) | Auto-regenerated |
|
||
| `./src/components/` | All custom Leptos components | Free (PascalCase.rs) |
|
||
| `./src/main.rs` | Router + Keycloak token loader + BaseLayout | **Only edit the router section**. Never remove auth/base wrappers |
|
||
| `./src/styles.css` | Global stylesheet + full "mountainridge" DaisyUI theme | Extend only – never overwrite theme block |
|
||
| `./index.html` | HTML entry point (Trunk) | **Immutable section** (see below) – only meta/title changes allowed |
|
||
|
||
## Immutable / Protected Elements (Never Change)
|
||
|
||
**`./index.html`** – these exact lines **must remain untouched** (required for Trunk, favicon, public URL, and config
|
||
injection):
|
||
|
||
```html
|
||
|
||
<link data-trunk rel="copy-dir" href="./assets" data-trunk-target-path="/assets"/>
|
||
<link rel="icon" href="./assets/mridge-craft-icon.webp" type="image/webp"/>
|
||
<base data-trunk-public-url/>
|
||
<script>
|
||
window.__embeddedAppConfig = {};
|
||
window.addEventListener('message', function (e) {
|
||
if (e.data.type === 'APP_CONFIG') {
|
||
window.__embeddedAppConfig = e.data;
|
||
}
|
||
}, {once: true});
|
||
</script>
|
||
```
|
||
|
||
**`./src/styles.css`** – never delete or replace the `"daisyui/theme"` block.
|
||
|
||
**`./src/main.rs`** – never remove `<AuthProvider>`, Keycloak init, or `<BaseLayout>`.
|
||
|
||
**`./src/codegen/`** – generated; never manual edits.
|
||
|
||
## Authentication – Keycloak OAuth2
|
||
|
||
`main.rs` contains the protected Keycloak token loader:
|
||
|
||
- **Web/iframe mode** (default): token injected via `postMessage` (uses `window.__embeddedAppConfig`)
|
||
- **Desktop mode** (`--features desktop`): full Keycloak login flow + Tauri
|
||
|
||
**Rule:** Never remove, refactor, or bypass any auth-related wrapper.
|
||
|
||
## Critical Rules for Coding Agents
|
||
|
||
1. **Data Dependencies**
|
||
Always use `mridge_craft_add_matterhorn_entity` for any new or modified Matterhorn model.
|
||
|
||
2. **Routing**
|
||
Add new routes **only** inside the existing `<Router>` block in `main.rs`.
|
||
Preserve all auth/protected-route wrappers.
|
||
|
||
3. **Styling**
|
||
Prefer DaisyUI classes everywhere.
|
||
Tailwind is standalone — no config file.
|
||
Never override the "mountainridge" theme.
|
||
|
||
4. **Data Fetching (CSR-only)**
|
||
All operations **must** use the generated `codegen::api::*` client.
|
||
No Leptos server functions.
|
||
|
||
5. **Building & Testing**
|
||
Every compile, dev server, release, or Tauri desktop build → use `mridge_craft_build`.
|
||
|
||
## Standard Agent Workflow
|
||
|
||
1. Need new data entity? → use 'mrdige_add-entity' skill
|
||
2. Create component(s) in `./src/components/`
|
||
3. Add route in `main.rs` (inside router, respect auth)
|
||
4. Commit/push via git tools or create issue if needed
|