odac 1.0.1 → 1.2.0

package/.agent/rules/coding.md

@@ -0,0 +1,27 @@
+---
+trigger: always_on
+---
+
+# Coding Standards & Best Practices
+
+## 1. Testing Strategy
+- **Rule:** No feature is complete without tests.
+- **Goal:** Maintain stability and prevent regressions.
+- **Action:** Write unit tests for logic and integration tests for API endpoints.
+
+## 2. Dependency Management
+- **Philosophy:** "Less is more."
+- **Rule:** Avoid external dependencies unless absolutely necessary.
+- **Preference:** Prioritize native Node.js modules (`fs`, `http`, `crypto`, etc.) to reduce bundle size and security attack surface.
+
+## 3. Error Handling
+- **Rule:** Fail loudly and clearly.
+- **Practice:** Use custom Error classes where possible.
+- **Message:** Error messages should guide the developer on how to fix the issue, not just say "Error".
+
+## 4. Modern JavaScript
+- **Standard:** Use ES6+ features (Async/Await, Arrow functions, Destructuring).
+- **Modules:** Strict adherence to ES Modules (import/export).
+
+## 5. Route & Session Logic
+- **Session Initialization:** `Odac.Request.setSession()` MUST be called before any logic that attempts to access `Odac.Request.session()`. This includes global middleware or form processing logic in `Route.js` that runs before the specific controller is resolved.

package/.agent/rules/memory.md

@@ -0,0 +1,33 @@
+---
+trigger: always_on
+---
+
+# Project Memory & Rules
+
+## Configuration & Environment
+- **Debug Mode Logic:** The `debug` configuration in `src/Config.js` defaults to `process.env.NODE_ENV !== 'production'`. This ensures that `odac dev` (undefined NODE_ENV) enables debug/hot-reload, while `odac start` (NODE_ENV=production) disables it to use caching.
+- **Logging Strategy:** 
+    - **Development (`debug: true`):** Enable verbose logging, hot-reloading notifications, and detailed stack traces for easier debugging.
+    - **Production (`debug: false`):** Minimize logging to essential operational events (Start/Stop) and Fatal Errors only. Avoid `console.log` for per-request information to preserve performance and disk space. Sensitive error details must not be exposed to the user.
+
+## Development Standards & Integrity
+- **NO QUICK/LAZY FIXES:** Explicitly prohibited. 
+    - Never implement truncated solutions (e.g., `substring(0, 32)` on a hash) or temporary workarounds just to make code run.
+    - Always implement the mathematically and architecturally correct "Enterprise-Grade" solution (e.g., using raw `Buffer` for crypto keys instead of hex strings).
+    - If a proper solution requires refactoring, do the refactoring. Do not patch holes.
+    - **Prioritize Correctness over Speed:** It is better to verify documentation or think for a minute than to output a sub-par patch.
+
+## Code Quality & Modern Standards
+- **No Legacy Syntax:** 
+    - **Strictly Prohibited:** The use of `var` is forbidden. Use `const` (preferred) or `let` (only if mutation is needed).
+    - **Variable Scope:** Ensure variables are block-scoped to prevent leakage.
+- **Anti-Spaghetti Code:**
+    - **Fail-Fast Pattern:** Avoid deeply nested `if/else` logic. Use early returns (`return`, `break`, `continue`) to handle negative cases immediately.
+    - **Promise Handling:** Resolve Promises upfront (e.g., `Promise.all` or strict `await` before loops) rather than mixing `await` inside deep logic or mutating input objects.
+    - **Strict Equality:** Always use strict equality checks (`===`) instead of loose ones.
+    - **Loop Optimization:** Use labeled loops (`label: for`) for efficient control flow in nested structures. Eliminate intermediate "flag" variables (`isMatch`, `found`) by using direct `return` or `continue label`.
+    - **Direct Returns:** Return a value as soon as it is determined. Avoid assigning to a temporary variable (e.g. `matchedUser`) and breaking the loop, unless post-loop processing is strictly necessary.
+    - **Async State Safety:** When an async function depends on mutable class state (like `pendingMiddlewares`), capture that state into a local `const` *synchronously* before triggering any async operations. This prevents race conditions where the state changes before the async task consumes it.
+
+## Dependency Management
+- **Prefer Native Fetch:** Use the native `fetch` API for network requests in both Node.js (18+) and browser environments to reduce dependencies and bundle size.

