odac 1.0.1 → 1.2.0

package/docs/backend/01-overview/03-development-server.md

@@ -1,79 +1,72 @@
-## 🚀 Development Server
+## 🚀 CLI Commands & Deployment
 
-Odac provides a built-in development server that allows you to test your website locally without running the full Odac server infrastructure.
+ODAC comes with a powerful CLI to manage your project's lifecycle, from development to production.
 
-### Quick Start
+### Development Mode (`dev`)
 
-Navigate to your website directory and run one of these commands:
+Start the development server with **hot-reloading** and **automatic Tailwind CSS compilation**:
 
 ```bash
 # Using npm script
-npm start
+npm run dev
 
-# Using Odac directly
-odac framework run
+# Using ODAC directly
+npx odac dev
 ```
 
-Both commands will start a local development server on port `1071` by default, and your website will be accessible at `http://127.0.0.1:1071`.
+**What it does:**
+- Starts the Node.js server (default port `1071`).
+- **Zero-Config Tailwind:** Automatically watches and compiles your classes.
+- **Watch Mode:** Recompiles CSS instantly when you change files.
 
-### Custom Port
+### Production Build (`build`)
 
-You can specify a custom port by adding it as an argument:
+Prepare your application for production deployment. This command compiles and modifies your assets for optimal performance.
 
 ```bash
-# Using npm script with custom port
-npm start 8080
+# Using npm script
+npm run build
 
-# Using Odac directly with custom port
-odac framework run 8080
+# Using ODAC directly
+npx odac build
 ```
 
-This will start the server on your specified port (e.g., `http://127.0.0.1:8080`).
-
-### Development vs Production
+**What it does:**
+- **Compiles CSS:** Generates the final `public/assets/css/app.css`.
+- **Minification:** Compresses the CSS to reduce file size.
+- **One-off Run:** Runs once and exits. Does not start a server.
 
-The development server (`npm start`) is designed for:
+### Production Server (`start`)
 
-- **Local testing** and development only
-- **Quick iteration** without server setup
-- **Debugging** your application logic
-- **Testing on localhost** (127.0.0.1)
-
-**Important**: The development server does NOT provide DNS, SSL, or other production services.
-
-For production deployment with full Odac server features, create your website using:
+Start the application in **production mode**. This is the command you should run on your server or hosting platform.
 
 ```bash
-odac web create
-```
+# Using npm script
+npm start
 
-This registers your website with the Odac server and provides:
+# Using ODAC directly
+npx odac start
+```
 
-- **Automatic SSL** certificate management
-- **DNS handling** for your domain
-- **Multi-domain hosting** capabilities
-- **Process monitoring** and auto-restart
-- **Production optimizations** and security
+**What it does:**
+- Sets `NODE_ENV=production`.
+- Starts the Node.js server.
+- **No Overhead:** Does not run Tailwind watchers or dev tools. Simplicity and performance focused.
 
 ### Package.json Scripts
 
-When you create a new website, Odac automatically generates a `package.json` with these useful scripts:
+When you create a new ODAC project, your `package.json` comes pre-configured with these scripts:
 
 ```json
 {
   "scripts": {
-    "start": "odac framework run",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "dev": "odac dev",
+    "build": "odac build",
+    "start": "odac start"
   }
 }
 ```
 
-- `npm start` - Starts the development server for local testing
-- `npm test` - Placeholder for your test suite
-
-### Tips
-
-- The development server automatically detects changes in your code
-- Use `Ctrl+C` to stop the development server
-- The server will show helpful error messages in the console
-- All Odac framework features are available in development mode
+- `npm run dev` - Your daily development command.
+- `npm run build` - Run this before deploying (e.g., in CI/CD).
+- `npm start` - The command that runs your live website.

package/docs/backend/02-structure/01-typical-project-layout.md

@@ -2,36 +2,70 @@
 
 Let's take a look at a typical project layout:
 
--   `project_root/`
-    -   `config.json`: This is where you'll keep your app's secrets and settings, like database passwords or API keys.
-    -   `index.js`: The starting pistol for your web application! This file kicks off the Odac framework.
-    -   `package.json`: Contains project metadata and npm scripts for development. Automatically generated when creating a new website.
-    -   `public/`: All files placed in this folder are directly accessible from the outside. This is the perfect place for your images, stylesheets, and client-side JavaScript.
-    -   `route/`: This folder holds all your route definitions. The filename of the route file corresponds to the subdomain it serves.
-        -   `www.js`: Used for routes on your main domain (e.g., `www.example.com` or `example.com`).
-        -   `api.js`: Used for routes on a subdomain (e.g., `api.example.com`). When a request comes in for `api.example.com`, this is the route file that gets used. You can create files for any subdomain!
-    -   `controller/`: This is where the magic happens! Controllers contain the main logic for your application.
-        -   `page/`: We suggest putting controllers that show HTML pages in here.
-        -   `api/`: If you're building an API, it's a great idea to keep those controllers separate in their own folder.
-    -   `view/`: For all your HTML template files. This is what your users will see.
-
-### Development Commands
-
-Your `package.json` includes helpful npm scripts for development:
+```
+project/
+├── class/              # Business logic classes (request-scoped)
+│   ├── Payment.js
+│   └── User.js
+├── controller/         # HTTP request handlers
+│   ├── api/            # API endpoint controllers
+│   │   ├── auth.js
+│   │   └── users.js
+│   └── page/           # HTML page controllers
+│       ├── about.js
+│       └── home.js
+├── middleware/         # Route middleware functions
+│   └── auth.js
+├── public/             # Static assets (directly accessible)
+│   └── assets/
+│       ├── css/
+│       │   └── app.css # Auto-generated by Tailwind
+│       ├── img/
+│       └── js/
+├── route/              # Route definitions (subdomain-based)
+│   ├── api.js          # Routes for api.example.com
+│   └── www.js          # Routes for www.example.com
+├── storage/            # App storage (logs, cache, uploads)
+│   └── .cache/
+├── view/               # HTML templates
+│   ├── content/
+│   ├── css/            # (Optional) Custom Tailwind entry points
+│   ├── footer/
+│   ├── header/
+│   └── skeleton/
+├── .env                # Environment variables (secrets, API keys)
+├── odac.json           # App configuration
+└── package.json        # Project metadata & npm scripts
+```
 
-```bash
-# Start development server (default port 1071)
-npm start
+### 📁 Directory Breakdown
 
