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 current implementation plan.

📁 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 utilities & configurations
│   │   ├── config.rs     # Configuration parsed from environment variables (.env)
│   │   ├── database.rs   # MongoDB initialization and connections
│   │   └── errors.rs     # AppError implementation wrapping custom responses
│   ├── auth/             # AUTH USE-CASE (Users, Passwords, Session cookies)
│   │   ├── extractors.rs # Native Axum extractors for authentication state
│   │   ├── handlers.rs   # Login and registration endpoint handlers
│   │   ├── models.rs     # User database schemas
│   │   └── repository.rs # MongoDB operations for authentication
│   ├── tasks/            # TASKS USE-CASE (CRUD tasks, dashboard view)
│   │   ├── handlers.rs
│   │   ├── models.rs
│   │   └── repository.rs
│   ├── developers/       # DEVELOPERS USE-CASE (HTMX-based assignee autocomplete query)
│   │   ├── handlers.rs
│   │   ├── models.rs
│   │   └── repository.rs
│   ├── main_view/        # STATIC VIEWS & GLOBAL ASSET ENDPOINTS
│   │   └── mod.rs        # Serves index.html, static css, and static javascript files
│   ├── components/       # WIKI & INTERACTIVE DESIGN SYSTEM
│   │   ├── mod.rs        # Wiki routing table
│   │   └── handlers.rs   # Handlers serving reference pages
│   └── input.css         # Tailwind CSS v4 custom theme mappings and custom scrollbars
├── static/               # Raw assets compiled/included in compilation
│   ├── tailwind.css      # Output/input css rules
│   └── js/
│       ├── components.js # Main component event delegation system
│       └── combobox.js   # HTMX-friendly autocomplete combobox scripts
└── templates/            # Raw HTML template layout files (Askama templates)
    ├── base.html         # Global HTML layout wrapper (injects headers, navigation)
    ├── auth/             # Login / registration markup
    ├── tasks/            # Task management layouts
    ├── main_view/        # Landing page layout
    └── components/       # Component Wiki pages (Buttons, Modals, Comboboxes, etc.)

Route Composition

In src/main.rs, routers from each vertical module are instantiated and merged using Axum's .merge() method:

let app = Router::new()
    .merge(main_view::router())
    .merge(components::router())
    .merge(auth::router())
    .merge(tasks::router())
    .merge(developers::router())
    .with_state(state);

🛠️ 2. Core Technical Dependencies

Web Server: axum = "0.8.9" — Native asynchronous routing with type-safe extractor traits.
Database: mongodb = "3.7.0" — Offical Rust driver, using bson = "3.1.0" with serde serialization.
Template Rendering: askama = "0.16.0" — Compile-time type safety; views are compiled directly into the binary.
Styling Engine: Tailwind CSS (v4) — Uses native CSS variables and @import "tailwindcss" rather than complex configuration JSONs.
Security & JWT: jsonwebtoken = "10.4.0" (via rust_crypto backend) + bcrypt = "0.19.1" for password hashing. JWTs are stored in secure HttpOnly cookie wrappers.

🎨 3. JavaScript & HTML Event Delegation Contract

Rather than attaching individual event listeners to elements upon page load (which degrades performance and fails when elements are swapped dynamically via HTMX), Stick uses document-level event delegation via static/js/components.js and static/js/combobox.js.

Active Binding Attributes & Hooks

To make components function, developers must preserve specific HTML attributes and class structures that JavaScript expects:

Component Type	JavaScript Trigger / Hook	Expected Target / Functional Structure
Modal / Dialog	`[data-modal-target="id"]`	`.modal-dialog` (wrapper), `.modal-backdrop`, `.modal-close`
Sheets / Drawers	`[data-sheet-target="id"]`	`.sheet-dialog` (wrapper), `.sheet-backdrop`, `.sheet-close`
Custom Dropdowns	`.dropdown-trigger`	`.dropdown-menu` (container), `.dropdown-content`
Interactive Tabs	`[data-tab-target="pane-id"]`	`[data-tab-group="group-name"]` on buttons & content wrappers
Accordions	`.accordion-trigger`	`.accordion-item` (container), `.accordion-content`, `.accordion-chevron`
Custom Select	`.select-trigger`	`.custom-select` (container), `.select-popover`, `.select-item`, `.select-value`
Autocomplete Combobox	`.combobox-input`	`.autocomplete-combobox` (container), `.combobox-results`, `.combobox-value`

Any customized styling classes (colors, borders, rounded corners) can be freely added or changed. However, the core class naming hierarchy listed above must remain intact to preserve interaction animations and keyboard controls.

🧩 4. Proposed Scalability & Code Reuse Solutions

Solution 1: Askama Macros (Selected Demo)

Consolidate UI components into a global macros registry template.

Pros: Safe compilation (missing variables or typos are checked at build time), zero performance cost.
Cons: Complex child structures (e.g. slots or dynamic SVG parameters) require passing strings/blocks, which can look verbose.

Solution 2: CSS Component Classes

Define custom components in src/input.css using Tailwind CSS v4's components layer (e.g. @apply btn btn-primary).

Pros: Clear, descriptive markup syntax; easily consumable by pure front-end web developers.
Cons: Partially moves styling definitions out of HTML files and back into stylesheet files.

Solution 3: Rust Struct Components

Represent reusable buttons, grids, or select widgets as Rust structs that implement Askama's Template trait.

Pros: Advanced data-driven structures and type constraints managed entirely in Rust code.
Cons: Visual updates require recompiling Rust binaries, which limits swift CSS experimentation.

🚀 5. Action Plan: Askama Macros Implementation

We are implementing a demo showcasing Askama Macros in a new git branch:

Branch Setup: Create demo/askama-macros.
Define Macros: Create templates/components/macros.html to define reusable snippets for:
- Button: Primary, secondary, outline, destructive, status indicators.
- Modal: Accessibility markup, background overlays, closing controls.
- Autocomplete Combobox: Dynamic HTMX data queries and search hooks.

Refactor Views: Replace manual HTML blocks in dashboard.html with:

{% import "components/macros.html" as ui %}
{{ ui::button("Submit", "primary") }}

7.9 KiB Raw Blame History