package/.agent/rules/project.md

@@ -0,0 +1,30 @@
+---
+trigger: always_on
+---
+
+# Project Context & Design Philosophy
+
+## Project Identity
+- **Type:** Node.js Framework
+- **Goal:** To provide a robust, enterprise-ready backbone for web applications.
+
+## Core Priorities (The "Big 3")
+1.  **Enterprise-Level Security:** 
+    - Security is not an afterthought; it is foundational. 
+    - Default to secure settings. 
+    - Validate all inputs. 
+    - Sanitize outputs. 
+    - Use established cryptographic standards.
+2.  **Zero-Config:** 
+    - The framework should work "out of the box" with sensible defaults. 
+    - Configuration should be optional, not mandatory for getting started. 
+    - "Convention over Configuration" is key.
+3.  **High Performance:** 
+    - Code must be optimized for throughput and low latency. 
+    - Avoid unnecessary overhead. 
+    - Profile and benchmark critical paths. 
+    - Memory management is crucial.
+
+## Interaction Guidelines for AI
+- Always assume the user wants the most efficient and secure solution unless specified otherwise.
+- When suggesting architecture, prioritize scalability and maintainability.

package/.agent/rules/workflow.md

@@ -0,0 +1,16 @@
+---
+trigger: always_on
+---
+
+# Development Workflow Rules
+
+## 1. Quality Assurance (Linting)
+- **Rule:** **ALWAYS** runs lint checks after writing or modifying code.
+- **Action:** Execute the project's linting command (e.g., `npm run lint` or `eslint .`) to verify code compliance.
+- **Strictness:** Do not mark a task as complete if lint errors persist. Fix them immediately.
+
+## 2. Documentation Hygiene
+- **Rule:** Documentation must be kept in sync with code changes.
+- **Trigger:** Adding a new feature, modifying an API, or changing configuration behavior.
+- **Action:** Update the relevant `.md` files (README, API docs, etc.) or JSDoc comments.
+- **Goal:** Ensure that the documentation is never stale and accurately reflects the current state of the codebase.

package/.github/workflows/auto-pr-description.yml

@@ -35,6 +35,8 @@ jobs:
 
       - name: Update PR Title and Body
         uses: actions/github-script@v7
+        env:
+          PR_BODY: ${{ steps.generate_body.outputs.body }}
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
@@ -43,5 +45,5 @@ jobs:
               repo: context.repo.repo,
               pull_number: context.issue.number,
               title: 'Sync `dev` to `main`',
-              body: `${{ steps.generate_body.outputs.body }}`
+              body: process.env.PR_BODY
             });

package/.github/workflows/release.yml

@@ -7,6 +7,7 @@ on:
     paths-ignore:
       - 'CHANGELOG.md'
       - 'package.json'
+      - '.github/workflows/test-publish.yml'
   workflow_dispatch:
 
 jobs:
@@ -27,9 +28,12 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '22'
+          node-version: '24'
           registry-url: 'https://registry.npmjs.org'
 
+      - name: Update npm
+        run: npm install -g npm@latest
+
       - name: Install dependencies
         run: npm install
 
@@ -37,3 +41,40 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: npx semantic-release
+
+      - name: Publish to npm
+        run: npm publish --provenance --access public
+      
+      - name: Get version
+        id: version
+        run: echo "version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT
+
+      - name: Checkout Actions
+        if: steps.version.outputs.version != ''
+        uses: actions/checkout@v4
+        with:
+          repository: odac-run/actions
+          token: ${{ secrets.GH_PAT }}
+          path: .github/odac-actions
+
+      - name: Generate Release Notes
+        id: ai_notes
+        if: steps.version.outputs.version != ''
+        uses: ./.github/odac-actions/actions/release-notes
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          michelangelo: ${{ secrets.MICHELANGELO }}
+        timeout-minutes: 15
+        continue-on-error: true
+
+      - name: Cleanup Actions
+        if: always()
+        run: rm -rf .github/odac-actions
+      - name: Update Release
+        uses: softprops/action-gh-release@v1
+        if: steps.ai_notes.outcome == 'success' && steps.version.outputs.version != ''
+        with:
+          tag_name: v${{ steps.version.outputs.version }}
+          body_path: RELEASE_NOTE.md
+          draft: false
+          prerelease: false