-# Start development server on custom port
-npm start 8080
-```
+| Directory | Purpose |
+|-----------|---------|
+| `class/` | Request-scoped service classes for business logic |
+| `controller/` | HTTP handlers that process requests and return responses |
+| `middleware/` | Functions that run before controllers (auth, logging, etc.) |
+| `route/` | Route definitions, one file per subdomain |
+| `view/` | HTML templates and partials |
+| `public/` | Static files served directly to browsers |
+| `storage/` | Runtime data (cache, logs, file uploads) |
 
-You can also use Odac commands directly:
+### CLI Commands
+
+Your `package.json` includes scripts to manage your project lifecycle:
 
 ```bash
-# Development server (local testing only)
-odac framework run [port]
+# STAGE 1: DEVELOPMENT
+# Starts dev server with hot-reload & automatic Tailwind CSS
+npm run dev
+
+# STAGE 2: BUILD
+# Compiles and optimizes assets (CSS) for production
+npm run build
+
+# STAGE 3: PRODUCTION
+# Starts the optimized server
+npm start
 ```
 
 **Note**: For production websites with DNS and SSL, use `odac web create` to register with Odac server.

package/docs/backend/03-config/00-configuration-overview.md

@@ -1,10 +1,10 @@
 ## ⚙️ Configuration Overview
 
-Odac uses a simple and flexible configuration system based on `config.json` and optional `.env` files. You can choose the approach that best fits your needs.
+Odac uses a simple and flexible configuration system based on `odac.json` and optional `.env` files. You can choose the approach that best fits your needs.
 
 ### Configuration Files
 
-#### config.json (Required)
+#### odac.json (Required)
 The main configuration file located in your website's root directory. This file contains all your application settings in JSON format.
 
 ```json
