@isthatuzii/create-nano-app/templates/solid-js-ts/docs/CLAUDE.md

Desktop application scaffolding tool for the Nano Framework

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**Nano Framework** - A minimal, professional desktop application framework built with Rust backend and SolidJS frontend with TypeScript. Uses Axum server with `tao` + `wry` for the desktop window, serving SolidJS application built with Vite. Configurable via `nano.config.json`. The project uses Rust 2024 edition.

## Common Commands

### Building and Running
- `cargo build` - Build the Rust backend
- `cargo run` - Build and run the desktop application (starts HTTP server and opens desktop window)
- `cargo check` - Check the project for errors without building
- `cargo build --release` - Build optimized release version

### Frontend Development
- `npm install` - Install SolidJS and TypeScript dependencies
- `npm run dev` - Start Vite development server
- `npm run build` - Build SolidJS app for production (outputs to `dist/`) with TypeScript compilation
- `npm run serve` - Preview production build

### Nano Framework Commands (Combined)
- `npm run nano` - Build frontend and run application (same as `npm run nano:dev`)
- `npm run nano:dev` - Build frontend and run application in development
- `npm run nano:hot` - Run with hot reload (starts both Vite dev server and Cargo watch)
- `npm run nano:release` - Build optimized release and copy executable to `nano-portable-release/`
- `npm run nano:portable` - Same as `nano:release` - build portable executable

### Testing and Quality
- `cargo test` - Run Rust tests
- `cargo clippy` - Run Rust linter for code quality suggestions
- `cargo fmt` - Format Rust code according to standards
- `tsc -b` - TypeScript type checking (run automatically during build)

## Project Structure

```
nano-framework/
├── Cargo.toml                    # Rust project manifest and dependencies
├── package.json                  # SolidJS frontend dependencies
├── vite.config.js                # Main Vite build configuration
├── vite.template.config.js       # Template UI Vite configuration
├── index.html                    # Main UI entry point HTML
├── template.html                 # Template UI entry point HTML
├── nano.config.json              # Nano Framework configuration
├── framework.md                  # Development pattern reference
├── CLAUDE.md                     # This file
├── dist/                         # Main UI build output (npm run build)
├── template-dist/                # Template UI build output (npm run template:build)
├── nano-portable-release/        # Portable executable output
├── src-nano/                     # Rust backend source code
│   ├── main.rs                   # Entry point with config loading and window creation
│   ├── server.rs                 # Axum HTTP server with embedded static assets
│   ├── config.rs                 # Configuration system with portable config paths
│   └── modules/                  # Rust backend modules
│       ├── mod.rs                # Module declarations
│       └── system.rs             # System API with structured ApiResponse pattern
├── src/                          # Main SolidJS UI source code (TypeScript)
│   ├── index.tsx                 # SolidJS app entry point
│   ├── App.tsx                   # Main SolidJS component
│   ├── App.functions.ts          # App-level business logic
│   ├── api/                      # Frontend API abstraction layer
│   │   ├── api.ts                # Main API module export
│   │   └── modules/              # Feature-specific API modules
│   │       └── system.module.ts  # System API calls
│   └── components/               # SolidJS components following 3-file pattern
│       └── greeting/
│           ├── GreetingPanel.tsx
│           ├── GreetingPanel.functions.ts
│           └── GreetingPanel.css
└── target/                       # Rust build artifacts
```

## Architecture Notes

### Backend (Rust) - Configurable HTTP Server + Desktop Window
- **Configuration**: `nano.config.json` controls all window properties, server settings, and app metadata
- **HTTP Server**: Axum framework with embedded static assets using `include_dir!` macro
- **Desktop Window**: Fully configurable via config - size, position, decorations, fullscreen, etc.
- **Portable Mode**: Embedded assets eliminate need for separate `dist/` folder in release builds
- **API Routes**: `/api/system-info` (GET), `/api/notify` (POST), `/api/greet` (GET with query params)
- **Module System**: `src-nano/modules/system.rs` contains business logic with `ApiResponse<T>` wrapper
- **Error Handling**: Functions return `Result<ApiResponse<T>, String>`, HTTP handlers convert to StatusCode
- **Config System**: Smart config path detection (temp dir → executable dir → current dir)
- **Cleanup System**: Automatic cleanup of temporary files on application exit

### Frontend - SolidJS + TypeScript + Vite
- **Framework**: SolidJS with reactive signals and component architecture
- **Language**: TypeScript for type safety with strict compiler options
- **Build System**: Vite for fast development and optimized production builds
- **Component Pattern**: Three-file pattern (.tsx, .functions.ts, .css)
- **API Communication**: Centralized API layer with modular organization using fetch()
- **Development**: Hot reload via Vite dev server, production builds to `dist/`

