89 lines
5.3 KiB
Markdown
89 lines
5.3 KiB
Markdown
# Detailed Project Architecture & Design System Reference Manual
|
|
|
|
This document provides a comprehensive technical overview of the **Stick** template, detailing its vertical structure, core dependencies, event delegation contracts, component reuse solutions, and our completed implementation history.
|
|
|
|
---
|
|
|
|
## 📁 1. Project Directory Layout & Vertical Architecture
|
|
|
|
Unlike traditional MVC applications that split code horizontally (e.g., separating all controllers, all models, and all views), Stick is organized by **vertical features (use-cases)**. Every business module contains its own Rust handler logic, database schemas, repository queries, and custom routing.
|
|
|
|
### Directory Mapping
|
|
```text
|
|
stick/
|
|
├── Cargo.toml # Rust dependency management
|
|
├── package.json # Node assets configuration (optional tooling)
|
|
├── src/
|
|
│ ├── main.rs # Core composition, shared state, and route merging
|
|
│ ├── common/ # Shared features (errors, database, settings)
|
|
│ ├── auth/ # AUTH USE-CASE (Users, Passwords, Session cookies)
|
|
│ ├── tasks/ # TASKS USE-CASE (CRUD tasks, dashboard view)
|
|
│ ├── developers/ # DEVELOPERS USE-CASE (Assignee autocomplete query)
|
|
│ ├── main_view/ # STATIC VIEWS & GLOBAL ASSET ENDPOINTS
|
|
│ ├── components/ # WIKI & INTERACTIVE DESIGN SYSTEM
|
|
│ └── input.css # Tailwind CSS v4 custom theme mappings and custom scrollbars
|
|
├── static/ # Raw assets compiled/included in compilation
|
|
└── templates/ # Raw HTML template layout files (Askama templates)
|
|
├── base.html # Global HTML layout wrapper
|
|
├── auth/ # Login / registration markup (refactored to macros)
|
|
├── tasks/ # Task management layouts (refactored to macros)
|
|
├── main_view/ # Landing page layout
|
|
└── components/ # Component Wiki pages (refactored to macros)
|
|
```
|
|
|
|
---
|
|
|
|
## 🛠️ 2. Core Technical Dependencies
|
|
|
|
* **Web Server**: `axum = "0.8.9"`
|
|
* **Database**: `mongodb = "3.7.0"` (using `bson = "3.1.0"`)
|
|
* **Template Rendering**: `askama = "0.16.0"`
|
|
* **Styling Engine**: Tailwind CSS (v4)
|
|
* **Security & JWT**: `jsonwebtoken = "10.4.0"` + `bcrypt = "0.19.1"`
|
|
|
|
---
|
|
|
|
## 🎨 3. JavaScript & HTML Event Delegation Contract
|
|
|
|
Stick uses **document-level event delegation** via `components.js` and `combobox.js`.
|
|
|
|
| Component Type | JavaScript Trigger / Hook | Expected Target / Functional Structure |
|
|
| :--- | :--- | :--- |
|
|
| **Modal / Dialog** | `[data-modal-target="id"]` | `.modal-dialog`, `.modal-backdrop`, `.modal-close` |
|
|
| **Sheets / Drawers** | `[data-sheet-target="id"]` | `.sheet-dialog`, `.sheet-backdrop`, `.sheet-close` |
|
|
| **Custom Dropdowns** | `.dropdown-trigger` | `.dropdown-menu`, `.dropdown-content` |
|
|
| **Interactive Tabs**| `[data-tab-target="pane-id"]` | `[data-tab-group="group-name"]` on buttons & content wrappers |
|
|
| **Accordions** | `.accordion-trigger` | `.accordion-item`, `.accordion-content`, `.accordion-chevron` |
|
|
| **Custom Select** | `.select-trigger` | `.custom-select`, `.select-popover`, `.select-item`, `.select-value` |
|
|
| **Autocomplete Combobox**| `.combobox-input` | `.autocomplete-combobox`, `.combobox-results`, `.combobox-value` |
|
|
|
|
---
|
|
|
|
## 🚀 4. Completed Askama Macros Refactoring (Completed Tasks)
|
|
We successfully migrated all UI components to type-safe templates on the branch `demo/askama-macros`.
|
|
|
|
### A. Phase 1: Form Inputs & Basic Controls
|
|
Consolidated basic form controls into [templates/components/macros.html](file:///home/enciphered/Desktop/Code/stick/templates/components/macros.html):
|
|
* `button`: Unified visual styles with custom icon inclusion (`label|safe`).
|
|
* `text_input` & `textarea`: Standardized label, placeholder, name, and value variables.
|
|
* `select_open`, `select_item`, `select_close`: Structural paired macros bypassing Askama's lack of template slots.
|
|
* `toggle_switch` & `checkbox`: Standardized custom check styles.
|
|
* `range_slider` & `datepicker` & `timepicker`: Popover-based pickers integration.
|
|
|
|
### B. Phase 2: Layout & Overlays (Paired Macro Pattern)
|
|
* `modal_open` & `modal_close`: Paired overlay layout block wrapping.
|
|
* `sheet_open` & `sheet_close`: Paired slide-out detail drawers.
|
|
* `tabs_header_open`, `tab_trigger`, `tabs_header_close`, `tabs_content_open`, `tab_pane_open`, `tab_pane_close`, `tabs_content_close`: Flexible dynamic tabs.
|
|
* `accordion_open` & `accordion_close`: Paired collapsible vertical containers.
|
|
|
|
### C. Phase 3: Global Cleanup & Integration
|
|
* Refactored the Component Wiki demo views to use all new macros (`buttons.html`, `inputs.html`, `toggles.html`, `date_time.html`, `modals.html`, `sheets.html`, `tabs_accordion.html`).
|
|
* Refactored the authentication views (`login.html` and `register.html`) to use unified `text_input` and `button` macros.
|
|
* Refactored the rest of the Task Dashboard (`dashboard.html`) to use macro inputs for the task name and task description fields.
|
|
|
|
---
|
|
|
|
## 🧪 5. Testing & Verification Results
|
|
* **Compile-time Check**: Successfully ran `cargo check` to ensure all macro scopes, imports, and variables are resolved at compilation time.
|
|
* **Docker Container Status**: Image rebuilt successfully. Running on network port `3009`.
|