@@ -46,7 +46,7 @@ Perfect for development or non-sensitive settings:
 ```
 
 #### 2. Environment Variables (Secure)
-Use `${VARIABLE}` syntax in `config.json` to reference `.env` values:
+Use `${VARIABLE}` syntax in `odac.json` to reference `.env` values:
 
 ```json
 {
@@ -101,7 +101,7 @@ const nodeEnv = process.env.NODE_ENV
 ### Best Practices
 
 **Development:**
-- Use direct values in `config.json` for quick setup
+- Use direct values in `odac.json` for quick setup
 - Keep development credentials simple
 
 **Production:**
@@ -111,7 +111,7 @@ const nodeEnv = process.env.NODE_ENV
 - Copy `.env.example` to `.env` and fill in production values
 
 **Version Control:**
-- Commit `config.json` with `${VARIABLE}` placeholders
+- Commit `odac.json` with `${VARIABLE}` placeholders
 - Commit `.env.example` with dummy values
 - Never commit `.env` with real credentials
 
@@ -161,13 +161,22 @@ const nodeEnv = process.env.NODE_ENV
 }
 ```
 
+**Debug Mode:**
+Enable verbose logging for development. This helps in troubleshooting by inspecting detailed logs for system actions like sending emails (e.g., SMTP connection details, server responses). Default is `false`.
+
+```json
+{
+  "debug": true
+}
+```
+
 Early Hints is a performance optimization feature that works automatically without any configuration. The server sends preliminary HTTP headers to the browser before the final response, allowing browsers to start preloading critical resources (CSS, JavaScript, fonts) earlier. This is completely zero-config - it detects resources from your HTML automatically and sends hints on subsequent requests.
 
 See individual documentation sections for detailed configuration options.
 
 ### Example Setup
 
-**config.json** (committed to git):
+**odac.json** (committed to git):
 ```json
 {
   "request": {

package/docs/backend/03-config/01-database-connection.md

@@ -1,6 +1,6 @@
 ## 🔌 Database Connection
 
-When you add a `mysql` object to your `config.json`, the system will automatically connect to your MySQL database. No separate connection setup is needed in your code.
+When you add a `mysql` object to your `odac.json`, the system will automatically connect to your MySQL database. No separate connection setup is needed in your code.
 
 ### Basic Configuration
 
@@ -15,13 +15,13 @@ When you add a `mysql` object to your `config.json`, the system will automatical
 }
 ```
 
-Once this is configured, you can directly use `Odac.Mysql` commands to run queries.
+Once this is configured, you can directly use `Odac.DB` commands to run queries.
 
 ### Using Environment Variables
 
 For better security, especially in production, you can use environment variables for sensitive information:
 
-**config.json:**
+**odac.json:**
 ```json
 {
   "mysql": {

package/docs/backend/03-config/02-static-route-mapping-optional.md

@@ -1,6 +1,6 @@
 ## 🗺️ Static Route Mapping (Optional)
 
-Normally, all publicly served files should be in your `public` folder. However, if you need to expose a specific file from somewhere else on your server, you can use the optional `route` object in your `config.json`. This creates a direct mapping from a URL path to that file.
+Normally, all publicly served files should be in your `public` folder. However, if you need to expose a specific file from somewhere else on your server, you can use the optional `route` object in your `odac.json`. This creates a direct mapping from a URL path to that file.
 
 ```json
 "route": {

package/docs/backend/03-config/03-request-timeout.md

@@ -1,6 +1,6 @@
 ## ⏱️ Request Timeout
 
-You can configure the global timeout for incoming requests by adding a `request` object to your `config.json`.
+You can configure the global timeout for incoming requests by adding a `request` object to your `odac.json`.
 
 ```json
 "request": {

package/docs/backend/03-config/04-environment-variables.md

@@ -4,7 +4,7 @@ Odac supports environment variables through `.env` files, making it easy to mana
 
 ### Creating a .env File
 
-Create a `.env` file in your website's root directory (same location as `config.json`):
+Create a `.env` file in your website's root directory (same location as `odac.json`):
 
 ```bash
 # .env
@@ -37,7 +37,7 @@ FEATURE_BETA=true
 MAINTENANCE_MODE=false
 ```
 
-### Using in config.json
+### Using in odac.json
 
 Reference environment variables using `${VARIABLE_NAME}` syntax:
 
@@ -91,7 +91,7 @@ module.exports = function() {
 }
 ```
 
-#### 3. From Odac.Config (if defined in config.json)
+#### 3. From Odac.Config (if defined in odac.json)
 
 ```javascript
 module.exports = function() {
@@ -222,6 +222,6 @@ MAIL_FROM='noreply@example.com'
 
 - Environment variables are loaded when the application starts
 - Changes to `.env` require restarting the application
-- The `.env` file is **optional** - you can use direct values in `config.json` if preferred
+- The `.env` file is **optional** - you can use direct values in `odac.json` if preferred
 - Variables defined in `.env` are available throughout your entire application
 - If a variable is not found, `Odac.env()` returns the default value or `undefined`

package/docs/backend/03-config/05-early-hints.md

@@ -54,7 +54,7 @@ Same flow - hints are sent from the manifest immediately.
 
 ## Configuration (Optional)
 
-While Early Hints works automatically, you can customize it in `config.json`:
+While Early Hints works automatically, you can customize it in `odac.json`:
 
 ```json
 {
@@ -329,7 +329,7 @@ Reduce `maxResources` in config:
 
 ## Disabling Early Hints
 
-Removing the `earlyHints` configuration section from your `config.json` is equivalent to using the default settings, which has the feature enabled. To truly disable Early Hints, you must explicitly set `enabled: false` in your configuration:
+Removing the `earlyHints` configuration section from your `odac.json` is equivalent to using the default settings, which has the feature enabled. To truly disable Early Hints, you must explicitly set `enabled: false` in your configuration:
 
 ```json
 {

package/docs/backend/04-routing/02-controller-less-view-routes.md

@@ -3,18 +3,24 @@
 For simple pages that don't require complex logic in a controller, you can render a view directly from your route file by passing a view configuration object as the second parameter.
 
 #### `page(path, { ... })`
-This defines a page and immediately tells it which view components to render.
+This defines a page and immediately tells it which view components to render. You can also pass variables directly in the object, which will be available in your views.
 
 ```javascript
 Odac.Route.page("/users", {
+    // View Configuration
     skeleton: "dashboard",
     header: "dashboard.main",
     sidebar: "dashboard.main",
     footer: "dashboard.main",
-    content: "users"
+    content: "users",
+
+    // Page Variables
+    title: "User Management",
+    description: "Manage your platform users here"
 });
 ```
-This example tells Odac to render the `/users` page by assembling a view from multiple parts, likely using a main `dashboard` skeleton and filling it with different content blocks.
+
+This example tells Odac to render the `/users` page using the `dashboard` skeleton. Additionally, `title` and `description` are set as variables and can be accessed in your views using `<odac var="title" />`.
 
 **Page Identifier:** When using view objects, the page identifier (accessible via `Odac.page()` in frontend) is automatically set to the `content` or `all` value. In this example, the page identifier would be `"users"`, allowing you to run page-specific JavaScript:
 

package/docs/backend/04-routing/03-api-and-data-routes.md

@@ -1,5 +1,22 @@
 ## 📦 API and Data Routes
 
+
+#### Class-Based Route Definition (Recommended)
+
+You can route requests to specific methods within a Controller Class using the `ClassName@methodName` syntax. This allows you to group related logic in a single file clearly.
+
+```javascript
+// Calls the 'index' method of the class exported in controller/User.js
+Odac.Route.get('/users', 'User@index');
+
+// Calls the 'store' method of the class exported in controller/User.js
+Odac.Route.post('/users', 'User@store');
+
+// You can also use dot notation for controllers in subdirectories
+// controller/Admin/Dashboard.js -> Admin.Dashboard
+Odac.Route.get('/admin', 'Admin.Dashboard@index');
+```
+
 #### `get(path, controller, options)`
 Defines a route that responds to `GET` requests. This is ideal for API endpoints that return data (like JSON).
 
@@ -18,3 +35,4 @@ Defines a route that responds to `POST` requests, typically used for form submis
 // A form that posts data to /login
 Odac.Route.post('/login', 'auth.login');
 ```
+

package/docs/backend/04-routing/07-cron-jobs.md

@@ -79,6 +79,9 @@ Odac.Route.cron('task')
 // Day (1-31)
 .day(15) // On the 15th of the month
 
+// At Specific Time (HH:MM)
+.at('14:30') // At 14:30 (Shorthand for .hour(14).minute(30))
+
 // Week day (0-6, 0=Sunday)
 .weekDay(1) // On Monday
 
@@ -114,6 +117,18 @@ Odac.Route.cron('periodic')
 
 // Every N years
 .everyYear(1) // Every year
+
+## Raw Cron Expression
+You can use standard UNIX cron expressions (Minute Hour Day Month WeekDay) using the `.raw()` method.
+Supported formats for each field: `*`, `*/n` (interval), `n` (exact match).
+
+```javascript
+// Run every 15 minutes
+Odac.Route.cron('quarter-task').raw('*\/15 * * * *')
+
+// Run at 14:30 on Mondays
+Odac.Route.cron('weekly-meeting').raw('30 14 * * 1')
+```
 ```
 
 ## Combination Usage
@@ -146,4 +161,5 @@ Odac.Route.cron('monthly-cleanup')
 - If the same job is defined multiple times, the last definition takes precedence
 - Controller files are re-required on each execution
 - Inline functions are stored in memory and executed directly
-- If a job fails, it stops but the system continues
+- If a job fails, it stops but the system continues
+- **CRITICAL:** Missing conditions act as wildcards (`*`). If you specify `.hour(14)` but omit `.minute()`, the task will run **every minute** between 14:00 and 14:59. Always specify smaller units (minute) to pin execution to a single point in time. Use `.at('14:00')` to safely set both hour and minute.

package/docs/backend/04-routing/09-websocket.md

@@ -45,6 +45,35 @@ web/
 │   └── websocket.js    # WebSocket routes (recommended)
 ```
 
+### Using Controllers
+
+You can also specify a connector file as a string. Odac will look for the file in `controller/ws/`.
+
+```javascript
+// route/websocket.js
+Odac.Route.ws('/chat', 'ChatController')
+```
+
+**File Structure:**
+```
+web/
+├── controller/
+│   └── ws/
+│       └── ChatController.js
+```
+
+**Controller File:**
+```javascript
+// controller/ws/ChatController.js
+module.exports = Odac => {
+  Odac.ws.send({type: 'welcome'})
+  
+  Odac.ws.on('message', data => {
+    // ...
+  })
+}
+```
+
 ## WebSocket Client API (Odac.ws)
 
 The WebSocket client is accessible via `Odac.ws` in your handler, providing a consistent API pattern with HTTP routes.

package/docs/backend/05-controllers/01-how-to-build-a-controller.md

@@ -1,8 +1,52 @@
 ## 🏗️ How to Build a Controller
 
-A controller is just a JavaScript module that exports a function. This function automatically gets the magical `Odac` context object we talked about in the overview.
+A controller is just a JavaScript module that exports a function or a Class. This function automatically gets the magical `Odac` context object we talked about in the overview.
 
-#### A Simple "Hello World" Controller
+#### Class-Based Controllers (Professional & Recommended)
+
+For professional applications, we **strongly recommend** using Class-Based Controllers. This approach allows you to group related actions (like all User-related or Product-related logic) into a single file in the `controller/` directory, keeping your project organized.
+
+**Example: `controller/User.js`**
+
+```javascript
+class User {
+  // Access this via 'User@index'
+  index(Odac) {
+    return Odac.View.make('user.list', {
+      title: 'User List'
+    })
+  }
+
+  // Access this via 'User@show'
+  show(Odac) {
+    const id = Odac.Request.input('id')
+    // Fetch user logic...
+    return Odac.return({ id: id, name: 'John Doe' })
+  }
+
+  // Access this via 'User@store'
+  store(Odac) {
+    // Save user logic...
+    return Odac.return({ success: true })
+  }
+}
+
+module.exports = User
+```
+
+When using this structure, you define your routes using the `ControllerName@MethodName` syntax:
+
+```javascript
+Odac.Route.get('/users', 'User@index')
+Odac.Route.get('/users/{id}', 'User@show')
+Odac.Route.post('/users', 'User@store')
+```
+
+The framework automatically instantiates your Controller class and calls the specified method with the `Odac` instance passed as an argument.
+
+#### specific Function Controllers (Basic)
+
+For very simple or single-purpose routes, you can export a single function.
 
 Check out this basic example from `controller/page/index.js`:
 
@@ -14,4 +58,5 @@ module.exports = function (Odac) {
 }
 ```
 
-This little guy is responsible for handling the homepage route (`/`). When it runs, it just sends a simple string back to the user's browser.
+This simple function is responsible for handling the homepage route (`/`). When it runs, it just sends a simple string back to the user's browser.
+

package/docs/backend/05-controllers/02-your-trusty-odac-assistant.md

@@ -14,6 +14,8 @@ Remember the `Odac` object? It's your best friend inside a controller. It's pass
 
 *   `Odac.return(data)`: Send back a response.
 *   `Odac.direct(url)`: Redirect the user to a new page.
+*   `Odac.set(key, value)`: Pass variables to your View template.
+*   `Odac.share(key, value)`: Share data directly with frontend JavaScript (`odac.data()`).
 *   `Odac.cookie(key, value)`: Set a browser cookie.
 *   `Odac.validator()`: Check user input easily.
 *   `Odac.setInterval(callback, delay)`: Schedule repeating tasks (auto-cleanup).