create-aziz-app 2.0.15 → 3.0.0

package/template/docs/HOW-IT-WORKS.md

@@ -1,362 +0,0 @@
-# How It Works
-
-## System Architecture
-
-Aziz App has three main systems working together:
-
-1. **Auto-Import System** - Automatically generates script tags
-2. **Live Reload System** - Automatically refreshes browser on changes
-3. **Routing System** - File-based routing with auto-registration
-
-## 1. Auto-Import System
-
-### Files Involved:
-- `scripts/generate-imports.js` - Scans folders and generates script tags
-- `app.html` - Contains the generated script tags
-- `app.config.js` - Configuration (auto-generated)
-
-### How It Works:
-
-```
-1. Dev server starts
-2. Runs generate-imports.js
-3. Scans: api/, components/, pages/
-4. Generates <script> tags for each file
-5. Updates app.html (body section only)
-6. Browser loads all scripts
-```
-
-### What Gets Generated:
-
-```html
-<!-- Load core modules -->
-<script type="text/babel" src="modules/router.js"></script>
-<script type="text/babel" src="modules/state.js"></script>
-<script type="text/babel" src="modules/api.js"></script>
-
-<!-- Load API routes -->
-<script type="text/babel" src="api/hello.js"></script>
-
-<!-- Load shared components -->
-<script type="text/babel" src="components/Navbar.jsx"></script>
-
-<!-- Load pages -->
-<script type="text/babel" src="pages/Home.jsx"></script>
-
-<!-- Start the app -->
-<script type="text/babel">
-    startApp();
-</script>
-```
-
-### When It Runs:
-
-- **On server start** - Initial generation
-- **On file change** - When .js/.jsx files are added/removed/renamed
-- **Manual** - Run `npm run build`
-
-### What It Doesn't Touch:
-
-- `<head>` section - Styles, meta tags, live-reload script
-- Files outside watched folders
-- Non-.js/.jsx files
-
-## 2. Live Reload System
-
-### Files Involved:
-- `scripts/live-reload-client.js` - Browser-side WebSocket client
-- `scripts/dev-server.js` - Server-side WebSocket server + file watcher
-- `app.html` - Loads the client script
-
-### How It Works:
-
-```
-1. Browser loads app.html
-2. app.html includes live-reload-client.js
-3. Client creates WebSocket connection
-4. Server watches: api/, components/, pages/, modules/, styles/
-5. File changes detected
-6. Server sends "reload" message via WebSocket
-7. Client receives message
-8. Browser reloads page
-```
-
-### Architecture:
-
-```
-┌─────────────┐                    ┌─────────────┐
-│   Browser   │                    │ Dev Server  │
-│             │                    │             │
-│  live-      │  WebSocket         │  File       │
-│  reload-    │◄──────────────────►│  Watcher    │
-│  client.js  │  "reload" message  │             │
-│             │                    │             │
-└─────────────┘                    └─────────────┘
-       │                                  │
-       │ Reload page                      │ Detects changes
-       ▼                                  ▼
-   app.html                         api/, pages/, etc.
-```
-
-### Why WebSocket?
-
-- **Reliable** - Bidirectional, persistent connection
-- **Fast** - Instant notifications
-- **Simple** - No external dependencies
-- **No caching** - Script is always loaded, not injected
-
-### Connection States:
-
-1. **Connecting** (gray) - Initial connection
-2. **Connected** (green) - Ready, watching for changes
-3. **Reloading** (blue) - Change detected, reloading
-4. **Disconnected** (orange) - Connection lost, reconnecting
-5. **Offline** (red) - Max reconnection attempts reached
-
-## 3. Routing System
-
-### Files Involved:
-- `modules/router.js` - Core routing engine
-- `pages/*.jsx` - Page components
-- `app.html` - Root element (#root)
-
-### How It Works:
-
-```
-1. Browser loads all page files
-2. Each page defines a function: HomePage(), AboutPage(), etc.
-3. startApp() calls autoRegisterPages()
-4. Scans window for functions ending with "Page"
-5. Registers: HomePage → "home", AboutPage → "about"
-6. URL hash changes: #/about
-7. Router finds AboutPage() function
-8. Renders it into #root
-```
-
-### Auto-Registration:
-
-```javascript
-// In pages/About.jsx
-function AboutPage() {
-    return <div><h1>About</h1></div>;
-}
-
-// Router automatically does:
-routes["about"] = AboutPage;
-```
-
-### Manual Registration (Optional):
-
-```javascript
-// For custom route names
-registerPage("user-profile", UserProfilePage);
-```
-
-## How They Work Together
-
-### Startup Sequence:
-
-```
-1. Run: npm run dev
-2. Dev server starts
-3. Runs generate-imports.js
-4. Scans folders, updates app.html
-5. Starts HTTP server on port 3000
-6. Starts WebSocket server
-7. Starts file watchers
-8. Ready! ✅
-```
-
-### Browser Load Sequence:
-
-```
-1. Browser requests http://localhost:3000/
-2. Server sends app.html
-3. Browser loads:
-   - styles/globals.css
-   - scripts/live-reload-client.js (connects to WebSocket)
-   - Babel standalone
-   - modules/router.js, state.js, api.js
-   - api/*.js
-   - components/*.jsx
-   - pages/*.jsx
-4. Calls startApp()
-5. Auto-registers pages
-6. Renders current route
-7. Done! ✅
-```
-
-### File Change Sequence:
-
-```
-1. Developer edits pages/Home.jsx
-2. File watcher detects change
-3. Debounce timer starts (500ms)
-4. Timer expires
-5. Runs generate-imports.js
-6. Updates app.html
-7. Sends "reload" via WebSocket
-8. Browser receives message
-9. Browser reloads
-10. New version loads
-11. Done! ✅
-```
-
-### CSS Change Sequence (Faster):
-
-```
-1. Developer edits styles/globals.css
-2. File watcher detects change
-3. Debounce timer starts (300ms)
-4. Timer expires
-5. Skips generate-imports (not needed for CSS)
-6. Sends "reload" via WebSocket
-7. Browser reloads
-8. Done! ✅
-```
-
-## File Organization
-
-### What Goes Where:
-
-```
-template/
-├── app.html              # Main HTML (auto-generated scripts)
-├── modules/              # Core system (don't modify)
-│   ├── router.js         # Routing + rendering
-│   ├── state.js          # State management
-│   └── api.js            # API system
-├── scripts/              # Build tools (don't modify)
-│   ├── dev-server.js     # Dev server + WebSocket
-│   ├── generate-imports.js  # Auto-import generator
-│   └── live-reload-client.js  # Browser WebSocket client
-├── api/                  # Your API routes (auto-imported)
-├── components/           # Your components (auto-imported)
-├── pages/                # Your pages (auto-imported)
-└── styles/               # Your styles (watched for changes)
-```
-
-### What You Modify:
-
-- ✅ `api/` - Add your API routes
-- ✅ `components/` - Add your components
-- ✅ `pages/` - Add your pages
-- ✅ `styles/` - Add your styles
-- ❌ `modules/` - Core system
-- ❌ `scripts/` - Build tools
-- ⚠️ `app.html` - Only modify `<head>` section
-
-## Key Concepts
-
-### 1. Auto-Import is Automatic
-
-You don't need to:
-- Add `<script>` tags manually
-- Run build commands after creating files
-- Restart the dev server
-
-Just create a file and save it!
-
-### 2. Live Reload is Always On
-
-The `live-reload-client.js` script:
-- Is always loaded (in `<head>`)
-- Only runs on localhost
-- Connects automatically
-- Reconnects if disconnected
-- Safe for production (does nothing)
-
-### 3. Pages Auto-Register
-
-You don't need to:
-- Call `registerPage()` (optional)
-- Import pages manually
-- Configure routes
-
-Just name your function `YourNamePage()` and it works!
-
-### 4. Everything is Watched
-
-The dev server watches:
-- `api/` - API routes
-- `components/` - Components
-- `pages/` - Pages
-- `modules/` - Core modules
-- `styles/` - Stylesheets
-
-Changes trigger:
-- Import regeneration (for .js/.jsx)
-- Browser reload (for everything)
-
-## Performance Optimizations
-
-### 1. Debouncing
-
-Prevents multiple rapid reloads:
-- CSS changes: 300ms delay
-- JS/JSX changes: 500ms delay
-
-### 2. Selective Regeneration
-
-- CSS changes: Skip import generation
-- JS/JSX changes: Regenerate imports
-
-### 3. WebSocket Efficiency
-
-- Single persistent connection
-- Minimal message size ("reload")
-- Automatic cleanup on disconnect
-
-### 4. Smart Watching
-
-- Only watches specific folders
-- Ignores non-code files
-- Recursive: false (performance)
-
-## Troubleshooting
-
-### Import Generation Issues
-
-**Problem:** New file not showing up
-
-**Check:**
-1. File is in `api/`, `components/`, or `pages/`
-2. File ends with `.js` or `.jsx`
-3. Dev server is running
-4. Check terminal for errors
-
-**Solution:** Run `npm run build` manually
-
-### Live Reload Issues
-
-**Problem:** Changes not showing
-
-**Check:**
-1. Indicator is green (✅ Live Reload)
-2. Dev server is running
-3. File was saved
-4. Browser console for errors
-
-**Solution:** Click indicator to manually reload
-
-### Routing Issues
-
-**Problem:** Page shows 404
-
-**Check:**
-1. Function name ends with "Page"
-2. File is loaded (check app.html)
-3. Browser console shows auto-registration
-4. URL hash is correct (#/about)
-
-**Solution:** Add manual registration
-
-## Summary
-
-Aziz App combines three systems:
-
-1. **Auto-Import** - Scans folders, generates script tags
-2. **Live Reload** - WebSocket connection, file watching
-3. **Auto-Registration** - Scans functions, registers routes
-
-Together, they provide a seamless development experience with zero configuration!