@brightsideoy/kama 0.1.0-alpha.14 → 0.1.0-alpha.141

package/README.md

@@ -0,0 +1,195 @@
+# KAMA – Global Content Delivery at the Edge
+
+**KAMA 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 strictly free for non-commercial, non-profit, educational, and government use.**
+
+You are completely free to use KAMA for personal projects, educational institutions, registered non-profits, government agencies, hobby blogs, and conceptual experimentation.
+
+**Commercial Use Prohibited:** You may not use KAMA for for-profit commercial purposes (including paid client projects, monetized websites, SaaS products, or internal corporate business operations) without an explicit commercial license. If you are interested in using KAMA commercially, please **[contact us](https://t3brightside.com)** for licensing details.
+
+<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.
+
+**[Read the full Schema Documentation here](/@brightsideoy/kama/documentation/SCHEMAS.md)**
+
+<br>
+
+## Getting Started
+
+KAMA comes with an interactive executable CLI to instantly spin up a full monorepo (Backend Worker + optional Astro Frontend), add new sites to existing workspaces, or promote local setups to Cloudflare Edge.
+
+### 1. Initialize a Workspace\*\*
+
+Run the KAMA CLI to start the workspace wizard:
+
+```bash
+npx kama init
+```
+
+The CLI will prompt you for your setup preferences and automatically:
+
+- Scaffold the `kama-worker` engine and content definition directories (`content/definitions/`).
+- Authenticate with Cloudflare and auto-provision a remote D1 database + R2 bucket bindings (if deploying to Edge).
+- Scaffold a fully configured Astro frontend site inside `sites/` with built-in edge-caching middleware.
+- Configure local SQLite fallback environments for completely offline development.
+
+### 2. Local Development
+
+Start the local CMS dev server from your workspace root:
+
+```bash
+npm run dev:cms
+```
+
+This command automatically compiles your YAML/JSON schemas into runtime JavaScript definitions, syncs your local SQLite database, and launches the Miniflare worker environment on `http://localhost:8787`.
+
+### 3. Management Commands\*\*
+
+You can run CLI commands anytime inside your workspace.
+
+#### Add a New Astro Frontend Site
+
+```bash
+npx kama add site
+```
+
+#### Promote a Local Workspace to Cloudflare Edge
+
+Convert a local offline workspace to Cloudflare Edge (auto-links domains & D1 databases):
+
+```bash
+npx kama promote
+```
+
+### 4. Deploy
+
+Deploy your CMS engine, content definitions, and database migrations to Cloudflare Edge:
+
+```bash
+npm run deploy:cms
+```
+
+> **Note:** For self-hosted virtual servers (VPS) or Docker environments, you can run `npm run dev:cms` under PM2/Docker as a standalone `workerd` server.
+> <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
+├── kama-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/)