# 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`.