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

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:

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.

5.3 KiB Raw Blame History