package/.github/workflows/test-coverage.yml

@@ -20,7 +20,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: 22.x
+        node-version: [18.x, 24.x]
 
     steps:
       - name: Checkout code
@@ -41,19 +41,20 @@ jobs:
         run: npm test
 
       - name: Upload coverage reports
-        if: matrix.node-version == '22.x'
-        uses: codecov/codecov-action@v3
+        if: matrix.node-version == '18.x'
+        uses: codecov/codecov-action@v4
         with:
           files: ./coverage/lcov.info
           flags: unittests
           name: codecov-umbrella
           fail_ci_if_error: false
+          token: ${{ secrets.CODECOV_TOKEN }}
 
       - name: Coverage Summary
-        if: matrix.node-version == '22.x'
+        if: matrix.node-version == '18.x'
         run: |
           echo "## Test Coverage Summary" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
           echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
-          npx nyc report --reporter=text-summary >> $GITHUB_STEP_SUMMARY || echo "Coverage report not available" >> $GITHUB_STEP_SUMMARY
+          npx nyc report --reporter=text-summary --temp-directory=coverage >> $GITHUB_STEP_SUMMARY || echo "Coverage report not available" >> $GITHUB_STEP_SUMMARY
           echo "\`\`\`" >> $GITHUB_STEP_SUMMARY

package/.github/workflows/test-publish.yml

@@ -0,0 +1,36 @@
+name: Test Publish Authentication
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  test-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+
+      - name: Update npm
+        run: npm install -g npm@latest
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Debug Environment
+        run: |
+          npm --version
+          node --version
+          npm config list
+          ls -la .npmrc || echo "No local .npmrc"
+
+      - name: Test Publish (Real Attempt)
+        run: npm publish --provenance --access public --registry https://registry.npmjs.org/

package/.husky/pre-commit

@@ -0,0 +1,10 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+echo "🔍 Running Pre-commit Hooks..."
+
+# Run linting and formatting on staged files
+npx lint-staged
+
+# Run tests for changed files to ensure no regressions
+node test/scripts/check-coverage.js

package/.husky/pre-push

@@ -0,0 +1,13 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+# Prevent pushing code with High/Critical vulnerabilities
+echo "🛡️  Running Security Gate (npm audit)..."
+
+npm audit --audit-level=high
+
+if [ $? -ne 0 ]; then
+    echo "❌ Security Check Failed! High vulnerabilities detected."
+    echo "Run 'npm audit fix' or add overrides before pushing."
+    exit 1
+fi

package/.releaserc.js

@@ -122,16 +122,16 @@ Powered by [⚡ ODAC](https://odac.run)
     [
       '@semantic-release/npm',
       {
-        provenance: true
+        npmPublish: false
       }
     ],
     [
       '@semantic-release/git',
       {
         assets: ['package.json', 'CHANGELOG.md'],
-        message: '⚡ ODAC v${nextRelease.version} Released'
+        message: '⚡ ODAC.JS v${nextRelease.version} Released'
       }
     ],
     '@semantic-release/github'
   ]
-}
+}

package/CHANGELOG.md

