@brightsideoy/kama 0.1.0-alpha.17 → 0.1.0-alpha.170

package/README.md

@@ -0,0 +1,169 @@
+# KAMA – Global Content Delivery at the Edge
+
+**[KAMA](https://kamaengine.com) is a schema-driven, headless Content Delivery Platform built to give you infinite edge scalability and total deployment flexibility.**
+
+Engineered natively for the Cloudflare ecosystem (Workers, D1, R2), KAMA eliminates the need for traditional origin servers for unmatched global performance—yet remains fully capable of running locally on your own virtual servers or VPS for complete control.
+
+<br>
+
+> <br>
+>
+> **ALPHA STATUS**
+>
+> KAMA is currently in early **Alpha**. This is a conceptual implementation of edge-native content delivery. While functional, the core architecture, schemas, and APIs are under rapid development and subject to breaking changes.
+> &nbsp;
+> <br>
+> <br>
+
+<br>
+
+## Usage & Licensing
+
+**KAMA is free to use for all kinds of projects. For commercial support get in touch with [Brightside OÜ](https://t3brightside.com).**
+
+The software is delivered in its current state without promises about performance, quality, or fitness for a specific purpose.
+<br>
+
+## The Concept: Edge-Native, Deployment-Agnostic
+
+1. **Compute Anywhere:** Deploy the backend to Cloudflare Workers to execute milliseconds away from users, or self-host it on a local virtual server/VPS using standard Node.js or edge-runtime containers.
+
+2. **Database Flexibility:** By default, data is stored in Cloudflare D1 (distributed SQLite) for edge-local queries. On a local server, this translates perfectly to standard SQLite, making it highly portable.
+
+3. **Storage at the Edge:** Media and assets are stored in Cloudflare R2 and served directly from the edge cache, but can easily be adapted for local storage solutions.
+4. **Single Source of Truth:** Your entire content model, UI forms, layouts, and database indexes are generated from simple YAML files stored alongside your frontend code.
+
+<br>
+
+## Core Features
+
+- **Zero-Config Admin UI:** No need to write React or Vue forms. Define your content model in a YAML file, and KAMA automatically generates the rich editing interface, validation rules, and layout logic.
+- **Vault vs. Tree Architecture:**
+  - **The Tree:** Hierarchical drag-and-drop routing for pages, navigation, and nested URLs.
+  - **The Vault:** A headless repository for structured, reusable data (e.g., Products, Office Locations, People) that can be queried via API or linked to Pages.
+- **Visual Canvas Builder:** An intuitive, block-based editor. Define your content regions, image drop zones and blocks (components) in YAML, and let editors compose pages safely without breaking the design system.
+- **Multi-Channel Native:** Manage multiple websites, apps, or regions from a single KAMA instance. Content can be shared across channels or isolated.
+- **Smart Media Engine:** Direct-to-R2 uploads with automated, schema-defined image cropping. Define aspect ratios in YAML, and the UI forces editors to crop images perfectly.
+- **Hybrid Deployment:** Deploy seamlessly to Cloudflare's global network, or run it on a local Linux/Windows virtual server for internal enterprise networks, staging environments, or self-hosted production.
+- **Astro First (But Framework Agnostic):** Comes with a built-in CLI to scaffold highly optimized Astro frontends that natively consume the KAMA API.
+
+<br>
+
+## Architecture & Tech Stack
+
+KAMA is built to leverage modern edge platforms while maintaining local portability:
+
+| Component     | Cloudflare Edge       | Local / Virtual Server             |
+| :------------ | :-------------------- | :--------------------------------- |
+| **Compute**   | Cloudflare Workers    | Node.js / `workerd` runtime        |
+| **Database**  | Cloudflare D1         | Local SQLite                       |
+| **Storage**   | Cloudflare R2         | S3-Compatible Storage / Local Disk |
+| **Caching**   | Cloudflare Edge Cache | In-memory / CDN pass-through       |
+| **CLI / Gen** | Node.js               | Node.js                            |
+
+<br>
+
+## Smart Edge Caching & Prewarming
+
+KAMA doesn't just serve content; it actively manages its lifecycle across the global edge network to guarantee absolute maximum cache hit ratios for your end users.
+
+- **Aggressive Edge Caching:** By default, all API responses and media assets are heavily cached directly at the edge layer. Database queries (D1) are bypassed entirely for cached requests.
+- **Targeted Invalidation (Purging):** When you publish a change in the KAMA Admin UI, the platform triggers a targeted Cloudflare Zone API purge. It invalidates only the modified content routes from the edge cache, leaving the rest of your site lightning fast.
+- **Automated Prewarming:** The moment a cache is purged, KAMA automatically sends background requests to "prewarm" the edge nodes with the fresh content. This means the very first organic visitor after a content update will still experience a rapid cache hit, completely hiding database latency.
+- **Zero-Config Management:** No Redis, Varnish, or complex CDN tagging rules to maintain. KAMA handles the edge invalidation and prewarming lifecycle out of the box.
+
+<br>
+
+## The Schema Engine
+
+At the heart of KAMA is the Schema Engine. Instead of complex database migrations, you define your content models, layouts, and reusable blocks in simple YAML files. KAMA dynamically bundles these definitions at build-time to auto-generate your entire Admin UI, database indexes, and API endpoints.
+
+<br>
+
+## Getting Started
+
+KAMA comes with a scaffolding CLI to instantly spin up a full monorepo (Backend + Astro Frontend).
+
+## 1. Initialize a Workspace
+
+```bash
+npx @brightsideoy/kama@latest
+```
+
+Select **"Kickstart new KAMA Monorepo"**. The CLI will automatically:
+
+- Authenticate with Cloudflare (if deploying to the Edge).
+- Create a new D1 database (or local SQLite equivalent).
+- Bind your R2 media buckets.
+- Setup the Worker backend and Astro frontend.
+
+## 2. Local Development
+
+Start the backend and frontend simultaneously on your local machine:
+
+```bash
+npm run dev:cms
+```
+
+This bundles your local YAML schemas, syncs the local SQLite/D1 database, and starts the Wrangler dev server on your localhost.
+
+## 3. Deploy
+
+Push your API, schemas, and database migrations to Cloudflare's global network, or package it for your virtual server:
+
+```bash
+npm run deploy:cms
+```
+
+<br>
+
+## Directory Structure Overview
+
+A standard KAMA workspace looks like this:
+
+```text
+my-kama-workspace/
+├── package.json
+├── content/                 # 👉 YOUR SCHEMA DEFINITIONS
+│   └── definitions/
+│       ├── nodes/           # e.g., page.yaml, product.yaml
+│       ├── blocks/          # e.g., hero.yaml, image_card.yaml
+│       └── node-layouts/    # e.g., two-column.yaml
+├── cms-worker/              # 👉 BACKEND PIPELINE
+│   ├── index.js             # Worker entrypoint (ES Module)
+│   ├── wrangler.json        # Bindings (D1, R2, Vars)
+│   └── package.json
+└── sites/                   # 👉 YOUR FRONTENDS
+    └── brand-website/       # (e.g., Astro project)
+        ├── src/
+        ├── astro.config.mjs
+        └── wrangler.json
+```
+
+<br>
+
+## API Usage (Frontend)
+
+Because KAMA is a headless Content Delivery Platform, fetching data from the edge (or your local server) is incredibly fast.
+
+```javascript
+// Fetch a navigation tree
+const response = await fetch(
+  "[https://admin.yourdomain.com/api/v1/tree/main-nav?channelId=website](https://admin.yourdomain.com/api/v1/tree/main-nav?channelId=website)",
+);
+const menu = await response.json();
+
+// Fetch a specific node/page by slug
+const pageResponse = await fetch(
+  "[https://admin.yourdomain.com/api/v1/node/about-us?channelId=website](https://admin.yourdomain.com/api/v1/node/about-us?channelId=website)",
+);
+const pageData = await pageResponse.json();
+```
+
+_(When deployed to Cloudflare, all responses are heavily cached at the Edge, ensuring near-instantaneous TTFB)._
+
+<br>
+
+## Development & maintenance
+
+[Brightside OÜ – Web development and hosting specialised web agency](https://t3brightside.com/)