### Configuration System (`nano.config.json`)
- **Window Config**: title, dimensions, min/max sizes, fullscreen, maximized, decorations, transparency
- **Server Config**: host, port, auto-start settings
- **Development Config**: devtools, hot reload, auto-restart options  
- **App Metadata**: name, version, description
- **Portable Storage**: Smart config path detection for portable deployments
- **Auto-generation**: Creates default config if none exists, with fallback error handling

## API Pattern

### Rust Backend (`src/modules/system.rs`)
```rust
#[derive(Debug, Serialize, Deserialize)]
pub struct ApiResponse<T> {
    pub success: bool,
    pub data: Option<T>,
    pub message: Option<String>,
}
```

### HTTP Routes (`src/server.rs`)
- GET `/api/system-info` → `system::get_system_info()`
- POST `/api/notify` → `system::send_notification(NotificationRequest)`
- GET `/api/greet?name=value` → `system::greet(Option<String>)`

### Frontend API (`src/api/`)
- `api.ts` - Main export with module imports
- `modules/system.module.ts` - System-specific API calls using fetch()

## Configuration File Structure

```json
{
  "window": {
    "title": "Nano Framework",
    "width": 1200,
    "height": 800,
    "minWidth": 400,
    "minHeight": 300,
    "resizable": true,
    "maximized": false,
    "fullscreen": false,
    "alwaysOnTop": false,
    "decorations": true,
    "transparent": false,
    "center": true
  },
  "server": {
    "host": "127.0.0.1",
    "port": 3030,
    "autoStart": true
  },
  "development": {
    "devtools": false,
    "hotReload": true
  }
}
```

## Dependencies

### Rust Dependencies
- `tokio = { version = "1.0", features = ["full"] }` - Async runtime
- `axum = "0.7"` - Web framework for API and file serving
- `tower = "0.4"` - Middleware tower
- `tower-http = { version = "0.5", features = ["fs", "cors"] }` - File serving and CORS
- `serde = { version = "1.0", features = ["derive"] }` - JSON serialization for config and API
- `serde_json = "1.0"` - JSON serialization
- `tao = "0.16"` - Cross-platform windowing with full configuration support
- `wry = "0.24"` - Cross-platform WebView
- `whoami = "1.4"` - System information
- `fs_extra = "1.3"` - File system utilities
- `include_dir = "0.7"` - Compile-time directory embedding for portable builds
- `mime_guess = "2.0"` - MIME type detection for static file serving

### Frontend Dependencies (package.json)
- `solid-js = "^1.8.0"` - Reactive UI framework
- `lucide-solid = "^0.537.0"` - Icon library for SolidJS
- `typescript = "^5.0.0"` - TypeScript compiler with strict type checking
- `vite = "^5.0.0"` - Fast build tool and dev server
- `vite-plugin-solid = "^2.8.0"` - SolidJS integration for Vite
- `@types/node = "^20.0.0"` - Node.js type definitions
- `concurrently = "^9.1.2"` - Run multiple commands concurrently (for hot reload setup)

## Key Architecture Decisions

1. **SolidJS + Vite Stack**: Modern reactive frontend with fast development experience
2. **Configuration-Driven**: All window and app settings controlled by `nano.config.json`
3. **Three-File Component Pattern**: .jsx (UI), .functions.js (logic), .css (styles) separation
4. **Embedded Assets**: Static assets compiled into binary for portable single-file distribution
5. **Portable Configuration**: Smart config path detection (temp → executable → current directory)
6. **Local Server + Desktop Window**: HTTP API server with native desktop window (tao + wry)
7. **VS Code Theme**: Professional dark theme with consistent design language
8. **Centralized API**: Clean abstraction layer between frontend and backend using fetch()
9. **Template System**: Separate UI template system for demos and rapid prototyping
10. **Development-Friendly**: Hot reload, devtools support, automatic config generation

## Development Workflow

### Quick Start (Recommended)
1. `npm run nano` - Builds frontend and starts application in one command
2. `npm run nano:hot` - Hot reload development with concurrent Vite dev server and Cargo watch

### Manual Development Mode
1. `npm run build` - Build SolidJS app to `dist/` 
2. `cargo run` - Start Rust backend serving embedded assets and open window

### Template UI Development
1. `npm run template` - Start template UI development server on port 1421
2. `npm run template:nano` - Build template UI and run with Nano

### Production Build
1. `npm run nano:release` - Complete build pipeline:
   - Builds optimized SolidJS app
   - Builds optimized Rust backend with embedded assets
   - Copies executable to `nano-portable-release/` directory
   - Result: Single portable executable with no external dependencies

### Cargo Build Optimizations
Release builds use aggressive size optimization:
- `strip = true` - Remove debug symbols
- `opt-level = "z"` - Optimize for size
- `lto = true` - Link Time Optimization
- `codegen-units = 1` - Better optimization
- `panic = "abort"` - Reduce binary size