@@ -1,3 +1,187 @@
+### agent
+
+- Clarify logging strategies for development and production environments
+
+### deps
+
+- update `tar` override version and add `@semantic-release/npm` override.
+
+### ⚙️ Engine Tuning
+
+- add JSDoc and default parameter to `Auth.user` method for improved clarity and robustness.
+- enable method chaining for cron job condition definitions
+- Enhance cryptographic security by using CSPRNG for token generation, SHA-256 for encryption key derivation, and adding clarifying configuration comments.
+- Improve authentication logic by adopting fail-fast patterns, upfront promise resolution, and optimized loop control, aligning with new code quality guidelines.
+- Improve view file reading by using `fsPromises.open` for better resource management and atomic operations.
+- Migrate route and middleware loading to asynchronous file system operations for improved performance.
+- Remove redundant `fs.existsSync` checks before `fs.mkdirSync` and add `EEXIST` handling for `fs.writeFileSync`.
+- remove unused nodeCrypto import from Config.test.js
+- rename config.json to odac.json for brand consistency
+- Streamline default CSS file creation using `fs.writeFileSync` 'wx' flag.
+- Use raw Buffer for encryption key hashing, aligning with enterprise-grade development standards.
+
+### ⚡️ Performance Upgrades
+
+- Implement enterprise-grade HTTP server performance configurations
+- Optimize file serving by eliminating redundant `fs.stat` calls and deriving content length directly from the read file.
+- **route:** implementation of async I/O and metadata caching for static assets
+- **view:** switch to async I/O and implement aggressive production caching
+
+### ✨ What's New
+
+- add built-in tailwindcss v4 support with zero-config
+- Enhance cron job scheduling with new `.at()` and `.raw()` methods, update cron documentation.
+- Enhance Tailwind CSS watcher to prioritize local CLI over npx for improved reliability and adjust shell option accordingly.
+- **framework:** add Odac.session() helper and update docs
+- implement Class-Based Controllers support and update docs
+- Implement conditional environment variable loading, configure server workers based on debug mode
+- Replaced bcrypt with native Node.js crypto.scrypt for hashing, removed bcrypt and axios dependencies, and updated related validation checks.
+- support multiple Tailwind CSS entry points in build and dev processes.
+
+### 📚 Documentation
+
+- add documentation for multiple CSS file support
+- add project structure overview to README
+- Add Tailwind CSS v4 integration to README features list
+- Introduce architectural and cluster safety notes to Token, Ipc, and Storage modules.
+
+### 🛠️ Fixes & Improvements
+
+- Add null safety checks for `odac.Request` and its `header` method when determining the default language.
+- add options support to authenticated routes (GET/POST)
+- Conditionally initialize Odac request-dependent components and provide a dedicated Odac instance with cleanup to cron jobs.
+- Enhance server port configuration to prioritize command-line arguments and environment variables
+- Initialize session in Route.js during form processing to ensure proper session availability before access, aligning with new coding standards.
+- **package:** resolve high severity npm vulnerabilities
+- Prevent form token expiration errors by dynamically generating forms at runtime.
+- Prevent middleware race conditions by synchronously capturing state and improve Tailwind CSS watcher robustness with auto-restart.
+- Refine error message styling in form validation
+- Replace insecure token generation with cryptographically secure random bytes for `token_x` and `token_y`.
+- **session:** change cookie SameSite policy to Lax for OAuth support
+
+
+
+---
+
+Powered by [⚡ ODAC](https://odac.run)
+
+### Fix
+
+- Resolve WebSocket handshake error by echoing subprotocol header
+
+### Refactor
+
+- Unified WebSocket architecture and fixed race conditions
+
+### deps
+
+- update mysql2 dependency to ^3.16.0
+
+### ⚙️ Engine Tuning
+
+- Add type checks for page assignments and a null check for the `authPage` method's `authFile` parameter.
+- extract and trim validation rule names for clearer inverse rule processing.
+- extract HTML stripping logic into a private helper method and apply it to text content generation.
+- migrate custom `odac:field` tag to `odac:input` with updated parsing logic and regex patterns.
+- migrate session locking from in-memory object to `Odac.Storage` for persistence.
+- Move form message clearing logic to the beginning of form submission.
+- move middleware execution to occur after URL parameter processing.
+- pass PR body to github-script action via environment variable
+- Remove duplicate data-error-email attribute assignment.
+- rename `requestMagicLink` method to `magic` in Auth and update its usages and documentation
+- Rename authentication token and session cookie keys from 'candy' to 'odac'.
+- rename internal `Odac` class to `_odac`
+- Rename Mysql to Database and implement connection pooling
+- Update default magic link table name from 'magic_links' to 'odac_magic'.
+- Use `crypto.randomBytes` for client and session ID generation instead of MD5 hashing.
+- use `node:crypto.randomBytes` for generating unique IDs instead of `Date.now()` and `Math.random()`
+- use file descriptor for mail template reading to ensure resource closure
+
+### ✨ What's New
+
+- add `_odac/form` POST route with CSRF token validation
+- Add `!disposable` validation rule to block temporary email providers by fetching and caching a daily updated blocklist.
+- Add console error for missing controller files
+- Add custom template rendering engine with caching to Mail service and enhance magic link email options.
+- Add magic link rate limiting, expired link cleanup, and open redirect protection for magic link redirects.
+- add passwordless auto-registration for magic links, improve URL query decoding, and disable token validation for the magic link verification route.
+- Add request language property from Accept-Language header, defaulting to 'en'.
+- Add session cooldown for magic link requests and return explicit errors for rate limits, updating documentation.
+- Allow direct page route definition when a file is provided.
+- Allow specifying and using a redirect URL for magic link authentication.
+- emit 'ping' event when receiving a WebSocket PING frame
+- Enable passing variables directly in view configuration objects for page routes and update documentation.
+- Enable sending plain text and raw HTML emails without templates in the mail service.
+- HTML Mail delivery via direct ODAC Mail Server
+- Ignore database table not found errors when looking up users by email.
+- Implement and document auto-clearing of form inputs on successful submission, controllable via a `clear` attribute.
+- Implement backend-to-frontend data sharing via `Odac.share` and…
+- implement built-in IPC system with Memory and Redis drivers
+- Implement dynamic session garbage collection with simple and batch cleaning modes based on session count.
+- Implement graceful shutdown for primary and worker processes in the cluster.
+- Implement magic login functionality
+- Implement magic login functionality with new routes, internal handlers, and form processing, while removing a generic form route.
+- Implement passwordless signup by auto-registering new users during magic link verification and adding `node:crypto` for random password generation.
+- Implement server actions for forms, allowing `Controller.method` as the action and dispatching internally via a generic endpoint.
+- introduce `Odac.DB.nanoid()` helper, centralize its implementation, and update authentication ID generation strategy documentation.
+- Introduce Nano IDs for primary keys and cookie identifiers, streamlining user insertion logic.
+- introduce service classes in a dedicated directory with naming collision handling and refine route authentication logic.
+- Introduce Storage module to encapsulate LMDB operations and session garbage collection.
+- Migrate session management from in-memory to LMDB, enable server clustering, and add session garbage collection.
+- Modernize db layer with magic api and migrations
+- Modernize db layer with magic api and migrations
+- Render form success and error messages as HTML using a new `textToHtml` utility.
+- Return generic success message for user not found when auto-register is enabled to prevent enumeration.
+- Server Clustering & Persistent Session Management
+- support string-based WebSocket controller paths and update documentation
+- Update route loading to execute function-exported route definitions with Odac.
+- Update session private key hashing algorithm from MD5 to SHA256.
+
+### 📚 Documentation
+
+- Add magic links documentation.
+- Fix typo in controller classes documentation
+- overhaul README to detail new Node.js framework features, advanced capabilities, updated quick start instructions, and license.
+- remove redundant html code block tag
+- remove server documentation index.
+- Replace old database connection and MySQL guides with new getting started, query basics, advanced queries, and migrations documentation.
+- Standardize framework name capitalization from Odac to ODAC across documentation.
+- Update database interaction examples from `Odac.Mysql` to `Odac.DB`.
+- update database query examples to include `.select()` and variable assignments.
+
+### 🛠️ Fixes & Improvements
+
+- Add error handling for cache file access to ensure validation update proceeds.
+- Add explicit response termination for middleware and redirects, and pass page file path to request.
+- Adjust session key counting range
+- Consume all magic link tokens for an email instead of just the used one to prevent reuse.
+- Correct `odac` special variable path resolution by removing `/src` instead of `/framework/src`.
+- Enable `MiddlewareChain` to automatically use auth handlers when created via `Route.auth.use`.
+- Ensure all HTML tags are recursively stripped when converting HTML to plain text.
+- Ignore `data:` and `vbscript:` pseudo-protocols when processing anchor hrefs.
+- Implement form token rotation on successful form submission without redirect and update client-side form with the new token.
+- Initialize cron interval only in the primary cluster process.
+- Introduce `setSession` method for client ID initialization and optimize internal session and cookie storage.
+- log errors when ensuring the magic link table exists instead of ignoring them
+- Log Odac Auth errors when ensuring token table exists instead of ignoring them.
+- Prevent navigation to `data:` and `vbscript:` URLs.
+- re-register form submit handler when its `data-odac-form` attribute changes to ensure correct event capture.
+- recursively strip nested script and style tags when sanitizing HTML
+- Relax sameSite cookie policy to Lax and refactor redirect handling.
+- remove all socket listeners when closing or disconnecting the WebSocket.
+- Remove early exit from token hash check loop to mitigate timing attacks.
+- return non-function default connection properties directly instead of attempting to bind them
+- return registration error on unique check failure.
+- Robustly extract multipart boundary from request body.
+- serve static files via `createReadStream` and pipe streamable content to response.
+- Validate error route cache handler is a function in Request abort method.
+
+
+
+---
+
+Powered by [⚡ ODAC](https://odac.run)
+
 ### 🛠️ Fixes & Improvements
 
 - Simplify project initialization by removing directory emptiness validation and extraneous comments.

package/README.md

@@ -1,57 +1,76 @@
-<p align="center">
-  <img src="https://odac.run/assets/img/github/header.png?v=1" alt="Odac Header">
-</p>
 
-# ⚡ Odac
+# ⚡ ODAC.JS
 
-**Odac** is a lightweight yet powerful server + framework toolkit for building and deploying modern web apps with ease — with built-in automation and a developer-first philosophy.
+**ODAC** is a lightweight, high-performance Node.js framework designed to build modern, scalable web applications with ease. It allows developers to focus on building features rather than configuring boilerplate, offering a complete toolkit for web development.
 
 ## ✨ Key Features
 
-### Core Server Features
-
-*   ⚡ **Blazing Fast & Ultra Light:** Optimized for performance, Odac is significantly lighter and faster than traditional server solutions, ensuring maximum performance with minimal resource usage.
-*   🚀 **Zero-Config Hosting:** Leave the complex server configurations to Odac and focus solely on your code. Get your web applications up and running in minutes.
-*   🌐 **One Server, Many Domains:** Easily host and manage multiple websites on a single Odac instance, each with its own domain and resources.
-*   🔒 **SSL in Seconds:** Secure all your websites in seconds with free, auto-renewing SSL certificates.
-*   📬 **Native Mail Server:** A full-featured, built-in mail server (IMAP/SMTP) that allows you to create and manage email accounts for your domains without needing an external service.
-*   ⚙️ **Process & CLI Monitor:** Keep your applications running smoothly with the integrated process manager and monitor your server from anywhere with the powerful command-line tool.
-
-### Integrated Web Framework
-
-*   🔗 **Custom URLs & Infinite Pages:** Easily create clean, custom URLs and an unlimited number of pages thanks to the powerful routing and skeleton system.
-*   ✨ **No-Code AJAX:** Automatically enable AJAX for form submissions and page transitions without writing any custom JavaScript, providing your users with a seamless single-page application (SPA) experience.
-*   🛡️ **Safe Requests:** Automatically secure all your endpoints against common vulnerabilities like CSRF with built-in token verification for POST and GET requests.
-*   🔐 **Auth Made Easy:** Implement user authentication in minutes with built-in session management, password hashing, and ready-to-use login/register forms.
-*   🌍 **Global Ready:** Reach a worldwide audience with built-in, automatic multi-language support. The framework simplifies internationalization (i18n).
-*   ⏰ **Built-in Cron Jobs:** Schedule and automate recurring tasks with the integrated cron system, perfect for background jobs, data cleanup, and scheduled operations.
+*   🚀 **Developer Friendly:** Simple setup and intuitive API design let you start building immediately.
+*   🎨 **Built-in Tailwind CSS:** Zero-config integration with Tailwind CSS v4. Automatic compilation and optimization out of the box.
+*   🔗 **Powerful Routing:** Create clean, custom URLs and manage infinite pages with a flexible routing system.
+*   ✨ **Seamless SPA Experience:** Automatic AJAX handling for forms and page transitions eliminates the need for complex client-side code.
+*   🛡️ **Built-in Security:** Automatic CSRF protection and secure default headers keep your application safe.
+*   🔐 **Authentication:** Ready-to-use session management, password hashing, and authentication helpers.
+*   🗄️ **Database Agnostic:** Integrated support for major databases (PostgreSQL, MySQL, SQLite) and Redis via Knex.js.
+*   🌍 **i18n Support:** Native multi-language support to help you reach a global audience.
+*   ⏰ **Task Scheduling:** Built-in Cron job system for handling background tasks and recurring operations.
+*   ⚡ **Zero-Config Early Hints:** Intelligent HTTP 103 implementation that requires **no setup**. ODAC automatically analyzes your views and serves assets instantly, drastically improving load times without a single line of code.
+
+## 🛠️ Advanced Capabilities
+
+### ⚡ Cluster-Ready IPC
+Built for scale from day one, ODAC includes a powerful Inter-Process Communication (IPC) system.
+*   **Unified API:** Use the same `get`, `set`, `publish`, and `subscribe` methods regardless of the underlying driver.
+*   **Zero-Config Clustering:** The default `memory` driver automatically syncs data between Node.js cluster workers without external dependencies.
+*   **Redis Support:** Switch to the `redis` driver with a single config change to scale horizontally across multiple servers.
+
+### 🔌 Native WebSocket Support
+Real-time features are a first-class citizen in ODAC.
+*   **Integrated Server:** No need for third-party libraries; ODAC features a lightweight, native WebSocket implementation.
+*   **Room System:** Easily manage user groups with built-in `join`, `leave`, and `broadcast` to room functionality.
+*   **Route Integration:** define WebSocket endpoints directly in your router alongside HTTP routes.
+
+### 🎨 Powerful Templating
+ODAC's view engine combines the power of JavaScript with intuitive HTML tags.
+*   **Logic Tags:** Use `<odac:if>`, `<odac:for>`, and `<odac:else>` for clean control flow.
+*   **Async Support:** Fully asynchronous rendering allows fetching data directly within your views using `await`.
+*   **Safety:** Automatic escaping prevents XSS while allowing raw HTML output when explicitly requested.
 
 ## 🚀 Quick Start
 
-> 🔥 **Install with a single command. Works on Linux, macOS, and Windows.**
+Get your new ODAC project up and running in seconds using our CLI.
 
-#### Linux & macOS
+### Create a new project
 
 ```bash
-curl -sL https://odac.run/install | sudo bash
+npx odac init my-app
 ```
 
-#### Windows (PowerShell)
+### Start development
 
-```powershell
-irm https://odac.run/install | iex
+```bash
+cd my-app
+npm run dev
 ```
 
-This command:
+## 📂 Project Structure
 
-- Installs Node.js (v18+) if missing
-- Installs Odac globally via npm
-- Prepares your system for development or deployment
+```
+project/
+├── class/          # Business logic classes
+├── controller/     # HTTP request handlers
+├── middleware/     # Route middlewares
+├── public/         # Static assets
+├── route/          # Route definitions
+├── view/           # HTML templates
+├── .env            # Environment variables
+└── odac.json       # App configuration
+```
 
 ## 📚 Documentation
 
-For more detailed information and API reference, please check out our [official documentation website](https://docs.odac.run).
+For detailed guides, API references, and examples, visit our [official documentation](https://docs.odac.run).
 
 ## 📄 License
 
-This project is licensed under the AGPL-3.0 License. See the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.