From 744c8a833b8d17d4723b9acf8efc8690c9ebc3f1 Mon Sep 17 00:00:00 2001
From: mmabdalla <101379618+mmabdalla@users.noreply.github.com>
Date: Sun, 28 Dec 2025 14:38:51 +0200
Subject: [PATCH] Initial commit: Add documentation and issue tracking for
BP_WB project
---
.cursor/rules/00-base-safety.mdc | 19 +
.cursor/rules/bosa_constitution.md | 890 ++++
.cursor/rules/change-discipline.mdc | 11 +
.cursor/rules/no-hallucinations.mdc | 10 +
.cursor/rules/testing-first.mdc | 13 +
.cursor/worktrees.json | 5 +
.gitignore | 51 +
README.md | 43 +
docs/BP_WB_DEVELOPMENT_ROADMAP.md | 387 ++
docs/BP_WB_FEATURES_LIST.md | 659 +++
docs/BP_WB_LINEAR_ISSUES.md | 1659 +++++++
docs/DEVELOPER_GUIDE.md | 6543 +++++++++++++++++++++++++++
12 files changed, 10290 insertions(+)
create mode 100644 .cursor/rules/00-base-safety.mdc
create mode 100644 .cursor/rules/bosa_constitution.md
create mode 100644 .cursor/rules/change-discipline.mdc
create mode 100644 .cursor/rules/no-hallucinations.mdc
create mode 100644 .cursor/rules/testing-first.mdc
create mode 100644 .cursor/worktrees.json
create mode 100644 .gitignore
create mode 100644 README.md
create mode 100644 docs/BP_WB_DEVELOPMENT_ROADMAP.md
create mode 100644 docs/BP_WB_FEATURES_LIST.md
create mode 100644 docs/BP_WB_LINEAR_ISSUES.md
create mode 100644 docs/DEVELOPER_GUIDE.md
diff --git a/.cursor/rules/00-base-safety.mdc b/.cursor/rules/00-base-safety.mdc
new file mode 100644
index 0000000..2301c40
--- /dev/null
+++ b/.cursor/rules/00-base-safety.mdc
@@ -0,0 +1,19 @@
+---
+description: Core safety – always applied to every request
+globs: ["**/*"]
+alwaysApply: true
+---
+
+You are an expert engineer working on a production codebase. Your #1 priority is **never break existing functionality**.
+
+## Critical Rules (never violate these)
+- NEVER delete or rename files without explicit user confirmation.
+- NEVER make changes to more than 5 files at once unless the user explicitly says “go ahead with the full refactor”.
+- NEVER invent non-existent functions, env vars, APIs, or packages. If unsure, ask for clarification or @ the relevant file.
+- NEVER commit or apply changes that haven’t passed tests. Always run the test suite first.
+- If tests fail or you detect a regression risk, stop and report it immediately.
+- Always prefer small, incremental changes over large sweeping refactors.
+- Before any multi-file change: propose a clear plan first, wait for approval.
+- If the user asks for something risky (e.g., “rewrite everything”), push back and suggest incremental steps.
+- Do not hallucinate. If you don’t know → say “I’m not sure, can you @ the file or clarify?”
+- Always think step-by-step and show your reasoning before code.
\ No newline at end of file
diff --git a/.cursor/rules/bosa_constitution.md b/.cursor/rules/bosa_constitution.md
new file mode 100644
index 0000000..a6150ef
--- /dev/null
+++ b/.cursor/rules/bosa_constitution.md
@@ -0,0 +1,890 @@
+# BOSA Platform - Constitution
+
+## ⚠️ CRITICAL VERSION BUMPING RULE (READ FIRST) ⚠️
+
+### NEVER EVER REVERSE VERSION NUMBERS BACKWARDS
+
+**THIS IS THE #1 MOST IMPORTANT RULE - VIOLATING THIS CAUSES SEVERE PROJECT DISRUPTION**
+
+**The Rule:**
+- **Version numbers can ONLY increase, NEVER decrease**
+- **The source of truth for current version is `version.txt` file, NOT git HEAD**
+- **If `version.txt` shows build number 077 and git HEAD shows 068, git hasn't been updated yet**
+- **ALWAYS bump ABOVE the higher number found in `version.txt`** (NOT git HEAD)
+
+**Examples:**
+- ✅ `version.txt` shows 0.0.2.077, git shows 0.0.2.068 → bump to **0.0.2.078**
+- ✅ `version.txt` shows 0.0.2.100, git shows 0.0.2.050 → bump to **0.0.2.101**
+- ❌ `version.txt` shows 0.0.2.077, git shows 0.0.2.068 → bump to **0.0.2.069** ← **WRONG! VIOLATION!**
+
+**Why This Matters:**
+- Decreasing version numbers causes confusion and tracking issues
+- Git HEAD may be outdated - local `version.txt` is the current state
+- This rule prevents critical project management disruptions
+
+**VIOLATION CONSEQUENCE**: Reversing version numbers is a P0 violation that causes severe project disruption. Always check `version.txt` first, never git HEAD, and always bump forward.
+
+---
+
+## Core Principles
+
+### I. Radical Simplicity (ABSOLUTE)
+**"WordPress for Business Apps" - If it's not this simple, it's wrong.**
+- Binary installation MUST complete in under 60 seconds
+- Plugin installation MUST complete in under 30 seconds
+- Default configuration MUST work with ZERO editing
+- Developer documentation MUST fit in AI context window (~10K tokens)
+- Core kernel MUST remain under 5,000 lines of code
+- Each component file MUST be under 500 lines
+- If a feature requires >100 lines, it's a plugin, not core
+
+**VIOLATION CONSEQUENCE**: Feature bloat kills adoption. Complexity is the enemy.
+
+### II. NO CREATIVITY RULE (NON-NEGOTIABLE - NEVER VIOLATE)
+**DO ONLY WHAT THE USER EXPLICITLY ASKS - NOTHING MORE**
+- If user says "implement HTTP server" → Implement ONLY HTTP server. NO WebSocket "extras"
+- If user says "fix database adapter" → Fix ONLY database adapter. Do NOT refactor other code
+- If user says "create 3 files" → Create EXACTLY 3 files. NOT 4, NOT 5
+- NEVER create "helpful" extra files, scripts, or documentation unless explicitly requested
+- NEVER add "nice to have" features or "while I'm at it" improvements
+- NEVER anticipate needs or be "creative" beyond the exact request
+- ASK before doing ANYTHING beyond the literal request
+
+**HISTORICAL VIOLATIONS TO AVOID**:
+- Creating 10+ "helper" utilities when asked to implement one function
+- Adding "comprehensive" error handling when asked for basic validation
+- Creating entire plugin examples when asked for SDK function
+- Refactoring working code when asked to add new feature
+
+**THE RULE**: Read request → Do EXACTLY that → STOP → Ask before extras
+
+### II-A. NO ASSUMPTIONS RULE (CRITICAL - NEVER VIOLATE)
+**DO NOT JUMP TO CONCLUSIONS - ASK FIRST BEFORE IMPLEMENTING**
+
+- When user asks a question → ANSWER the question. Do NOT implement solutions
+- When user asks "can you help with X?" → Explain HOW you can help, then WAIT for confirmation
+- When user asks about possibilities → List options, then WAIT for user to choose
+- NEVER create files, scripts, or code unless user explicitly says "create", "implement", "do it"
+- NEVER assume user wants automation when they ask "can you help"
+- NEVER waste tokens implementing things that will be reverted
+
+**CRITICAL PATTERN**:
+1. User asks question → Answer question
+2. User asks "can you do X?" → Say "Yes, I can do X by [method]. Should I proceed?"
+3. User asks "is it possible?" → Say "Yes, here are the options: [list]. Which do you prefer?"
+4. WAIT for explicit confirmation before creating ANY files or code
+
+**HISTORICAL VIOLATIONS TO AVOID**:
+- Creating import scripts when user asked "can you help add issues to Linear?"
+- Implementing features when user asked "is it possible to do X?"
+- Writing code when user asked a question about how something works
+- Adding files when user asked about documentation options
+
+**THE RULE**: Question → Answer → Wait → Confirm → Then implement
+
+**TOKEN CONSERVATION**: Wasted tokens from reverted work = wasted money. Always confirm first.
+
+### III. Plugin-First Architecture (MANDATORY)
+Every feature beyond core (HTTP, Auth, Data, Events, Real-time) MUST be a plugin.
+
+**Core Kernel Responsibilities (ONLY THESE):**
+- HTTP/WebSocket server
+- JWT authentication
+- Database abstraction layer
+- Event bus (in-memory → Redis)
+- Plugin lifecycle management
+- Static file serving
+- Admin web UI (minimal)
+
+**Everything Else is a Plugin:**
+- Business logic (CRM, inventory, invoicing, etc.)
+- UI components beyond admin
+- Third-party integrations
+- Reporting and analytics
+- Custom workflows
+- Email/SMS sending
+- File uploads/storage
+
+**Plugin Communication Rules:**
+- Plugins CANNOT access kernel internals directly
+- Plugins CANNOT communicate with each other directly
+- All plugin communication via kernel APIs (REST/gRPC/WebSocket)
+- All plugin interactions MUST be logged for debugging
+- Plugin failures MUST NOT crash kernel
+
+**Plugin Naming Convention:**
+```
+plugins/[name]-[language]/
+ manifest.yaml
+ [entry-file].[ext]
+ migrations/
+ templates/
+ static/
+```
+
+Examples: `crm-php`, `inventory-js`, `analytics-py`, `pos-lua`
+
+### IV. Multi-Language Support (REQUIRED)
+Plugins MUST be writable in ANY language the developer prefers.
+
+**Tier 1 Support (Built-in):**
+- **Lua**: Embedded runtime, sandboxed, ~5MB overhead
+- **JavaScript/Node.js**: Process isolation, npm ecosystem
+- **PHP**: php-fpm process, composer packages
+- **Python**: Process isolation, pip packages
+- **Go**: Native binary compilation
+
+**Tier 2 Support (Docker):**
+- Ruby, Rust, Java, C#, etc. via Docker containers
+
+**SDK Requirements:**
+- Each language MUST have official SDK: `bosa-sdk-[lang]`
+- SDKs MUST provide identical API surface (parity required)
+- SDKs MUST handle serialization/connection automatically
+- SDKs MUST include TypeScript/JSDoc for IDE support
+
+**Plugin API Contract:**
+```
+Database:
+ - query(table).where().orderBy().limit().get()
+ - query(table).insert(data)
+ - query(table).update(data)
+ - query(table).delete()
+ - transaction(callback)
+
+Events:
+ - publish(type, data)
+ - subscribe(type, handler)
+
+Real-time:
+ - broadcast(channel, message)
+ - sendToUser(userId, message)
+ - presence(channel)
+ - join(channel, metadata)
+
+HTTP:
+ - route(method, path, handler)
+ - request.body, request.params, request.query
+ - response.json(), response.render()
+```
+
+### V. Multi-Database Abstraction (MANDATORY)
+Database layer MUST be completely abstracted - plugins NEVER write database-specific SQL.
+
+**Supported Databases (Adapters Required):**
+- SQLite (default - zero config)
+- PostgreSQL (production standard)
+- MySQL/MariaDB (web hosting compatibility)
+- MongoDB (document store optional)
+
+**Repository Pattern Requirements:**
+- All database access through `DatabaseAdapter` interface
+- Query builder MUST work identically across all databases
+- Migrations MUST be database-agnostic SQL
+- Connection pooling managed by kernel
+- Transactions MUST work across all adapters
+
+**Adapter Interface (Go):**
+```go
+type DatabaseAdapter interface {
+ Connect(config) error
+ Close() error
+ Query(table string) QueryBuilder
+ Execute(sql string, args ...interface{}) (Result, error)
+ Migrate(migrations []Migration) error
+ BeginTransaction() (Transaction, error)
+}
+```
+
+**Plugin Usage (Language-Agnostic API):**
+```javascript
+// Same code works with SQLite, Postgres, MySQL, MongoDB
+const customers = await bosa.db.query('customers')
+ .where('status', '=', 'active')
+ .orderBy('created_at', 'desc')
+ .limit(50)
+ .get();
+```
+
+**Database Migration Rules:**
+- Migrations MUST be sequential numbered files: `001_initial.sql`, `002_add_columns.sql`
+- Migrations MUST support up AND down (rollback)
+- Schema changes MUST be tested on ALL supported databases
+- NEVER use database-specific features unless in adapter code
+- Migration from SQLite → Postgres MUST be one command: `bosa db migrate --to postgres`
+
+### VI. Real-Time First (REQUIRED)
+Real-time capabilities MUST be built into kernel, not bolted on later.
+
+**WebSocket Server Requirements:**
+- Sub-50ms event propagation (p95 target)
+- Support 10,000+ concurrent connections per instance
+- Automatic reconnection with exponential backoff
+- Graceful fallback: WebSocket → SSE → Long-polling
+- Channel-based pub/sub with presence detection
+
+**Real-Time Features (Built-in):**
+- Event broadcasting to channels
+- User-specific messaging
+- Presence tracking (who's online)
+- Typing indicators
+- Live data synchronization
+
+**Plugin Real-Time API:**
+```php
+// Broadcast to all clients on channel
+$bosa->realtime->broadcast('dashboard', [
+ 'type' => 'data.updated',
+ 'data' => $newData
+]);
+
+// Get presence info
+$viewers = $bosa->realtime->presence('customer.123');
+```
+
+**Performance Targets:**
+- Event latency: <50ms p95
+- Message throughput: 50,000 msg/s per instance
+- Memory per connection: <10KB
+- Reconnection time: <2s
+
+### VII. Test-First Development (NON-NEGOTIABLE)
+**TDD Mandatory: Tests → User Approval → Fail → Implement → Pass**
+
+**Testing Pyramid:**
+```
+ E2E Tests (5%)
+ Integration Tests (15%)
+ Unit Tests (80%)
+```
+
+**Unit Testing (Go):**
+- Every function MUST have test
+- Table-driven tests preferred
+- Mocks for external dependencies
+- Coverage target: 85%+
+
+**Integration Testing:**
+- Database adapters tested on ALL supported DBs
+- Plugin SDK tested in ALL supported languages
+- WebSocket tested with 1000+ concurrent connections
+- API endpoints tested with realistic payloads
+
+**E2E Testing:**
+- Critical paths: install → start → create plugin → deploy
+- Real browser tests with Playwright/Cypress
+- Multi-browser: Chrome, Firefox, Safari
+- Mobile responsive testing
+
+**CI/CD Requirements:**
+- All tests MUST pass before merge
+- No manual testing as gate for deployment
+- Automated benchmarks on every PR
+- Performance regression = failed build
+
+**Test File Organization:**
+```
+internal/core/
+ server.go
+ server_test.go # Unit tests
+
+tests/
+ integration/
+ database_test.go # All DB adapters
+ plugins_test.go # Multi-language plugins
+ e2e/
+ install_test.go
+ plugin_lifecycle_test.go
+```
+
+### VIII. Go-First Kernel, Language-Agnostic Plugins
+**Kernel: 100% Go. Plugins: Developer's choice.**
+
+**Why Go for Kernel:**
+- Single binary compilation
+- Excellent concurrency (goroutines)
+- Fast compile times (<5s for full build)
+- Strong typing without ceremony
+- Stdlib is production-ready
+- Cross-platform compilation
+
+**Go Code Standards:**
+- Standard library preferred over frameworks
+- Minimal dependencies (<20 total)
+- Go modules for dependency management
+- gofmt + golint mandatory
+- Meaningful error messages
+- Context propagation for timeouts
+
+**Forbidden in Kernel:**
+- Web frameworks (use stdlib)
+- ORMs (use database/sql directly)
+- Complex abstractions (KISS principle)
+- Reflection (except SDK bindings)
+- Global state (pass dependencies)
+
+**CGO Build Requirements (CRITICAL - NEVER FORGET):**
+BOSA uses SQLite via `github.com/mattn/go-sqlite3` which requires CGO. The build system MUST handle CGO compilation correctly.
+
+**Solution for CGO Build Errors:**
+1. **Use Clang instead of GCC (RECOMMENDED)** - Better compatibility, especially with GCC 15+
+ - Install Clang via MSYS2: `pacman -S mingw-w64-x86_64-clang`
+ - Build script automatically detects and uses Clang if available
+ - Sets `CC=clang` and `CGO_CFLAGS="-Oz -g0"` automatically
+
+2. **Why Clang?**
+ - GCC 15+ has known incompatibility with Go's CGO (github.com/golang/go/issues)
+ - Clang has better compatibility with newer toolchains
+ - No need to downgrade GCC - just use Clang
+
+3. **Build Script Behavior:**
+ - Automatically checks for Clang first (preferred)
+ - Falls back to GCC if Clang not found
+ - Warns if GCC 15+ detected (incompatible)
+ - Provides clear error messages with solutions
+
+4. **Manual Build (if needed):**
+ ```powershell
+ $env:CGO_ENABLED = "1"
+ $env:CC = "clang"
+ $env:CGO_CFLAGS = "-Oz -g0"
+ go build ./cmd/bosa
+ ```
+
+5. **Error Pattern to Recognize:**
+ - `runtime/cgo: cgo.exe: exit status 2` = CGO compilation failed
+ - Usually means GCC 15+ incompatibility or missing C compiler
+ - Solution: Install Clang or use build script (auto-detects)
+
+**VIOLATION CONSEQUENCE**: CGO build failures block all development. Always use Clang or ensure GCC <15.
+
+**File Structure:**
+```
+bosa/
+ cmd/
+ bosa/
+ main.go # <100 lines
+ internal/
+ core/
+ server.go # <500 lines
+ auth.go # <300 lines
+ database/
+ adapter.go # <200 lines
+ sqlite.go # <300 lines
+ postgres.go # <300 lines
+ realtime/
+ hub.go # <400 lines
+ plugins/
+ manager.go # <500 lines
+ runtime_lua.go # <300 lines
+ runtime_node.go # <300 lines
+ runtime_php.go # <300 lines
+```
+
+**AI Development Guidelines for Go:**
+- Every function has clear purpose comment
+- No "clever" code - readability over brevity
+- Error handling explicit, not hidden
+- Interfaces small and focused
+- Structs document field purposes
+- All functionality must have Development (dev) and Production (prd) logging.
+
+
+### IX. AI-First Development Patterns
+**Code MUST be optimized for AI comprehension and generation.**
+
+**File Size Limits (Strict):**
+- Any file >500 lines MUST be split
+- Any function >50 lines MUST be refactored
+- Total kernel codebase <10K lines (fits in AI context)
+
+**Documentation Requirements:**
+- Every file has purpose header:
+```go
+// File: server.go
+// Purpose: HTTP and WebSocket server initialization
+// Dependencies: database, auth, realtime
+// Used by: main.go
+// AI Notes: Single entry point, no global state
+```
+
+- Every function documented:
+```go
+// CreateCustomer inserts a new customer record
+// Input: customer data map (name, email required)
+// Output: customer ID or error
+// Side effects: Publishes customer.created event
+func CreateCustomer(data map[string]interface{}) (int64, error) {
+ // Implementation
+}
+```
+
+**Consistent Patterns:**
+- All database operations via repository pattern
+- All plugin communication via SDK
+- All configuration via config.yaml + env vars
+- All errors use standard error types
+
+**AI Prompting Guide:**
+```
+Good Prompt:
+"Implement SQLite database adapter following the DatabaseAdapter
+interface in internal/core/database/adapter.go. Include connection
+pooling and query builder. Reference postgres.go for patterns."
+
+Bad Prompt:
+"Add database support"
+```
+
+### X. Security by Design
+**Security CANNOT be an afterthought.**
+
+**Authentication:**
+- JWT tokens with 15-minute expiry
+- Refresh tokens with 7-day expiry (rotating)
+- Tokens stored in httpOnly cookies (web) or secure storage (mobile)
+- Password hashing: bcrypt cost 12
+- Failed login rate limiting: 5 attempts per 5 minutes
+
+**Authorization:**
+- Role-based access control (RBAC) in core
+- Plugin-level permissions in manifest
+- API endpoint authorization middleware
+- Channel-level authorization for WebSocket
+
+**Data Protection:**
+- All passwords hashed (never plaintext)
+- Sensitive config in environment variables
+- SQL injection prevention via parameterized queries
+- XSS prevention via template escaping
+- CSRF tokens for state-changing operations
+
+**Plugin Sandboxing:**
+- Plugins run in separate processes
+- Resource limits (CPU, memory) enforced
+- File system access restricted
+- Network access controlled
+- System calls limited via seccomp (future)
+
+**Security Headers (Required):**
+```
+Strict-Transport-Security: max-age=31536000
+X-Frame-Options: DENY
+X-Content-Type-Options: nosniff
+Content-Security-Policy: default-src 'self'
+```
+
+### XI. Operational Excellence
+**System MUST be operable by non-technical users.**
+
+**App/Plugin Deployment Locations (MANDATORY):**
+
+**Development Location:**
+- Apps/plugins can be developed **anywhere** on the developer's machine
+- Example: `D:\dev\projects\My Todo App\`, `C:\Users\Name\apps\todo\`, etc.
+- Contains: source code, `.git/`, `node_modules/`, tests, development files
+
+**Deployment Location (Local Development):**
+- **Local Dev:** `D:\dev\projects\bosa\apps\` (relative to BOSA project root)
+- Configured in `config.yaml` → `plugins.directory`
+- This is where BOSA installs apps/plugins when uploading `.zip` files or using `bosa plugin install`
+- Apps are installed to: `D:\dev\projects\bosa\apps\[app-name]\`
+
+**Deployment Location (Production/Namecheap):**
+- **Production:** `./apps` (relative to `/bosa` base directory on server)
+- On Namecheap: `/home/meaivgfb/bosa/apps/`
+- Configured automatically in deployment scripts
+- Apps are installed to: `/home/meaivgfb/bosa/apps/[app-name]/`
+
+**Separation Rules:**
+- ✅ Development location: Anywhere (developer's choice)
+- ✅ Deployment location: Always `apps/` directory under BOSA base
+- ✅ Never develop directly in deployment directory
+- ✅ Always use packaging script to create deployment `.zip` files
+- ✅ Deployment scripts automatically create `apps/` directory if missing
+
+**Configuration:**
+- Local dev: `config.yaml` → `plugins.directory: "D:/dev/projects/bosa/apps"`
+- Production: `config.yaml` → `plugins.directory: "./apps"` (relative path)
+
+**Installation Requirements:**
+- Zero-config default: `bosa init && bosa serve`
+- Guided setup wizard in web UI
+- Automatic database initialization
+- Health checks on startup
+
+**Observability (Built-in):**
+- `/health` endpoint (Kubernetes-compatible)
+- `/metrics` endpoint (Prometheus format)
+- Structured JSON logging
+- Request tracing with correlation IDs
+
+### XI-A. Comprehensive Logging System (MANDATORY)
+**All operations MUST be logged. Logging behavior differs by environment.**
+
+**Development Mode (BOSA_DEV_MODE=true or plugins.hot_reload=true):**
+- ALL operations MUST be logged automatically
+- Debug-level logging enabled by default
+- HTTP requests: ALL requests logged (method, path, status, duration)
+- Database operations: ALL queries logged (table, operation, parameters)
+- Plugin operations: ALL plugin lifecycle events logged (load, unload, errors)
+- Authentication events: ALL login attempts, failures, token refreshes logged
+- Event bus: ALL events published/subscribed logged
+- Error tracking: ALL errors with stack traces logged
+- No logging toggles - always enabled for debugging
+
+**Production Mode (BOSA_DEV_MODE=false and plugins.hot_reload=false):**
+- Logging is OPTIONAL and toggleable by super admin
+- Default state: Logging DISABLED (performance optimization)
+- Super admin can enable/disable via `/api/admin/logging/toggle` endpoint
+- When enabled in production: Log only WARN and ERROR levels by default
+- When enabled in production: HTTP requests logged at INFO level
+- Database errors: Always logged regardless of toggle (critical for debugging)
+- Authentication failures: Always logged regardless of toggle (security requirement)
+- Log buffer size: 1000 entries (configurable via config.yaml)
+- Log retention: In-memory only (cleared on restart)
+
+**Logging Requirements for ALL Functions:**
+- Every function MUST include logging at entry/exit points
+- Every error MUST be logged with context (function name, parameters, error message)
+- Every database operation MUST be logged (table, operation, success/failure)
+- Every HTTP request/response MUST be logged (method, path, status, duration)
+- Every plugin operation MUST be logged (plugin name, operation, success/failure)
+- Every authentication event MUST be logged (user, action, success/failure)
+- Every configuration change MUST be logged (what changed, by whom, when)
+
+**Log Levels (Standard):**
+- **DEBUG**: Detailed diagnostic information (dev mode only)
+- **INFO**: General informational messages (server start, plugin loaded, HTTP requests)
+- **WARN**: Warning messages (non-critical issues, deprecation notices)
+- **ERROR**: Error messages (failed operations, exceptions)
+
+**Log Format (Structured):**
+```json
+{
+ "timestamp": "2025-11-25T10:28:36Z",
+ "level": "info",
+ "message": "HTTP request processed",
+ "source": "http",
+ "method": "GET",
+ "path": "/api/plugins",
+ "status": 200,
+ "duration_ms": 45
+}
+```
+
+**Log Buffer Management:**
+- Maximum size: 1000 entries (configurable)
+- FIFO eviction: Oldest entries removed when limit reached
+- Filtering: By level (debug, info, warn, error, all)
+- Export: CSV format via `/api/logs/export`
+- Clear: Via `/api/logs` DELETE endpoint (super admin only)
+
+**Super Admin Logging Controls:**
+- GET `/api/admin/logging/status` - Get current logging state (enabled/disabled, level, buffer size)
+- POST `/api/admin/logging/toggle` - Toggle logging on/off (production only)
+- PUT `/api/admin/logging/config` - Update logging configuration (level, buffer size, production only)
+- All logging controls require super_admin role
+
+**Performance Considerations:**
+- Logging MUST NOT block operations (async where possible)
+- Log buffer MUST use efficient data structures (slice with mutex)
+- Production mode with logging disabled: Near-zero overhead (<1% CPU)
+- Production mode with logging enabled: <5% CPU overhead
+
+**Security Requirements:**
+- Sensitive data MUST NOT be logged (passwords, tokens, PII)
+- Authentication tokens: Log only presence, never full value
+- Database passwords: Never logged
+- User emails: Log only for authentication events
+- Logs accessible only to super_admin role
+
+**VIOLATION CONSEQUENCE**: Missing logs = debugging nightmare. All operations without logs are bugs.
+
+**Backup & Recovery:**
+- One-command backup: `bosa backup create`
+- One-command restore: `bosa backup restore [file]`
+- Automatic daily backups (configurable)
+- Export/import between databases
+
+**Upgrades:**
+- Zero-downtime rolling updates
+- Automatic schema migrations
+- Rollback support
+- Version compatibility checks
+
+**Monitoring Targets:**
+- System uptime: 99.9% (43 min/month downtime)
+- API response time: <200ms p95
+- WebSocket latency: <50ms p95
+- Database query time: <100ms p95
+- Memory usage: <500MB idle, <2GB under load
+
+### XII. Performance Requirements
+**Performance is a feature, not an optimization.**
+
+**Response Time Targets:**
+| Operation | Target | Measurement |
+|-----------|--------|-------------|
+| API CRUD | <100ms p95 | End-to-end |
+| Database query | <50ms p95 | Indexed lookups |
+| WebSocket event | <50ms p95 | Delivery time |
+| Plugin cold start | <5s | Process spawn |
+| Page load | <2s | First contentful paint |
+
+**Scalability Targets:**
+| Metric | Target | Growth Path |
+|--------|--------|-------------|
+| Concurrent users | 100 (SQLite) → 10K (Postgres) | Add replicas |
+| API throughput | 1K req/s (single) → 100K req/s (cluster) | Horizontal scaling |
+| Database size | 1GB (SQLite) → 1TB+ (Postgres) | Sharding |
+| WebSocket connections | 1K (single) → 100K (Redis pub/sub) | Load balancer |
+
+**Optimization Rules:**
+- Database queries MUST use indexes
+- N+1 queries are bugs, not features
+- Caching MUST be explicit, not implicit
+- Asset compression MUST be enabled
+- CDN integration for static files
+
+**Benchmarking (Required):**
+- Every PR MUST include benchmark results
+- Regressions >10% MUST be explained
+- Load testing before major releases
+- Database query profiling enabled in dev
+
+### XIII. Growth Path Architecture
+**System MUST scale from laptop to cloud without rewrites.**
+
+**Stage 1: Development (Laptop)**
+- SQLite database (one file)
+- In-memory events
+- Single binary
+- Cost: $0
+
+**Stage 2: Small Business (VPS)**
+- SQLite still works OR switch to Postgres
+- Optional Redis for caching
+- nginx reverse proxy
+- Cost: $10-20/month
+
+**Stage 3: Growing Company (Cloud)**
+- PostgreSQL managed instance
+- Redis for events + cache
+- Load balancer (2-3 instances)
+- Cost: $100-200/month
+
+**Stage 4: Enterprise (Kubernetes)**
+- PostgreSQL cluster with replicas
+- Redis cluster
+- Multiple BOSA instances (auto-scaled)
+- CDN for static assets
+- Cost: $500-1,000/month
+
+**Critical Rule**: Same codebase, same config format, zero code changes at each stage.
+
+### XIV. Documentation Standards
+**Documentation is code, not an afterthought.**
+
+**Required Documentation:**
+- `README.md`: Quick start (5-minute setup)
+- `docs/ARCHITECTURE.md`: System design overview
+- `docs/API.md`: Complete API reference
+- `docs/PLUGINS.md`: Plugin development guide
+- `docs/DEPLOYMENT.md`: Production deployment guide
+
+**Plugin Documentation:**
+- Every plugin MUST have `README.md`
+- Installation instructions
+- Configuration options
+- API endpoints exposed
+- Event subscriptions/publications
+- Example usage
+
+**Code Comments (When Required):**
+- Why, not what (code shows what)
+- Non-obvious decisions
+- Performance trade-offs
+- Security considerations
+- TODO items with GitHub issue links
+
+**Documentation Generation:**
+- OpenAPI/Swagger from code annotations
+- SDK docs from JSDoc/GoDoc comments
+- Architecture diagrams in Mermaid format
+- Examples must be runnable code
+
+### XV. Internationalization (i18n)
+**Global readiness from day one.**
+
+**Language Support:**
+- English (primary)
+- Arabic with RTL support (secondary)
+- Framework for community translations
+
+**Implementation:**
+- JSON files for UI strings
+- `t('key')` function in all UIs
+- Locale-aware date/time formatting
+- Currency formatting with Intl API
+- Number formatting (Western vs Arabic numerals)
+
+**RTL Support:**
+- CSS logical properties (start/end vs left/right)
+- Bidirectional text rendering
+- Mirrored layouts for RTL languages
+- Icon orientation adjustments
+
+### XVI. Mobile-First Considerations
+**Desktop second, mobile first.**
+
+**Responsive Design:**
+- All UI MUST work on 320px width
+- Touch-friendly targets (44px minimum)
+- No hover-dependent interactions
+- Optimized images (WebP with fallback)
+
+**Progressive Web App (PWA):**
+- Service worker for offline capability
+- App manifest for "Add to Home Screen"
+- Push notifications for real-time updates
+- Background sync for offline actions
+
+**Native Mobile (Future):**
+- React Native for iOS/Android
+- Shared API client with web
+- Biometric authentication
+- Camera integration for work orders
+
+## Business Logic Constraints
+
+### User Management Rules
+- Email addresses MUST be unique globally
+- Passwords MUST meet complexity requirements (12+ chars, special chars)
+- Role changes MUST be logged with who/when/why
+- Account deletion MUST be soft delete (preserve history)
+- Failed login attempts MUST be logged for security monitoring
+
+### Plugin Lifecycle Rules
+- Plugin installation MUST be atomic (success or rollback)
+- Plugin upgrades MUST run migrations automatically
+- Plugin removal MUST clean up database tables
+- Plugin failures MUST NOT crash kernel
+- Plugin resource usage MUST be monitored and limited
+
+### Data Consistency Rules
+- Database transactions MUST be used for multi-step operations
+- Event publishing MUST use transactional outbox pattern
+- Cache invalidation MUST happen synchronously with writes
+- Concurrent updates MUST use optimistic locking
+- Data migrations MUST be tested on copy of production data
+
+## Violation Consequences
+
+### Severity Levels
+
+**P0 - Immediate Rejection:**
+- NO CREATIVITY rule violations (extra files, features)
+- NO ASSUMPTIONS rule violations (implementing without confirmation)
+- Security vulnerabilities (SQL injection, XSS)
+- Breaking core simplicity (>5K lines kernel)
+- Database-specific SQL in plugins
+- Direct plugin-to-plugin communication
+
+**P1 - Requires Immediate Fix:**
+- Missing tests for new features
+- Files >500 lines
+- Functions >50 lines
+- Performance regressions >10%
+- Missing documentation
+
+**P2 - Fix Before Merge:**
+- Inconsistent naming conventions
+- Missing error handling
+- Hard-coded configuration
+- Poor variable names
+- Missing type annotations
+
+## Governance
+
+### Amendment Process
+1. Propose change in GitHub issue
+2. Discuss with team (async, 7-day minimum)
+3. Vote (majority approval required)
+4. Update constitution with version bump
+5. Notify all developers
+6. Migration plan if needed
+
+### Review Requirements
+- All PRs MUST reference constitution compliance
+- Architecture decisions MUST be documented in ADR format
+- Breaking changes MUST bump version and provide migration guide
+- New principles MUST have rationale documented
+
+### AI Agent Instructions
+When working on BOSA:
+1. Read this constitution FIRST before ANY code changes
+2. Verify request against NO CREATIVITY rule
+3. Verify request against NO ASSUMPTIONS rule - ANSWER questions, don't implement solutions
+4. Check if change belongs in core or plugin
+5. Ensure multi-language/multi-database compatibility
+6. Write tests BEFORE implementation
+7. Keep files under 500 lines
+8. Document WHY, not WHAT
+9. ASK before adding anything beyond exact request
+10. When user asks a question → ANSWER first, WAIT for confirmation before implementing
+11. **CRITICAL: Version Bumping Rules (NEVER VIOLATE - ABSOLUTE PRIORITY):**
+ - **⚠️ NEVER EVER REVERSE VERSION NUMBERS BACKWARDS ⚠️**
+ - **⚠️ VERSION NUMBERS CAN ONLY INCREASE, NEVER DECREASE ⚠️**
+ - **⚠️ IF YOU DECREASE A VERSION NUMBER, YOU ARE VIOLATING THE CONSTITUTION ⚠️**
+
+ **Version Source of Truth Logic:**
+ - The source of truth for current version is the **`version.txt` file**, NOT git HEAD
+ - If `version.txt` shows build number 077 and git HEAD shows 068, this means git hasn't been updated yet
+ - This is NORMAL - git may be behind the actual current version
+
+ **Bumping Rules:**
+ - **ALWAYS check `version.txt` file FIRST** (not git HEAD)
+ - **ALWAYS bump ABOVE the higher number found in `version.txt`**
+ - Example: If `version.txt` shows 0.0.2.077 and git shows 0.0.2.068 → bump to **0.0.2.078** (NOT 0.0.2.069)
+ - Example: If `version.txt` shows 0.0.2.100 and git shows 0.0.2.050 → bump to **0.0.2.101** (NOT 0.0.2.051)
+
+ **What to NEVER do:**
+ - ❌ NEVER use git HEAD version to determine bump number
+ - ❌ NEVER decrease version numbers under ANY circumstances
+ - ❌ NEVER bump to a number lower than what's in `version.txt`
+ - ❌ NEVER assume git HEAD is current - it may be outdated
+
+ **The Rule: `version.txt` = Source of Truth → Always bump above the number in `version.txt`**
+12. **CRITICAL: ALL new files MUST be committed to git IMMEDIATELY after creation and testing. NO EXCEPTIONS. Untracked files violate project rules and can be lost.**
+
+## Version History
+
+**Version 1.0.0** | **Ratified**: 2025-11-19 | **Status**: Active
+
+### Key Decisions
+- Go for kernel (single binary simplicity)
+- Multi-language plugin support (ecosystem growth)
+- Real-time WebSocket built-in (not optional)
+- Multi-database from day one (no vendor lock-in)
+- Radical simplicity (WordPress-level ease)
+- NO CREATIVITY rule (prevent over-engineering)
+
+### Future Considerations
+- WASM plugin runtime (v2.0)
+- GraphQL API layer (v1.5)
+- Plugin marketplace (v1.2)
+- Visual plugin builder (v2.0)
+- Multi-region deployment (v3.0)
+
+---
+
+**This constitution is the law of BOSA development. All other documents, patterns, and practices are subordinate. When in doubt, ask: "Does this make BOSA simpler?" If no, don't do it.**
+
+**Remember**: The best code is no code. The second best is code so simple that AI can write and maintain it.
+
+---
+
+*"Complexity is the enemy. Simplicity is the ultimate sophistication." - Leonardo da Vinci*
+
+*"Make it work, make it right, make it fast - in that order. And make it simple throughout." - Kent Beck (adapted)*
diff --git a/.cursor/rules/change-discipline.mdc b/.cursor/rules/change-discipline.mdc
new file mode 100644
index 0000000..b70d0a3
--- /dev/null
+++ b/.cursor/rules/change-discipline.mdc
@@ -0,0 +1,11 @@
+---
+description: Force review before applying
+alwaysApply: true
+---
+
+## Workflow
+1. Understand the request fully.
+2. If the change touches >3 files or is architectural → output a clear numbered plan and wait for “proceed”.
+3. Generate code → run tests → show diff → ask “Apply this?” (never auto-apply large changes).
+4. After user says yes → apply and re-run tests.
+5. Never say “looks good” if you haven’t actually executed the code/tests.
\ No newline at end of file
diff --git a/.cursor/rules/no-hallucinations.mdc b/.cursor/rules/no-hallucinations.mdc
new file mode 100644
index 0000000..58da505
--- /dev/null
+++ b/.cursor/rules/no-hallucinations.mdc
@@ -0,0 +1,10 @@
+---
+description: Prevent inventing APIs or ignoring real code
+alwaysApply: true
+---
+
+- Base all code on the actual codebase, not assumptions.
+- If a function/class/pattern might exist, search the codebase first (@Codebase or grep).
+- Never use placeholder comments like “implement later”. Implement or ask.
+- For external libraries: only use versions and APIs that actually exist in package.json/requirements.txt/etc.
+- If the codebase has an established pattern (e.g., custom hooks, service layer), follow it exactly — never introduce a new one without asking.
\ No newline at end of file
diff --git a/.cursor/rules/testing-first.mdc b/.cursor/rules/testing-first.mdc
new file mode 100644
index 0000000..596ee50
--- /dev/null
+++ b/.cursor/rules/testing-first.mdc
@@ -0,0 +1,13 @@
+---
+description: Force test execution & writing
+globs: ["**/*.ts", "**/*.js", "**/*.py", "**/*.go", etc.]
+alwaysApply: true
+---
+
+## Testing is mandatory
+- Every non-trivial change must include or update tests.
+- After generating code, always run the full test suite (npm test / pytest / go test / etc.).
+- If tests are missing for the area you touch, write them first.
+- Enable YOLO mode only for allowed test commands (configure in Cursor settings → Features → YOLO).
+- If any test fails → fix it before presenting the final diff.
+- Use “Run tests and fix any failures” as your default loop.
\ No newline at end of file
diff --git a/.cursor/worktrees.json b/.cursor/worktrees.json
new file mode 100644
index 0000000..77e9744
--- /dev/null
+++ b/.cursor/worktrees.json
@@ -0,0 +1,5 @@
+{
+ "setup-worktree": [
+ "npm install"
+ ]
+}
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..6b77b79
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,51 @@
+# Dependencies
+node_modules/
+package-lock.json
+yarn.lock
+
+# Build outputs
+dist/
+build/
+*.tsbuildinfo
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Testing
+coverage/
+.nyc_output/
+
+# Temporary files
+tmp/
+temp/
+*.tmp
+
+# Database
+*.db
+*.sqlite
+*.sqlite3
+
+# Deployment
+*.zip
+!builds/**/*.zip
+
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..04f5cf4
--- /dev/null
+++ b/README.md
@@ -0,0 +1,43 @@
+# BP_WB - BOSA Plugin Website Builder
+
+Visual drag-and-drop page builder for BOSA apps, allowing users to create rich UI/UX interfaces without coding.
+
+## Overview
+
+**App Name:** bp_wb (BOSA Plugin Website Builder)
+**Version:** 0.1.0 (Initial Development)
+**Runtime:** Node.js with React/TypeScript
+**Target:** Elementor/Beaver Builder level functionality
+**Purpose:** Visual drag-and-drop page builder for BOSA apps, allowing users to create rich UI/UX interfaces without coding
+
+## Documentation
+
+- **[Developer Guide](docs/DEVELOPER_GUIDE.md)** - Complete development guide
+- **[Development Roadmap](docs/BP_WB_DEVELOPMENT_ROADMAP.md)** - Project roadmap and phases
+- **[Features List](docs/BP_WB_FEATURES_LIST.md)** - Complete feature list
+- **[Linear Issues](docs/BP_WB_LINEAR_ISSUES.md)** - All development issues formatted for Linear
+
+## Technology Stack
+
+- **Frontend:** React + TypeScript
+- **Backend:** Node.js + Express/Fastify
+- **Build Tools:** Vite/Webpack
+- **Drag & Drop:** React DnD / React Flow
+- **Styling:** Tailwind CSS
+- **State Management:** Zustand/Redux
+
+## Project Status
+
+**Current Phase:** Planning
+**Status:** Initial setup and issue tracking
+**Total Features:** 71 features across 8 phases
+**Estimated Timeline:** 32 weeks (8 months)
+
+## Getting Started
+
+This project is currently in the planning phase. Documentation and issues are being prepared for development.
+
+## License
+
+[To be determined]
+
diff --git a/docs/BP_WB_DEVELOPMENT_ROADMAP.md b/docs/BP_WB_DEVELOPMENT_ROADMAP.md
new file mode 100644
index 0000000..cb2fdf3
--- /dev/null
+++ b/docs/BP_WB_DEVELOPMENT_ROADMAP.md
@@ -0,0 +1,387 @@
+# BP_WB (BOSA Plugin Website Builder) - Development Roadmap
+
+## Overview
+
+**App Name:** bp_wb (BOSA Plugin Website Builder)
+**Version:** 0.1.0 (Initial Development)
+**Runtime:** Node.js with React/TypeScript
+**Target:** Elementor/Beaver Builder level functionality
+**Purpose:** Visual drag-and-drop page builder for BOSA apps, allowing users to create rich UI/UX interfaces without coding
+
+## Technology Stack Recommendation
+
+### Primary Stack: **Node.js + React + TypeScript**
+
+**Rationale:**
+- **React**: Industry standard for visual editors (Elementor, Webflow, etc. use React)
+- **TypeScript**: Type safety for complex editor logic
+- **Node.js**: Full-stack capability, can share code between editor and renderer
+- **Express/Fastify**: Backend API for page config storage
+- **React DnD / React Flow**: Drag-and-drop functionality
+- **Tailwind CSS**: Utility-first styling for editor UI
+- **Zustand/Redux**: State management for editor state
+
+**Alternative Considerations:**
+- **Go + React**: Could use Go for backend, React for frontend (more complex)
+- **Vue.js**: Alternative to React (less ecosystem for visual editors)
+- **PHP**: WordPress ecosystem (but less modern, harder to build visual editors)
+
+**Recommendation: Node.js + React + TypeScript** - Best fit for visual editor development
+
+## Architecture Overview
+
+```
+bp_wb/
+├── manifest.yaml
+├── package.json
+├── tsconfig.json
+├── frontend/
+│ ├── editor/ # Visual editor UI
+│ │ ├── components/
+│ │ │ ├── Canvas.tsx # Main editing canvas
+│ │ │ ├── Toolbar.tsx # Top toolbar (save, preview, etc.)
+│ │ │ ├── Sidebar.tsx # Component palette sidebar
+│ │ │ ├── Properties.tsx # Property panel
+│ │ │ ├── Layers.tsx # Layer tree view
+│ │ │ └── Responsive.tsx # Responsive breakpoint switcher
+│ │ ├── hooks/
+│ │ │ ├── useEditor.ts
+│ │ │ ├── useDragDrop.ts
+│ │ │ └── useUndoRedo.ts
+│ │ └── store/
+│ │ └── editorStore.ts # Zustand/Redux store
+│ ├── renderer/ # Page renderer (public-facing)
+│ │ ├── ComponentRenderer.tsx
+│ │ ├── LayoutEngine.tsx
+│ │ └── StyleInjector.tsx
+│ └── components/ # Reusable UI components
+│ ├── base/ # Base components (Button, Card, etc.)
+│ ├── layout/ # Layout components (Container, Grid, etc.)
+│ └── custom/ # Custom component registry
+├── backend/
+│ ├── api/
+│ │ ├── pages.ts # Page CRUD endpoints
+│ │ ├── templates.ts # Template management
+│ │ ├── components.ts # Component registry API
+│ │ ├── assets.ts # Asset upload/management
+│ │ └── export.ts # Export to theme
+│ ├── storage/
+│ │ ├── pageConfig.ts # Page config storage
+│ │ └── versionControl.ts # Version history
+│ └── renderer/
+│ └── serverRenderer.ts # Server-side rendering
+├── migrations/
+│ └── 001_initial_schema.sql
+└── docs/
+ └── DEVELOPER_GUIDE.md
+```
+
+## Database Schema
+
+### Core Tables
+
+```sql
+-- Page configurations
+CREATE TABLE wb_pages (
+ id SERIAL PRIMARY KEY,
+ app_name VARCHAR(255) NOT NULL,
+ route_path VARCHAR(500) NOT NULL,
+ page_config JSONB NOT NULL,
+ version INTEGER DEFAULT 1,
+ created_at TIMESTAMP DEFAULT NOW(),
+ updated_at TIMESTAMP DEFAULT NOW(),
+ created_by INTEGER,
+ UNIQUE(app_name, route_path)
+);
+
+-- Page versions (for history/rollback)
+CREATE TABLE wb_page_versions (
+ id SERIAL PRIMARY KEY,
+ page_id INTEGER REFERENCES wb_pages(id),
+ version INTEGER NOT NULL,
+ page_config JSONB NOT NULL,
+ created_at TIMESTAMP DEFAULT NOW(),
+ created_by INTEGER
+);
+
+-- Templates (starting points)
+CREATE TABLE wb_templates (
+ id SERIAL PRIMARY KEY,
+ name VARCHAR(255) NOT NULL,
+ description TEXT,
+ category VARCHAR(100),
+ template_config JSONB NOT NULL,
+ preview_image VARCHAR(500),
+ created_at TIMESTAMP DEFAULT NOW(),
+ created_by INTEGER
+);
+
+-- Component registry (custom components from plugins)
+CREATE TABLE wb_components (
+ id SERIAL PRIMARY KEY,
+ plugin_name VARCHAR(255) NOT NULL,
+ component_name VARCHAR(255) NOT NULL,
+ component_config JSONB NOT NULL,
+ created_at TIMESTAMP DEFAULT NOW(),
+ UNIQUE(plugin_name, component_name)
+);
+
+-- Asset library
+CREATE TABLE wb_assets (
+ id SERIAL PRIMARY KEY,
+ filename VARCHAR(255) NOT NULL,
+ file_path VARCHAR(500) NOT NULL,
+ file_type VARCHAR(50),
+ file_size INTEGER,
+ uploaded_by INTEGER,
+ created_at TIMESTAMP DEFAULT NOW()
+);
+```
+
+## Development Phases
+
+### Phase 1: Foundation (Weeks 1-4)
+**Goal:** Basic editor with core functionality
+
+**Features:**
+- [ ] Project setup (Node.js, React, TypeScript)
+- [ ] Basic editor UI (canvas, toolbar, sidebar)
+- [ ] Drag-and-drop system
+- [ ] Component palette (10 base components)
+- [ ] Property panel (basic properties)
+- [ ] Page config storage (database)
+- [ ] Basic renderer (render page from config)
+- [ ] Save/load functionality
+
+**Deliverables:**
+- Working editor UI
+- Can create simple pages
+- Can save and view pages
+
+---
+
+### Phase 2: Core Editing (Weeks 5-8)
+**Goal:** Full editing capabilities
+
+**Features:**
+- [ ] Undo/Redo system
+- [ ] Copy/Paste components
+- [ ] Delete components
+- [ ] Layer tree view
+- [ ] Component selection/highlighting
+- [ ] Property editor (colors, fonts, spacing, etc.)
+- [ ] Responsive breakpoints (desktop, tablet, mobile)
+- [ ] Grid system (12-column, flexbox)
+- [ ] Container components
+- [ ] Section components
+
+**Deliverables:**
+- Full editing workflow
+- Responsive design support
+- Professional property editing
+
+---
+
+### Phase 3: Advanced Components (Weeks 9-12)
+**Goal:** Rich component library
+
+**Features:**
+- [ ] Text components (Heading, Paragraph, Rich Text)
+- [ ] Media components (Image, Video, Gallery)
+- [ ] Form components (Input, Textarea, Select, Button)
+- [ ] Layout components (Row, Column, Container, Section)
+- [ ] Navigation components (Menu, Breadcrumb)
+- [ ] Content components (Card, Accordion, Tabs)
+- [ ] Interactive components (Modal, Dropdown, Tooltip)
+- [ ] Component nesting (components within components)
+- [ ] Component templates (pre-built component groups)
+
+**Deliverables:**
+- Comprehensive component library
+- Can build complex layouts
+- Professional UI components
+
+---
+
+### Phase 4: Styling & Design (Weeks 13-16)
+**Goal:** Advanced styling capabilities
+
+**Features:**
+- [ ] Color picker (with palette)
+- [ ] Typography editor (font family, size, weight, line height)
+- [ ] Spacing controls (margin, padding)
+- [ ] Border editor (width, style, color, radius)
+- [ ] Shadow editor (box shadow, text shadow)
+- [ ] Background editor (color, image, gradient)
+- [ ] Animation editor (transitions, transforms)
+- [ ] Custom CSS editor (advanced users)
+- [ ] Style presets (save/load style sets)
+- [ ] Global styles (theme-level styling)
+
+**Deliverables:**
+- Professional styling tools
+- Can create beautiful designs
+- Advanced customization options
+
+---
+
+### Phase 5: Templates & Themes (Weeks 17-20)
+**Goal:** Template system and theme integration
+
+**Features:**
+- [ ] Template library (pre-built page templates)
+- [ ] Template categories (landing, blog, shop, etc.)
+- [ ] Import/export templates
+- [ ] Theme integration (use BOSA themes as base)
+- [ ] Export page to theme (convert page config to theme)
+- [ ] Template marketplace (share templates)
+- [ ] Clone page functionality
+- [ ] Page templates (header, footer, sidebar templates)
+
+**Deliverables:**
+- Template system
+- Theme integration
+- Can export to themes
+
+---
+
+### Phase 6: Advanced Features (Weeks 21-24)
+**Goal:** Professional features
+
+**Features:**
+- [ ] Version history (view/restore previous versions)
+- [ ] Collaboration (multiple users editing)
+- [ ] Comments/annotations
+- [ ] Asset library (image/video management)
+- [ ] Media upload/management
+- [ ] SEO editor (meta tags, Open Graph)
+- [ ] Custom code injection (head, body)
+- [ ] Conditional visibility (show/hide based on conditions)
+- [ ] Dynamic content (connect to app data)
+- [ ] Form builder (create forms with validation)
+
+**Deliverables:**
+- Professional features
+- Production-ready tool
+- Advanced capabilities
+
+---
+
+### Phase 7: Plugin Integration (Weeks 25-28)
+**Goal:** Integration with BOSA ecosystem
+
+**Features:**
+- [ ] Plugin component registry (plugins can register components)
+- [ ] Plugin widget system (plugins provide widgets)
+- [ ] App-specific components (components from other apps)
+- [ ] Event system (components can trigger/listen to events)
+- [ ] Data binding (connect components to app data)
+- [ ] API integration (fetch data from app APIs)
+- [ ] Authentication integration (show/hide based on auth)
+- [ ] Multi-language support (i18n components)
+
+**Deliverables:**
+- Full BOSA integration
+- Extensible component system
+- Plugin ecosystem support
+
+---
+
+### Phase 8: Performance & Polish (Weeks 29-32)
+**Goal:** Optimization and refinement
+
+**Features:**
+- [ ] Performance optimization (lazy loading, code splitting)
+- [ ] Renderer optimization (fast page rendering)
+- [ ] Editor performance (smooth editing experience)
+- [ ] Mobile editor (responsive editor UI)
+- [ ] Keyboard shortcuts
+- [ ] Accessibility (WCAG compliance)
+- [ ] Documentation (user guide, API docs)
+- [ ] Testing (unit, integration, E2E)
+- [ ] Bug fixes and refinements
+
+**Deliverables:**
+- Production-ready app
+- Optimized performance
+- Complete documentation
+
+---
+
+## Feature Comparison with Elementor/Beaver Builder
+
+### Elementor Features (Reference)
+- ✅ Drag-and-drop editor
+- ✅ 100+ widgets
+- ✅ Responsive editing
+- ✅ Theme builder
+- ✅ Template library
+- ✅ Form builder
+- ✅ Popup builder
+- ✅ WooCommerce integration
+- ✅ Dynamic content
+- ✅ Custom CSS
+- ✅ Animation builder
+- ✅ Global widgets
+- ✅ Version history
+
+### BP_WB Target Features
+- ✅ Drag-and-drop editor (Phase 1)
+- ✅ Component library (Phase 3)
+- ✅ Responsive editing (Phase 2)
+- ✅ Theme integration (Phase 5)
+- ✅ Template library (Phase 5)
+- ✅ Form builder (Phase 6)
+- ✅ Modal builder (Phase 3)
+- ✅ BOSA app integration (Phase 7)
+- ✅ Dynamic content (Phase 6)
+- ✅ Custom CSS (Phase 4)
+- ✅ Animation editor (Phase 4)
+- ✅ Global components (Phase 3)
+- ✅ Version history (Phase 6)
+
+## Success Metrics
+
+### Phase 1 Success:
+- Can create a simple page with 5+ components
+- Can save and view the page
+- Editor is responsive and usable
+
+### Phase 4 Success:
+- Can create a professional landing page
+- Styling tools are intuitive
+- Pages render correctly
+
+### Phase 8 Success:
+- Can build any page type (landing, blog, shop, dashboard)
+- Performance is excellent (< 2s page load)
+- User satisfaction > 80%
+
+## Risk Mitigation
+
+### Technical Risks:
+1. **Complexity**: Visual editors are complex
+ - *Mitigation*: Start simple, iterate, use proven libraries
+2. **Performance**: Large page configs can be slow
+ - *Mitigation*: Optimize rendering, lazy loading, code splitting
+3. **Browser Compatibility**: Different browser behaviors
+ - *Mitigation*: Use modern frameworks, test across browsers
+
+### Scope Risks:
+1. **Feature Creep**: Too many features
+ - *Mitigation*: Strict phase boundaries, MVP first
+2. **Timeline**: May take longer than expected
+ - *Mitigation*: Realistic estimates, buffer time, prioritize
+
+## Next Steps
+
+1. **Create Linear Issues**: Convert this roadmap to Linear issues
+2. **Set up Development Environment**: Node.js, React, TypeScript setup
+3. **Create App Structure**: Initialize bp_wb app structure
+4. **Start Phase 1**: Begin foundation development
+
+---
+
+**Document Version:** 1.0
+**Last Updated:** December 21, 2025
+**Status:** Planning Phase
diff --git a/docs/BP_WB_FEATURES_LIST.md b/docs/BP_WB_FEATURES_LIST.md
new file mode 100644
index 0000000..e880123
--- /dev/null
+++ b/docs/BP_WB_FEATURES_LIST.md
@@ -0,0 +1,659 @@
+# BP_WB (BOSA Plugin Website Builder) - Complete Features List
+
+This document contains the complete feature list organized by development phases. Use this to create Linear issues for the bp_wb app development.
+
+## Phase 1: Foundation (Weeks 1-4)
+
+### WB-001: Project Setup and Infrastructure
+- Initialize Node.js project with TypeScript
+- Set up React development environment
+- Configure build tools (Vite/Webpack)
+- Set up ESLint, Prettier
+- Create project structure
+- Set up testing framework (Jest, React Testing Library)
+- Configure CI/CD pipeline
+
+### WB-002: Basic Editor UI Layout
+- Create main editor container
+- Implement top toolbar (save, preview, exit)
+- Create left sidebar (component palette)
+- Create right sidebar (property panel)
+- Create center canvas area
+- Implement responsive editor layout
+- Add loading states
+
+### WB-003: Drag-and-Drop System
+- Implement drag-and-drop library (React DnD)
+- Create draggable component items
+- Create drop zones on canvas
+- Handle drag start/end events
+- Visual feedback during drag
+- Prevent invalid drops
+
+### WB-004: Component Palette (Base Components)
+- Create component palette UI
+- Implement 10 base components:
+ - Button
+ - Heading
+ - Paragraph
+ - Image
+ - Container
+ - Section
+ - Row
+ - Column
+ - Divider
+ - Spacer
+- Component icons and labels
+- Search/filter components
+
+### WB-005: Property Panel (Basic)
+- Create property panel UI
+- Implement basic property editors:
+ - Text input
+ - Number input
+ - Color picker (basic)
+ - Select dropdown
+- Property grouping
+- Show/hide properties based on component
+
+### WB-006: Page Config Storage
+- Design page config JSON schema
+- Create database table (wb_pages)
+- Implement save page API endpoint
+- Implement load page API endpoint
+- Implement update page API endpoint
+- Implement delete page API endpoint
+- Error handling and validation
+
+### WB-007: Basic Renderer
+- Create renderer component
+- Parse page config JSON
+- Render components from config
+- Apply basic styles
+- Handle component nesting
+- Error boundaries
+
+### WB-008: Save/Load Functionality
+- Implement save button in toolbar
+- Auto-save functionality (debounced)
+- Load page on editor open
+- Unsaved changes warning
+- Save success/error notifications
+- Loading states
+
+---
+
+## Phase 2: Core Editing (Weeks 5-8)
+
+### WB-009: Undo/Redo System
+- Implement command pattern for actions
+- Create undo/redo stack
+- Keyboard shortcuts (Ctrl+Z, Ctrl+Y)
+- Undo/redo buttons in toolbar
+- Visual feedback
+- Limit stack size (performance)
+
+### WB-010: Copy/Paste Components
+- Implement copy component functionality
+- Implement paste component functionality
+- Keyboard shortcuts (Ctrl+C, Ctrl+V)
+- Copy multiple components
+- Paste with position offset
+- Clipboard management
+
+### WB-011: Delete Components
+- Implement delete component functionality
+- Delete button in property panel
+- Keyboard shortcut (Delete key)
+- Delete confirmation dialog
+- Delete nested components
+- Undo delete support
+
+### WB-012: Layer Tree View
+- Create layer tree sidebar
+- Display component hierarchy
+- Expand/collapse layers
+- Select component from layer tree
+- Drag to reorder layers
+- Visual indicators (selected, hidden)
+
+### WB-013: Component Selection
+- Click to select component
+- Visual selection indicator (outline)
+- Multi-select (Ctrl+Click, Shift+Click)
+- Selection handles (resize, move)
+- Deselect (click outside)
+- Selection in layer tree
+
+### WB-014: Property Editor (Advanced)
+- Typography editor (font family, size, weight, line height)
+- Spacing editor (margin, padding)
+- Border editor (width, style, color, radius)
+- Background editor (color, image, gradient)
+- Shadow editor (box shadow, text shadow)
+- Layout editor (display, flex, grid)
+- Position editor (relative, absolute, fixed)
+
+### WB-015: Responsive Breakpoints
+- Desktop breakpoint (default, 1920px+)
+- Tablet breakpoint (768px - 1919px)
+- Mobile breakpoint (320px - 767px)
+- Breakpoint switcher in toolbar
+- Per-breakpoint property editing
+- Responsive preview mode
+
+### WB-016: Grid System
+- 12-column grid system
+- Grid container component
+- Grid column component
+- Flexbox layout support
+- CSS Grid support
+- Responsive grid (different columns per breakpoint)
+
+### WB-017: Container Components
+- Container component (max-width, centered)
+- Section component (full-width sections)
+- Row component (horizontal layout)
+- Column component (vertical layout)
+- Nested containers
+- Container spacing options
+
+### WB-018: Section Components
+- Section component (page sections)
+- Section background options
+- Section padding/margin
+- Section height options (auto, full, custom)
+- Section overflow handling
+- Section z-index management
+
+---
+
+## Phase 3: Advanced Components (Weeks 9-12)
+
+### WB-019: Text Components
+- Heading component (H1-H6)
+- Paragraph component
+- Rich text editor component
+- Text formatting (bold, italic, underline)
+- Text alignment (left, center, right, justify)
+- Text color and styling
+- Link component
+
+### WB-020: Media Components
+- Image component
+- Image upload functionality
+- Image optimization
+- Image gallery component
+- Video component (YouTube, Vimeo, self-hosted)
+- Video player controls
+- Audio component
+- Media library integration
+
+### WB-021: Form Components
+- Input component (text, email, password, number)
+- Textarea component
+- Select dropdown component
+- Checkbox component
+- Radio button component
+- File upload component
+- Form container component
+- Form validation (basic)
+
+### WB-022: Layout Components
+- Advanced Row component (flexbox options)
+- Advanced Column component (flexbox options)
+- Stack component (vertical/horizontal stacking)
+- Grid component (CSS Grid)
+- Spacer component (flexible spacing)
+- Divider component (horizontal/vertical lines)
+
+### WB-023: Navigation Components
+- Menu component (horizontal/vertical)
+- Menu item component
+- Breadcrumb component
+- Pagination component
+- Tab navigation component
+- Accordion component
+- Sidebar navigation component
+
+### WB-024: Content Components
+- Card component
+- Card header, body, footer
+- Accordion component
+- Tabs component
+- Modal component
+- Tooltip component
+- Popover component
+- Alert component
+
+### WB-025: Interactive Components
+- Modal/Dialog component
+- Dropdown component
+- Tooltip component
+- Popover component
+- Carousel/Slider component
+- Tabs component
+- Accordion component
+- Collapse component
+
+### WB-026: Component Nesting
+- Support nested components
+- Nesting depth limits
+- Visual nesting indicators
+- Drag components into other components
+- Nested component selection
+- Nested component properties
+
+### WB-027: Component Templates
+- Pre-built component groups
+- Save component group as template
+- Load component template
+- Template library
+- Template categories
+- Template search
+
+---
+
+## Phase 4: Styling & Design (Weeks 13-16)
+
+### WB-028: Color Picker (Advanced)
+- Full color picker (HSV, RGB, HEX)
+- Color palette (saved colors)
+- Color history
+- Gradient editor
+- Color opacity/alpha
+- Color presets
+- Global color variables
+
+### WB-029: Typography Editor
+- Font family selector (Google Fonts integration)
+- Font size editor (px, em, rem)
+- Font weight selector
+- Line height editor
+- Letter spacing editor
+- Text transform (uppercase, lowercase, capitalize)
+- Text decoration (underline, strikethrough)
+
+### WB-030: Spacing Controls
+- Margin editor (top, right, bottom, left)
+- Padding editor (top, right, bottom, left)
+- Spacing presets
+- Responsive spacing (different per breakpoint)
+- Spacing units (px, em, rem, %)
+- Visual spacing indicators
+
+### WB-031: Border Editor
+- Border width editor
+- Border style selector (solid, dashed, dotted)
+- Border color picker
+- Border radius editor (individual corners)
+- Border presets
+- Responsive borders
+
+### WB-032: Shadow Editor
+- Box shadow editor (x, y, blur, spread, color)
+- Text shadow editor
+- Shadow presets
+- Multiple shadows support
+- Shadow preview
+- Responsive shadows
+
+### WB-033: Background Editor
+- Solid color background
+- Image background (upload, URL)
+- Image position (center, cover, contain)
+- Image repeat (no-repeat, repeat, repeat-x, repeat-y)
+- Gradient background (linear, radial)
+- Gradient editor (colors, stops, angle)
+- Video background
+
+### WB-034: Animation Editor
+- Transition editor (property, duration, easing)
+- Transform editor (translate, rotate, scale, skew)
+- Animation presets (fade, slide, bounce)
+- Hover animations
+- Scroll animations (basic)
+- Animation preview
+
+### WB-035: Custom CSS Editor
+- Code editor for custom CSS
+- Syntax highlighting
+- CSS validation
+- Scoped CSS (component-level)
+- Global CSS (page-level)
+- CSS minification
+- CSS autocomplete
+
+### WB-036: Style Presets
+- Save style set (colors, fonts, spacing)
+- Load style preset
+- Style preset library
+- Apply preset to component
+- Apply preset to page
+- Export/import presets
+
+### WB-037: Global Styles
+- Global color variables
+- Global typography settings
+- Global spacing scale
+- Global border radius
+- Global shadows
+- Theme-level styling
+- Style inheritance
+
+---
+
+## Phase 5: Templates & Themes (Weeks 17-20)
+
+### WB-038: Template Library
+- Template library UI
+- Template categories (landing, blog, shop, dashboard)
+- Template search and filter
+- Template preview
+- Template installation
+- Template management (create, edit, delete)
+
+### WB-039: Template System
+- Create template from page
+- Save template to library
+- Load template to page
+- Template metadata (name, description, category)
+- Template preview images
+- Template versioning
+
+### WB-040: Theme Integration
+- Load BOSA theme as base
+- Apply theme styles to editor
+- Theme component library
+- Theme color palette
+- Theme typography
+- Theme asset integration
+
+### WB-041: Export to Theme
+- Convert page config to theme structure
+- Generate theme.yaml
+- Export CSS files
+- Export JS files
+- Export assets
+- Create installable theme ZIP
+- Theme validation
+
+### WB-042: Template Marketplace
+- Template sharing system
+- Template upload/download
+- Template ratings/reviews
+- Template categories
+- Template search
+- Template versioning
+
+### WB-043: Clone Page
+- Duplicate page functionality
+- Clone with new name
+- Clone with new route
+- Clone templates
+- Bulk clone operations
+
+### WB-044: Page Templates
+- Header template
+- Footer template
+- Sidebar template
+- Page layout templates
+- Template inheritance
+- Template overrides
+
+---
+
+## Phase 6: Advanced Features (Weeks 21-24)
+
+### WB-045: Version History
+- Save page versions
+- Version list view
+- Version preview
+- Restore version
+- Version comparison
+- Version metadata (date, author, changes)
+- Version limit (keep last N versions)
+
+### WB-046: Collaboration
+- Multi-user editing support
+- Real-time collaboration (WebSocket)
+- User cursors/selection
+- Conflict resolution
+- User permissions (edit, view)
+- Collaboration indicators
+
+### WB-047: Comments/Annotations
+- Add comments to components
+- Comment thread
+- Resolve comments
+- Comment notifications
+- Comment history
+- Comment permissions
+
+### WB-048: Asset Library
+- Asset library UI
+- Image upload
+- Video upload
+- File management
+- Asset organization (folders, tags)
+- Asset search
+- Asset optimization
+- Asset CDN integration
+
+### WB-049: Media Upload/Management
+- Drag-and-drop upload
+- Multiple file upload
+- Upload progress
+- Image cropping/editing
+- Image optimization
+- File type validation
+- File size limits
+- Storage management
+
+### WB-050: SEO Editor
+- Meta title editor
+- Meta description editor
+- Open Graph tags
+- Twitter Card tags
+- Canonical URL
+- Robots meta
+- Schema.org markup
+- SEO preview
+
+### WB-051: Custom Code Injection
+- Head code injection (page-level)
+- Body code injection (page-level)
+- Component-level code injection
+- Script injection
+- Style injection
+- Code validation
+- Security checks
+
+### WB-052: Conditional Visibility
+- Show/hide based on conditions
+- User role conditions
+- Authentication conditions
+- Custom conditions (API-based)
+- Conditional logic builder
+- Preview conditional states
+
+### WB-053: Dynamic Content
+- Connect to app data (API)
+- Data binding
+- Dynamic lists
+- Dynamic forms
+- Data filtering
+- Data pagination
+- Real-time data updates
+
+### WB-054: Form Builder
+- Form component builder
+- Form field types
+- Form validation rules
+- Form submission handling
+- Form email notifications
+- Form data storage
+- Form analytics
+
+---
+
+## Phase 7: Plugin Integration (Weeks 25-28)
+
+### WB-055: Plugin Component Registry
+- Component registration API
+- Plugin component discovery
+- Component metadata
+- Component icons
+- Component categories
+- Component versioning
+
+### WB-056: Plugin Widget System
+- Widget registration
+- Widget configuration
+- Widget data binding
+- Widget events
+- Widget styling
+- Widget documentation
+
+### WB-057: App-Specific Components
+- Components from other BOSA apps
+- App component discovery
+- App component integration
+- App component styling
+- App component data
+- App component events
+
+### WB-058: Event System
+- Component events (click, hover, etc.)
+- Custom events
+- Event handlers
+- Event propagation
+- Event logging
+- Event debugging
+
+### WB-059: Data Binding
+- Connect components to app data
+- Data source configuration
+- Data transformation
+- Data caching
+- Data refresh
+- Data error handling
+
+### WB-060: API Integration
+- Fetch data from app APIs
+- API authentication
+- API request builder
+- API response handling
+- API error handling
+- API caching
+
+### WB-061: Authentication Integration
+- Show/hide based on authentication
+- User role conditions
+- Permission-based visibility
+- Login/logout components
+- User profile components
+- Protected content
+
+### WB-062: Multi-Language Support
+- i18n component support
+- Language switcher component
+- Per-language content
+- Language-specific styling
+- Translation management
+- RTL support
+
+---
+
+## Phase 8: Performance & Polish (Weeks 29-32)
+
+### WB-063: Performance Optimization
+- Code splitting
+- Lazy loading components
+- Image lazy loading
+- Asset optimization
+- Bundle size optimization
+- Render optimization
+- Memory management
+
+### WB-064: Renderer Optimization
+- Fast page rendering
+- Server-side rendering (SSR)
+- Static page generation
+- Caching strategies
+- CDN integration
+- Minification
+- Compression
+
+### WB-065: Editor Performance
+- Smooth editing experience
+- Optimized re-renders
+- Virtual scrolling (large pages)
+- Debounced updates
+- Efficient state management
+- Performance monitoring
+
+### WB-066: Mobile Editor
+- Responsive editor UI
+- Touch-friendly controls
+- Mobile canvas view
+- Mobile property panel
+- Mobile component palette
+- Mobile gestures
+
+### WB-067: Keyboard Shortcuts
+- Comprehensive keyboard shortcuts
+- Shortcut customization
+- Shortcut help dialog
+- Mac/Windows key differences
+- Accessibility shortcuts
+
+### WB-068: Accessibility
+- WCAG 2.1 AA compliance
+- Keyboard navigation
+- Screen reader support
+- ARIA labels
+- Focus management
+- Color contrast
+- Alt text for images
+
+### WB-069: Documentation
+- User guide
+- Video tutorials
+- API documentation
+- Component documentation
+- Template documentation
+- FAQ
+- Troubleshooting guide
+
+### WB-070: Testing
+- Unit tests
+- Integration tests
+- E2E tests (Playwright/Cypress)
+- Visual regression tests
+- Performance tests
+- Accessibility tests
+- Browser compatibility tests
+
+### WB-071: Bug Fixes and Refinements
+- Bug triage and fixing
+- UI/UX refinements
+- Performance improvements
+- Security fixes
+- Code cleanup
+- Documentation updates
+
+---
+
+## Summary
+
+**Total Features:** 71 features across 8 phases
+**Estimated Timeline:** 32 weeks (8 months)
+**Team Size:** 2-3 developers recommended
+**Priority:** High (core BOSA functionality)
+
+---
+
+**Document Version:** 1.0
+**Last Updated:** December 21, 2025
+**Status:** Ready for Linear Issue Creation
diff --git a/docs/BP_WB_LINEAR_ISSUES.md b/docs/BP_WB_LINEAR_ISSUES.md
new file mode 100644
index 0000000..3e9a053
--- /dev/null
+++ b/docs/BP_WB_LINEAR_ISSUES.md
@@ -0,0 +1,1659 @@
+# BP_WB (BOSA Plugin Website Builder) - Linear Issues
+
+This document contains all 71 issues formatted for Linear import. Each issue includes:
+- Issue ID (WB-001 through WB-071)
+- Title
+- Phase assignment
+- Description
+- Acceptance criteria (tasks)
+- Priority/Phase information
+
+**Total Issues:** 71
+**Phases:** 8
+**Estimated Timeline:** 32 weeks (8 months)
+
+---
+
+## Phase 1: Foundation (Weeks 1-4)
+
+### WB-001: Project Setup and Infrastructure
+
+**Phase:** Phase 1 - Foundation
+**Priority:** P0 - Critical
+**Labels:** setup, infrastructure, foundation
+
+**Description:**
+Initialize the Node.js project with TypeScript and set up the complete development environment including build tools, linting, testing framework, and project structure.
+
+**Acceptance Criteria:**
+- [ ] Initialize Node.js project with TypeScript
+- [ ] Set up React development environment
+- [ ] Configure build tools (Vite/Webpack)
+- [ ] Set up ESLint, Prettier
+- [ ] Create project structure (frontend/editor, frontend/renderer, backend, migrations)
+- [ ] Set up testing framework (Jest, React Testing Library)
+- [ ] Configure CI/CD pipeline
+
+**Estimated Effort:** 1 week
+
+---
+
+### WB-002: Basic Editor UI Layout
+
+**Phase:** Phase 1 - Foundation
+**Priority:** P0 - Critical
+**Labels:** ui, editor, foundation
+
+**Description:**
+Create the basic editor UI layout with toolbar, sidebars, and canvas area. This is the foundation of the visual editor interface.
+
+**Acceptance Criteria:**
+- [ ] Create main editor container
+- [ ] Implement top toolbar (save, preview, exit)
+- [ ] Create left sidebar (component palette)
+- [ ] Create right sidebar (property panel)
+- [ ] Create center canvas area
+- [ ] Implement responsive editor layout
+- [ ] Add loading states
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-001
+
+---
+
+### WB-003: Drag-and-Drop System
+
+**Phase:** Phase 1 - Foundation
+**Priority:** P0 - Critical
+**Labels:** drag-drop, core-feature, editor
+
+**Description:**
+Implement the drag-and-drop system that allows users to drag components from the palette onto the canvas. This is a core feature of the visual editor.
+
+**Acceptance Criteria:**
+- [ ] Implement drag-and-drop library (React DnD)
+- [ ] Create draggable component items
+- [ ] Create drop zones on canvas
+- [ ] Handle drag start/end events
+- [ ] Visual feedback during drag
+- [ ] Prevent invalid drops
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-002
+
+---
+
+### WB-004: Component Palette (Base Components)
+
+**Phase:** Phase 1 - Foundation
+**Priority:** P0 - Critical
+**Labels:** components, palette, foundation
+
+**Description:**
+Create the component palette UI and implement the 10 base components that users can drag onto the canvas.
+
+**Acceptance Criteria:**
+- [ ] Create component palette UI
+- [ ] Implement 10 base components:
+ - Button
+ - Heading
+ - Paragraph
+ - Image
+ - Container
+ - Section
+ - Row
+ - Column
+ - Divider
+ - Spacer
+- [ ] Component icons and labels
+- [ ] Search/filter components
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-002, WB-003
+
+---
+
+### WB-005: Property Panel (Basic)
+
+**Phase:** Phase 1 - Foundation
+**Priority:** P0 - Critical
+**Labels:** properties, editor, ui
+
+**Description:**
+Create the property panel that displays and allows editing of component properties when a component is selected.
+
+**Acceptance Criteria:**
+- [ ] Create property panel UI
+- [ ] Implement basic property editors:
+ - Text input
+ - Number input
+ - Color picker (basic)
+ - Select dropdown
+- [ ] Property grouping
+- [ ] Show/hide properties based on component
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-002, WB-004
+
+---
+
+### WB-006: Page Config Storage
+
+**Phase:** Phase 1 - Foundation
+**Priority:** P0 - Critical
+**Labels:** backend, database, storage
+
+**Description:**
+Design and implement the page configuration storage system with database schema and API endpoints for CRUD operations.
+
+**Acceptance Criteria:**
+- [ ] Design page config JSON schema
+- [ ] Create database table (wb_pages)
+- [ ] Implement save page API endpoint
+- [ ] Implement load page API endpoint
+- [ ] Implement update page API endpoint
+- [ ] Implement delete page API endpoint
+- [ ] Error handling and validation
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-001
+
+---
+
+### WB-007: Basic Renderer
+
+**Phase:** Phase 1 - Foundation
+**Priority:** P0 - Critical
+**Labels:** renderer, core-feature
+
+**Description:**
+Create the basic renderer that can parse page config JSON and render components with basic styling.
+
+**Acceptance Criteria:**
+- [ ] Create renderer component
+- [ ] Parse page config JSON
+- [ ] Render components from config
+- [ ] Apply basic styles
+- [ ] Handle component nesting
+- [ ] Error boundaries
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-004, WB-006
+
+---
+
+### WB-008: Save/Load Functionality
+
+**Phase:** Phase 1 - Foundation
+**Priority:** P0 - Critical
+**Labels:** save-load, editor, core-feature
+
+**Description:**
+Implement save and load functionality in the editor with auto-save, unsaved changes warnings, and proper loading states.
+
+**Acceptance Criteria:**
+- [ ] Implement save button in toolbar
+- [ ] Auto-save functionality (debounced)
+- [ ] Load page on editor open
+- [ ] Unsaved changes warning
+- [ ] Save success/error notifications
+- [ ] Loading states
+
+**Estimated Effort:** 3 days
+**Dependencies:** WB-002, WB-006, WB-007
+
+---
+
+## Phase 2: Core Editing (Weeks 5-8)
+
+### WB-009: Undo/Redo System
+
+**Phase:** Phase 2 - Core Editing
+**Priority:** P0 - Critical
+**Labels:** undo-redo, editor, core-feature
+
+**Description:**
+Implement undo/redo functionality using the command pattern to allow users to revert and reapply changes.
+
+**Acceptance Criteria:**
+- [ ] Implement command pattern for actions
+- [ ] Create undo/redo stack
+- [ ] Keyboard shortcuts (Ctrl+Z, Ctrl+Y)
+- [ ] Undo/redo buttons in toolbar
+- [ ] Visual feedback
+- [ ] Limit stack size (performance)
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-002, WB-003
+
+---
+
+### WB-010: Copy/Paste Components
+
+**Phase:** Phase 2 - Core Editing
+**Priority:** P1 - High
+**Labels:** copy-paste, editor, productivity
+
+**Description:**
+Implement copy and paste functionality for components to improve editing productivity.
+
+**Acceptance Criteria:**
+- [ ] Implement copy component functionality
+- [ ] Implement paste component functionality
+- [ ] Keyboard shortcuts (Ctrl+C, Ctrl+V)
+- [ ] Copy multiple components
+- [ ] Paste with position offset
+- [ ] Clipboard management
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-003, WB-009
+
+---
+
+### WB-011: Delete Components
+
+**Phase:** Phase 2 - Core Editing
+**Priority:** P0 - Critical
+**Labels:** delete, editor, core-feature
+
+**Description:**
+Implement delete functionality for components with confirmation dialogs and undo support.
+
+**Acceptance Criteria:**
+- [ ] Implement delete component functionality
+- [ ] Delete button in property panel
+- [ ] Keyboard shortcut (Delete key)
+- [ ] Delete confirmation dialog
+- [ ] Delete nested components
+- [ ] Undo delete support
+
+**Estimated Effort:** 3 days
+**Dependencies:** WB-003, WB-009
+
+---
+
+### WB-012: Layer Tree View
+
+**Phase:** Phase 2 - Core Editing
+**Priority:** P1 - High
+**Labels:** layers, ui, editor
+
+**Description:**
+Create a layer tree sidebar that displays the component hierarchy and allows selection and reordering.
+
+**Acceptance Criteria:**
+- [ ] Create layer tree sidebar
+- [ ] Display component hierarchy
+- [ ] Expand/collapse layers
+- [ ] Select component from layer tree
+- [ ] Drag to reorder layers
+- [ ] Visual indicators (selected, hidden)
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-002, WB-013
+
+---
+
+### WB-013: Component Selection
+
+**Phase:** Phase 2 - Core Editing
+**Priority:** P0 - Critical
+**Labels:** selection, editor, core-feature
+
+**Description:**
+Implement component selection with visual indicators, multi-select support, and selection handles.
+
+**Acceptance Criteria:**
+- [ ] Click to select component
+- [ ] Visual selection indicator (outline)
+- [ ] Multi-select (Ctrl+Click, Shift+Click)
+- [ ] Selection handles (resize, move)
+- [ ] Deselect (click outside)
+- [ ] Selection in layer tree
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-003, WB-004
+
+---
+
+### WB-014: Property Editor (Advanced)
+
+**Phase:** Phase 2 - Core Editing
+**Priority:** P0 - Critical
+**Labels:** properties, editor, styling
+
+**Description:**
+Enhance the property panel with advanced property editors for typography, spacing, borders, backgrounds, shadows, and layout.
+
+**Acceptance Criteria:**
+- [ ] Typography editor (font family, size, weight, line height)
+- [ ] Spacing editor (margin, padding)
+- [ ] Border editor (width, style, color, radius)
+- [ ] Background editor (color, image, gradient)
+- [ ] Shadow editor (box shadow, text shadow)
+- [ ] Layout editor (display, flex, grid)
+- [ ] Position editor (relative, absolute, fixed)
+
+**Estimated Effort:** 2 weeks
+**Dependencies:** WB-005
+
+---
+
+### WB-015: Responsive Breakpoints
+
+**Phase:** Phase 2 - Core Editing
+**Priority:** P0 - Critical
+**Labels:** responsive, breakpoints, editor
+
+**Description:**
+Implement responsive breakpoint system with desktop, tablet, and mobile breakpoints and per-breakpoint property editing.
+
+**Acceptance Criteria:**
+- [ ] Desktop breakpoint (default, 1920px+)
+- [ ] Tablet breakpoint (768px - 1919px)
+- [ ] Mobile breakpoint (320px - 767px)
+- [ ] Breakpoint switcher in toolbar
+- [ ] Per-breakpoint property editing
+- [ ] Responsive preview mode
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-002, WB-014
+
+---
+
+### WB-016: Grid System
+
+**Phase:** Phase 2 - Core Editing
+**Priority:** P1 - High
+**Labels:** grid, layout, components
+
+**Description:**
+Implement a 12-column grid system with CSS Grid and Flexbox support for responsive layouts.
+
+**Acceptance Criteria:**
+- [ ] 12-column grid system
+- [ ] Grid container component
+- [ ] Grid column component
+- [ ] Flexbox layout support
+- [ ] CSS Grid support
+- [ ] Responsive grid (different columns per breakpoint)
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-004, WB-015
+
+---
+
+### WB-017: Container Components
+
+**Phase:** Phase 2 - Core Editing
+**Priority:** P1 - High
+**Labels:** containers, layout, components
+
+**Description:**
+Implement advanced container components for layout management including Container, Section, Row, and Column components.
+
+**Acceptance Criteria:**
+- [ ] Container component (max-width, centered)
+- [ ] Section component (full-width sections)
+- [ ] Row component (horizontal layout)
+- [ ] Column component (vertical layout)
+- [ ] Nested containers
+- [ ] Container spacing options
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-004, WB-016
+
+---
+
+### WB-018: Section Components
+
+**Phase:** Phase 2 - Core Editing
+**Priority:** P1 - High
+**Labels:** sections, layout, components
+
+**Description:**
+Enhance section components with background options, spacing controls, height management, and z-index handling.
+
+**Acceptance Criteria:**
+- [ ] Section component (page sections)
+- [ ] Section background options
+- [ ] Section padding/margin
+- [ ] Section height options (auto, full, custom)
+- [ ] Section overflow handling
+- [ ] Section z-index management
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-017
+
+---
+
+## Phase 3: Advanced Components (Weeks 9-12)
+
+### WB-019: Text Components
+
+**Phase:** Phase 3 - Advanced Components
+**Priority:** P0 - Critical
+**Labels:** text, components, content
+
+**Description:**
+Implement comprehensive text components including headings, paragraphs, rich text editor, and link components.
+
+**Acceptance Criteria:**
+- [ ] Heading component (H1-H6)
+- [ ] Paragraph component
+- [ ] Rich text editor component
+- [ ] Text formatting (bold, italic, underline)
+- [ ] Text alignment (left, center, right, justify)
+- [ ] Text color and styling
+- [ ] Link component
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-004
+
+---
+
+### WB-020: Media Components
+
+**Phase:** Phase 3 - Advanced Components
+**Priority:** P0 - Critical
+**Labels:** media, components, content
+
+**Description:**
+Implement media components for images, videos, audio, and galleries with upload and optimization capabilities.
+
+**Acceptance Criteria:**
+- [ ] Image component
+- [ ] Image upload functionality
+- [ ] Image optimization
+- [ ] Image gallery component
+- [ ] Video component (YouTube, Vimeo, self-hosted)
+- [ ] Video player controls
+- [ ] Audio component
+- [ ] Media library integration
+
+**Estimated Effort:** 2 weeks
+**Dependencies:** WB-004, WB-048
+
+---
+
+### WB-021: Form Components
+
+**Phase:** Phase 3 - Advanced Components
+**Priority:** P1 - High
+**Labels:** forms, components, input
+
+**Description:**
+Implement form components including inputs, textareas, selects, checkboxes, radio buttons, and file upload with basic validation.
+
+**Acceptance Criteria:**
+- [ ] Input component (text, email, password, number)
+- [ ] Textarea component
+- [ ] Select dropdown component
+- [ ] Checkbox component
+- [ ] Radio button component
+- [ ] File upload component
+- [ ] Form container component
+- [ ] Form validation (basic)
+
+**Estimated Effort:** 2 weeks
+**Dependencies:** WB-004
+
+---
+
+### WB-022: Layout Components
+
+**Phase:** Phase 3 - Advanced Components
+**Priority:** P1 - High
+**Labels:** layout, components
+
+**Description:**
+Implement advanced layout components including Stack, Grid, Spacer, and Divider components with flexbox options.
+
+**Acceptance Criteria:**
+- [ ] Advanced Row component (flexbox options)
+- [ ] Advanced Column component (flexbox options)
+- [ ] Stack component (vertical/horizontal stacking)
+- [ ] Grid component (CSS Grid)
+- [ ] Spacer component (flexible spacing)
+- [ ] Divider component (horizontal/vertical lines)
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-017, WB-016
+
+---
+
+### WB-023: Navigation Components
+
+**Phase:** Phase 3 - Advanced Components
+**Priority:** P1 - High
+**Labels:** navigation, components, ui
+
+**Description:**
+Implement navigation components including menus, breadcrumbs, pagination, tabs, accordion, and sidebar navigation.
+
+**Acceptance Criteria:**
+- [ ] Menu component (horizontal/vertical)
+- [ ] Menu item component
+- [ ] Breadcrumb component
+- [ ] Pagination component
+- [ ] Tab navigation component
+- [ ] Accordion component
+- [ ] Sidebar navigation component
+
+**Estimated Effort:** 2 weeks
+**Dependencies:** WB-004
+
+---
+
+### WB-024: Content Components
+
+**Phase:** Phase 3 - Advanced Components
+**Priority:** P1 - High
+**Labels:** content, components, ui
+
+**Description:**
+Implement content display components including cards, accordions, tabs, modals, tooltips, popovers, and alerts.
+
+**Acceptance Criteria:**
+- [ ] Card component
+- [ ] Card header, body, footer
+- [ ] Accordion component
+- [ ] Tabs component
+- [ ] Modal component
+- [ ] Tooltip component
+- [ ] Popover component
+- [ ] Alert component
+
+**Estimated Effort:** 2 weeks
+**Dependencies:** WB-004
+
+---
+
+### WB-025: Interactive Components
+
+**Phase:** Phase 3 - Advanced Components
+**Priority:** P1 - High
+**Labels:** interactive, components, ui
+
+**Description:**
+Implement interactive components including modals, dropdowns, tooltips, popovers, carousels, tabs, accordions, and collapse components.
+
+**Acceptance Criteria:**
+- [ ] Modal/Dialog component
+- [ ] Dropdown component
+- [ ] Tooltip component
+- [ ] Popover component
+- [ ] Carousel/Slider component
+- [ ] Tabs component
+- [ ] Accordion component
+- [ ] Collapse component
+
+**Estimated Effort:** 2 weeks
+**Dependencies:** WB-004, WB-024
+
+---
+
+### WB-026: Component Nesting
+
+**Phase:** Phase 3 - Advanced Components
+**Priority:** P0 - Critical
+**Labels:** nesting, components, core-feature
+
+**Description:**
+Implement support for nested components with depth limits, visual indicators, and proper property editing for nested components.
+
+**Acceptance Criteria:**
+- [ ] Support nested components
+- [ ] Nesting depth limits
+- [ ] Visual nesting indicators
+- [ ] Drag components into other components
+- [ ] Nested component selection
+- [ ] Nested component properties
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-003, WB-013
+
+---
+
+### WB-027: Component Templates
+
+**Phase:** Phase 3 - Advanced Components
+**Priority:** P2 - Medium
+**Labels:** templates, components, productivity
+
+**Description:**
+Implement component templates system allowing users to save and reuse component groups as templates.
+
+**Acceptance Criteria:**
+- [ ] Pre-built component groups
+- [ ] Save component group as template
+- [ ] Load component template
+- [ ] Template library
+- [ ] Template categories
+- [ ] Template search
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-026
+
+---
+
+## Phase 4: Styling & Design (Weeks 13-16)
+
+### WB-028: Color Picker (Advanced)
+
+**Phase:** Phase 4 - Styling & Design
+**Priority:** P0 - Critical
+**Labels:** color, styling, editor
+
+**Description:**
+Implement an advanced color picker with HSV/RGB/HEX support, color palettes, gradients, opacity, and global color variables.
+
+**Acceptance Criteria:**
+- [ ] Full color picker (HSV, RGB, HEX)
+- [ ] Color palette (saved colors)
+- [ ] Color history
+- [ ] Gradient editor
+- [ ] Color opacity/alpha
+- [ ] Color presets
+- [ ] Global color variables
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-005, WB-014
+
+---
+
+### WB-029: Typography Editor
+
+**Phase:** Phase 4 - Styling & Design
+**Priority:** P0 - Critical
+**Labels:** typography, styling, editor
+
+**Description:**
+Implement comprehensive typography editor with Google Fonts integration, font size, weight, line height, letter spacing, and text transforms.
+
+**Acceptance Criteria:**
+- [ ] Font family selector (Google Fonts integration)
+- [ ] Font size editor (px, em, rem)
+- [ ] Font weight selector
+- [ ] Line height editor
+- [ ] Letter spacing editor
+- [ ] Text transform (uppercase, lowercase, capitalize)
+- [ ] Text decoration (underline, strikethrough)
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-014, WB-028
+
+---
+
+### WB-030: Spacing Controls
+
+**Phase:** Phase 4 - Styling & Design
+**Priority:** P0 - Critical
+**Labels:** spacing, styling, editor
+
+**Description:**
+Implement advanced spacing controls for margin and padding with presets, responsive spacing, and multiple units support.
+
+**Acceptance Criteria:**
+- [ ] Margin editor (top, right, bottom, left)
+- [ ] Padding editor (top, right, bottom, left)
+- [ ] Spacing presets
+- [ ] Responsive spacing (different per breakpoint)
+- [ ] Spacing units (px, em, rem, %)
+- [ ] Visual spacing indicators
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-014, WB-015
+
+---
+
+### WB-031: Border Editor
+
+**Phase:** Phase 4 - Styling & Design
+**Priority:** P1 - High
+**Labels:** borders, styling, editor
+
+**Description:**
+Implement border editor with width, style, color, radius controls, presets, and responsive border support.
+
+**Acceptance Criteria:**
+- [ ] Border width editor
+- [ ] Border style selector (solid, dashed, dotted)
+- [ ] Border color picker
+- [ ] Border radius editor (individual corners)
+- [ ] Border presets
+- [ ] Responsive borders
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-014, WB-028
+
+---
+
+### WB-032: Shadow Editor
+
+**Phase:** Phase 4 - Styling & Design
+**Priority:** P1 - High
+**Labels:** shadows, styling, editor
+
+**Description:**
+Implement shadow editor for box shadows and text shadows with presets, multiple shadows support, and preview.
+
+**Acceptance Criteria:**
+- [ ] Box shadow editor (x, y, blur, spread, color)
+- [ ] Text shadow editor
+- [ ] Shadow presets
+- [ ] Multiple shadows support
+- [ ] Shadow preview
+- [ ] Responsive shadows
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-014, WB-028
+
+---
+
+### WB-033: Background Editor
+
+**Phase:** Phase 4 - Styling & Design
+**Priority:** P0 - Critical
+**Labels:** background, styling, editor
+
+**Description:**
+Implement comprehensive background editor supporting solid colors, images, gradients, and video backgrounds.
+
+**Acceptance Criteria:**
+- [ ] Solid color background
+- [ ] Image background (upload, URL)
+- [ ] Image position (center, cover, contain)
+- [ ] Image repeat (no-repeat, repeat, repeat-x, repeat-y)
+- [ ] Gradient background (linear, radial)
+- [ ] Gradient editor (colors, stops, angle)
+- [ ] Video background
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-014, WB-028, WB-020
+
+---
+
+### WB-034: Animation Editor
+
+**Phase:** Phase 4 - Styling & Design
+**Priority:** P2 - Medium
+**Labels:** animation, styling, editor
+
+**Description:**
+Implement animation editor with transitions, transforms, presets, hover animations, and scroll animations.
+
+**Acceptance Criteria:**
+- [ ] Transition editor (property, duration, easing)
+- [ ] Transform editor (translate, rotate, scale, skew)
+- [ ] Animation presets (fade, slide, bounce)
+- [ ] Hover animations
+- [ ] Scroll animations (basic)
+- [ ] Animation preview
+
+**Estimated Effort:** 2 weeks
+**Dependencies:** WB-014
+
+---
+
+### WB-035: Custom CSS Editor
+
+**Phase:** Phase 4 - Styling & Design
+**Priority:** P2 - Medium
+**Labels:** css, styling, advanced
+
+**Description:**
+Implement custom CSS editor with syntax highlighting, validation, scoped/global CSS support, and autocomplete.
+
+**Acceptance Criteria:**
+- [ ] Code editor for custom CSS
+- [ ] Syntax highlighting
+- [ ] CSS validation
+- [ ] Scoped CSS (component-level)
+- [ ] Global CSS (page-level)
+- [ ] CSS minification
+- [ ] CSS autocomplete
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-014
+
+---
+
+### WB-036: Style Presets
+
+**Phase:** Phase 4 - Styling & Design
+**Priority:** P2 - Medium
+**Labels:** presets, styling, productivity
+
+**Description:**
+Implement style preset system allowing users to save, load, and apply style sets to components and pages.
+
+**Acceptance Criteria:**
+- [ ] Save style set (colors, fonts, spacing)
+- [ ] Load style preset
+- [ ] Style preset library
+- [ ] Apply preset to component
+- [ ] Apply preset to page
+- [ ] Export/import presets
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-014, WB-028, WB-029, WB-030
+
+---
+
+### WB-037: Global Styles
+
+**Phase:** Phase 4 - Styling & Design
+**Priority:** P1 - High
+**Labels:** global-styles, styling, theme
+
+**Description:**
+Implement global style system with color variables, typography settings, spacing scale, and theme-level styling.
+
+**Acceptance Criteria:**
+- [ ] Global color variables
+- [ ] Global typography settings
+- [ ] Global spacing scale
+- [ ] Global border radius
+- [ ] Global shadows
+- [ ] Theme-level styling
+- [ ] Style inheritance
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-036
+
+---
+
+## Phase 5: Templates & Themes (Weeks 17-20)
+
+### WB-038: Template Library
+
+**Phase:** Phase 5 - Templates & Themes
+**Priority:** P1 - High
+**Labels:** templates, library, ui
+
+**Description:**
+Create template library UI with categories, search, filter, preview, installation, and template management.
+
+**Acceptance Criteria:**
+- [ ] Template library UI
+- [ ] Template categories (landing, blog, shop, dashboard)
+- [ ] Template search and filter
+- [ ] Template preview
+- [ ] Template installation
+- [ ] Template management (create, edit, delete)
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-006, WB-007
+
+---
+
+### WB-039: Template System
+
+**Phase:** Phase 5 - Templates & Themes
+**Priority:** P0 - Critical
+**Labels:** templates, core-feature
+
+**Description:**
+Implement the core template system allowing users to create templates from pages, save them, and load them.
+
+**Acceptance Criteria:**
+- [ ] Create template from page
+- [ ] Save template to library
+- [ ] Load template to page
+- [ ] Template metadata (name, description, category)
+- [ ] Template preview images
+- [ ] Template versioning
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-006, WB-038
+
+---
+
+### WB-040: Theme Integration
+
+**Phase:** Phase 5 - Templates & Themes
+**Priority:** P1 - High
+**Labels:** themes, integration, bosa
+
+**Description:**
+Implement BOSA theme integration allowing the editor to use existing BOSA themes as a base for pages.
+
+**Acceptance Criteria:**
+- [ ] Load BOSA theme as base
+- [ ] Apply theme styles to editor
+- [ ] Theme component library
+- [ ] Theme color palette
+- [ ] Theme typography
+- [ ] Theme asset integration
+
+**Estimated Effort:** 2 weeks
+**Dependencies:** WB-039
+
+---
+
+### WB-041: Export to Theme
+
+**Phase:** Phase 5 - Templates & Themes
+**Priority:** P1 - High
+**Labels:** export, themes, bosa
+
+**Description:**
+Implement functionality to export page configurations to BOSA theme structure with theme.yaml, CSS, JS, and assets.
+
+**Acceptance Criteria:**
+- [ ] Convert page config to theme structure
+- [ ] Generate theme.yaml
+- [ ] Export CSS files
+- [ ] Export JS files
+- [ ] Export assets
+- [ ] Create installable theme ZIP
+- [ ] Theme validation
+
+**Estimated Effort:** 2 weeks
+**Dependencies:** WB-007, WB-039
+
+---
+
+### WB-042: Template Marketplace
+
+**Phase:** Phase 5 - Templates & Themes
+**Priority:** P2 - Medium
+**Labels:** marketplace, templates, community
+
+**Description:**
+Implement template marketplace for sharing, uploading, downloading templates with ratings, reviews, and versioning.
+
+**Acceptance Criteria:**
+- [ ] Template sharing system
+- [ ] Template upload/download
+- [ ] Template ratings/reviews
+- [ ] Template categories
+- [ ] Template search
+- [ ] Template versioning
+
+**Estimated Effort:** 2 weeks
+**Dependencies:** WB-038, WB-039
+
+---
+
+### WB-043: Clone Page
+
+**Phase:** Phase 5 - Templates & Themes
+**Priority:** P2 - Medium
+**Labels:** clone, productivity
+
+**Description:**
+Implement page cloning functionality allowing users to duplicate pages with new names and routes.
+
+**Acceptance Criteria:**
+- [ ] Duplicate page functionality
+- [ ] Clone with new name
+- [ ] Clone with new route
+- [ ] Clone templates
+- [ ] Bulk clone operations
+
+**Estimated Effort:** 3 days
+**Dependencies:** WB-006
+
+---
+
+### WB-044: Page Templates
+
+**Phase:** Phase 5 - Templates & Themes
+**Priority:** P2 - Medium
+**Labels:** page-templates, templates
+
+**Description:**
+Implement page template system for headers, footers, sidebars, and page layouts with inheritance and overrides.
+
+**Acceptance Criteria:**
+- [ ] Header template
+- [ ] Footer template
+- [ ] Sidebar template
+- [ ] Page layout templates
+- [ ] Template inheritance
+- [ ] Template overrides
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-039
+
+---
+
+## Phase 6: Advanced Features (Weeks 21-24)
+
+### WB-045: Version History
+
+**Phase:** Phase 6 - Advanced Features
+**Priority:** P1 - High
+**Labels:** version-history, advanced
+
+**Description:**
+Implement version history system allowing users to view, preview, compare, and restore previous page versions.
+
+**Acceptance Criteria:**
+- [ ] Save page versions
+- [ ] Version list view
+- [ ] Version preview
+- [ ] Restore version
+- [ ] Version comparison
+- [ ] Version metadata (date, author, changes)
+- [ ] Version limit (keep last N versions)
+
+**Estimated Effort:** 2 weeks
+**Dependencies:** WB-006
+
+---
+
+### WB-046: Collaboration
+
+**Phase:** Phase 6 - Advanced Features
+**Priority:** P2 - Medium
+**Labels:** collaboration, real-time, advanced
+
+**Description:**
+Implement multi-user collaboration with real-time editing, user cursors, conflict resolution, and permissions.
+
+**Acceptance Criteria:**
+- [ ] Multi-user editing support
+- [ ] Real-time collaboration (WebSocket)
+- [ ] User cursors/selection
+- [ ] Conflict resolution
+- [ ] User permissions (edit, view)
+- [ ] Collaboration indicators
+
+**Estimated Effort:** 3 weeks
+**Dependencies:** WB-002, WB-006
+
+---
+
+### WB-047: Comments/Annotations
+
+**Phase:** Phase 6 - Advanced Features
+**Priority:** P2 - Medium
+**Labels:** comments, collaboration, advanced
+
+**Description:**
+Implement commenting system allowing users to add comments to components with threads, notifications, and permissions.
+
+**Acceptance Criteria:**
+- [ ] Add comments to components
+- [ ] Comment thread
+- [ ] Resolve comments
+- [ ] Comment notifications
+- [ ] Comment history
+- [ ] Comment permissions
+
+**Estimated Effort:** 2 weeks
+**Dependencies:** WB-046
+
+---
+
+### WB-048: Asset Library
+
+**Phase:** Phase 6 - Advanced Features
+**Priority:** P0 - Critical
+**Labels:** assets, library, media
+
+**Description:**
+Create asset library UI for managing images, videos, and files with organization, search, optimization, and CDN integration.
+
+**Acceptance Criteria:**
+- [ ] Asset library UI
+- [ ] Image upload
+- [ ] Video upload
+- [ ] File management
+- [ ] Asset organization (folders, tags)
+- [ ] Asset search
+- [ ] Asset optimization
+- [ ] Asset CDN integration
+
+**Estimated Effort:** 2 weeks
+**Dependencies:** WB-006
+
+---
+
+### WB-049: Media Upload/Management
+
+**Phase:** Phase 6 - Advanced Features
+**Priority:** P0 - Critical
+**Labels:** upload, media, management
+
+**Description:**
+Implement comprehensive media upload and management with drag-and-drop, progress tracking, editing, and optimization.
+
+**Acceptance Criteria:**
+- [ ] Drag-and-drop upload
+- [ ] Multiple file upload
+- [ ] Upload progress
+- [ ] Image cropping/editing
+- [ ] Image optimization
+- [ ] File type validation
+- [ ] File size limits
+- [ ] Storage management
+
+**Estimated Effort:** 2 weeks
+**Dependencies:** WB-048
+
+---
+
+### WB-050: SEO Editor
+
+**Phase:** Phase 6 - Advanced Features
+**Priority:** P1 - High
+**Labels:** seo, metadata, advanced
+
+**Description:**
+Implement SEO editor for meta tags, Open Graph, Twitter Cards, canonical URLs, robots meta, and Schema.org markup.
+
+**Acceptance Criteria:**
+- [ ] Meta title editor
+- [ ] Meta description editor
+- [ ] Open Graph tags
+- [ ] Twitter Card tags
+- [ ] Canonical URL
+- [ ] Robots meta
+- [ ] Schema.org markup
+- [ ] SEO preview
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-006
+
+---
+
+### WB-051: Custom Code Injection
+
+**Phase:** Phase 6 - Advanced Features
+**Priority:** P2 - Medium
+**Labels:** code-injection, advanced
+
+**Description:**
+Implement custom code injection for head, body, and component-level code with validation and security checks.
+
+**Acceptance Criteria:**
+- [ ] Head code injection (page-level)
+- [ ] Body code injection (page-level)
+- [ ] Component-level code injection
+- [ ] Script injection
+- [ ] Style injection
+- [ ] Code validation
+- [ ] Security checks
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-007
+
+---
+
+### WB-052: Conditional Visibility
+
+**Phase:** Phase 6 - Advanced Features
+**Priority:** P1 - High
+**Labels:** conditional, visibility, advanced
+
+**Description:**
+Implement conditional visibility system allowing components to show/hide based on user roles, authentication, and custom conditions.
+
+**Acceptance Criteria:**
+- [ ] Show/hide based on conditions
+- [ ] User role conditions
+- [ ] Authentication conditions
+- [ ] Custom conditions (API-based)
+- [ ] Conditional logic builder
+- [ ] Preview conditional states
+
+**Estimated Effort:** 2 weeks
+**Dependencies:** WB-007
+
+---
+
+### WB-053: Dynamic Content
+
+**Phase:** Phase 6 - Advanced Features
+**Priority:** P1 - High
+**Labels:** dynamic-content, data-binding, advanced
+
+**Description:**
+Implement dynamic content system connecting components to app data with data binding, filtering, pagination, and real-time updates.
+
+**Acceptance Criteria:**
+- [ ] Connect to app data (API)
+- [ ] Data binding
+- [ ] Dynamic lists
+- [ ] Dynamic forms
+- [ ] Data filtering
+- [ ] Data pagination
+- [ ] Real-time data updates
+
+**Estimated Effort:** 3 weeks
+**Dependencies:** WB-007, WB-060
+
+---
+
+### WB-054: Form Builder
+
+**Phase:** Phase 6 - Advanced Features
+**Priority:** P1 - High
+**Labels:** forms, builder, advanced
+
+**Description:**
+Implement comprehensive form builder with field types, validation rules, submission handling, email notifications, and analytics.
+
+**Acceptance Criteria:**
+- [ ] Form component builder
+- [ ] Form field types
+- [ ] Form validation rules
+- [ ] Form submission handling
+- [ ] Form email notifications
+- [ ] Form data storage
+- [ ] Form analytics
+
+**Estimated Effort:** 2 weeks
+**Dependencies:** WB-021
+
+---
+
+## Phase 7: Plugin Integration (Weeks 25-28)
+
+### WB-055: Plugin Component Registry
+
+**Phase:** Phase 7 - Plugin Integration
+**Priority:** P1 - High
+**Labels:** plugins, registry, integration
+
+**Description:**
+Implement plugin component registry allowing plugins to register custom components with metadata, icons, and categories.
+
+**Acceptance Criteria:**
+- [ ] Component registration API
+- [ ] Plugin component discovery
+- [ ] Component metadata
+- [ ] Component icons
+- [ ] Component categories
+- [ ] Component versioning
+
+**Estimated Effort:** 2 weeks
+**Dependencies:** WB-004
+
+---
+
+### WB-056: Plugin Widget System
+
+**Phase:** Phase 7 - Plugin Integration
+**Priority:** P1 - High
+**Labels:** widgets, plugins, integration
+
+**Description:**
+Implement plugin widget system allowing plugins to provide widgets with configuration, data binding, events, and styling.
+
+**Acceptance Criteria:**
+- [ ] Widget registration
+- [ ] Widget configuration
+- [ ] Widget data binding
+- [ ] Widget events
+- [ ] Widget styling
+- [ ] Widget documentation
+
+**Estimated Effort:** 2 weeks
+**Dependencies:** WB-055
+
+---
+
+### WB-057: App-Specific Components
+
+**Phase:** Phase 7 - Plugin Integration
+**Priority:** P1 - High
+**Labels:** app-components, integration, bosa
+
+**Description:**
+Implement support for components from other BOSA apps with discovery, integration, styling, data, and events.
+
+**Acceptance Criteria:**
+- [ ] Components from other BOSA apps
+- [ ] App component discovery
+- [ ] App component integration
+- [ ] App component styling
+- [ ] App component data
+- [ ] App component events
+
+**Estimated Effort:** 2 weeks
+**Dependencies:** WB-055
+
+---
+
+### WB-058: Event System
+
+**Phase:** Phase 7 - Plugin Integration
+**Priority:** P1 - High
+**Labels:** events, integration, advanced
+
+**Description:**
+Implement component event system with click, hover events, custom events, handlers, propagation, logging, and debugging.
+
+**Acceptance Criteria:**
+- [ ] Component events (click, hover, etc.)
+- [ ] Custom events
+- [ ] Event handlers
+- [ ] Event propagation
+- [ ] Event logging
+- [ ] Event debugging
+
+**Estimated Effort:** 2 weeks
+**Dependencies:** WB-004
+
+---
+
+### WB-059: Data Binding
+
+**Phase:** Phase 7 - Plugin Integration
+**Priority:** P1 - High
+**Labels:** data-binding, integration, advanced
+
+**Description:**
+Implement data binding system connecting components to app data with source configuration, transformation, caching, and error handling.
+
+**Acceptance Criteria:**
+- [ ] Connect components to app data
+- [ ] Data source configuration
+- [ ] Data transformation
+- [ ] Data caching
+- [ ] Data refresh
+- [ ] Data error handling
+
+**Estimated Effort:** 2 weeks
+**Dependencies:** WB-053, WB-060
+
+---
+
+### WB-060: API Integration
+
+**Phase:** Phase 7 - Plugin Integration
+**Priority:** P1 - High
+**Labels:** api, integration, advanced
+
+**Description:**
+Implement API integration system for fetching data from app APIs with authentication, request building, response handling, and caching.
+
+**Acceptance Criteria:**
+- [ ] Fetch data from app APIs
+- [ ] API authentication
+- [ ] API request builder
+- [ ] API response handling
+- [ ] API error handling
+- [ ] API caching
+
+**Estimated Effort:** 2 weeks
+**Dependencies:** WB-007
+
+---
+
+### WB-061: Authentication Integration
+
+**Phase:** Phase 7 - Plugin Integration
+**Priority:** P1 - High
+**Labels:** authentication, integration, bosa
+
+**Description:**
+Implement authentication integration with show/hide based on auth status, user role conditions, login/logout components, and protected content.
+
+**Acceptance Criteria:**
+- [ ] Show/hide based on authentication
+- [ ] User role conditions
+- [ ] Permission-based visibility
+- [ ] Login/logout components
+- [ ] User profile components
+- [ ] Protected content
+
+**Estimated Effort:** 2 weeks
+**Dependencies:** WB-052
+
+---
+
+### WB-062: Multi-Language Support
+
+**Phase:** Phase 7 - Plugin Integration
+**Priority:** P1 - High
+**Labels:** i18n, multi-language, integration
+
+**Description:**
+Implement multi-language support with i18n components, language switcher, per-language content, RTL support, and translation management.
+
+**Acceptance Criteria:**
+- [ ] i18n component support
+- [ ] Language switcher component
+- [ ] Per-language content
+- [ ] Language-specific styling
+- [ ] Translation management
+- [ ] RTL support
+
+**Estimated Effort:** 2 weeks
+**Dependencies:** WB-004
+
+---
+
+## Phase 8: Performance & Polish (Weeks 29-32)
+
+### WB-063: Performance Optimization
+
+**Phase:** Phase 8 - Performance & Polish
+**Priority:** P0 - Critical
+**Labels:** performance, optimization
+
+**Description:**
+Implement performance optimizations including code splitting, lazy loading, image optimization, bundle size reduction, and memory management.
+
+**Acceptance Criteria:**
+- [ ] Code splitting
+- [ ] Lazy loading components
+- [ ] Image lazy loading
+- [ ] Asset optimization
+- [ ] Bundle size optimization
+- [ ] Render optimization
+- [ ] Memory management
+
+**Estimated Effort:** 2 weeks
+**Dependencies:** All previous phases
+
+---
+
+### WB-064: Renderer Optimization
+
+**Phase:** Phase 8 - Performance & Polish
+**Priority:** P0 - Critical
+**Labels:** renderer, performance, optimization
+
+**Description:**
+Optimize page renderer for fast rendering with SSR, static generation, caching, CDN integration, minification, and compression.
+
+**Acceptance Criteria:**
+- [ ] Fast page rendering
+- [ ] Server-side rendering (SSR)
+- [ ] Static page generation
+- [ ] Caching strategies
+- [ ] CDN integration
+- [ ] Minification
+- [ ] Compression
+
+**Estimated Effort:** 2 weeks
+**Dependencies:** WB-007
+
+---
+
+### WB-065: Editor Performance
+
+**Phase:** Phase 8 - Performance & Polish
+**Priority:** P0 - Critical
+**Labels:** editor, performance, optimization
+
+**Description:**
+Optimize editor performance for smooth editing experience with optimized re-renders, virtual scrolling, debounced updates, and performance monitoring.
+
+**Acceptance Criteria:**
+- [ ] Smooth editing experience
+- [ ] Optimized re-renders
+- [ ] Virtual scrolling (large pages)
+- [ ] Debounced updates
+- [ ] Efficient state management
+- [ ] Performance monitoring
+
+**Estimated Effort:** 2 weeks
+**Dependencies:** WB-002
+
+---
+
+### WB-066: Mobile Editor
+
+**Phase:** Phase 8 - Performance & Polish
+**Priority:** P1 - High
+**Labels:** mobile, responsive, editor
+
+**Description:**
+Implement mobile-friendly editor UI with responsive layout, touch-friendly controls, mobile canvas view, and mobile gestures.
+
+**Acceptance Criteria:**
+- [ ] Responsive editor UI
+- [ ] Touch-friendly controls
+- [ ] Mobile canvas view
+- [ ] Mobile property panel
+- [ ] Mobile component palette
+- [ ] Mobile gestures
+
+**Estimated Effort:** 2 weeks
+**Dependencies:** WB-002
+
+---
+
+### WB-067: Keyboard Shortcuts
+
+**Phase:** Phase 8 - Performance & Polish
+**Priority:** P2 - Medium
+**Labels:** shortcuts, productivity, accessibility
+
+**Description:**
+Implement comprehensive keyboard shortcuts with customization, help dialog, Mac/Windows key differences, and accessibility shortcuts.
+
+**Acceptance Criteria:**
+- [ ] Comprehensive keyboard shortcuts
+- [ ] Shortcut customization
+- [ ] Shortcut help dialog
+- [ ] Mac/Windows key differences
+- [ ] Accessibility shortcuts
+
+**Estimated Effort:** 1 week
+**Dependencies:** WB-002
+
+---
+
+### WB-068: Accessibility
+
+**Phase:** Phase 8 - Performance & Polish
+**Priority:** P1 - High
+**Labels:** accessibility, a11y, compliance
+
+**Description:**
+Implement WCAG 2.1 AA compliance with keyboard navigation, screen reader support, ARIA labels, focus management, and color contrast.
+
+**Acceptance Criteria:**
+- [ ] WCAG 2.1 AA compliance
+- [ ] Keyboard navigation
+- [ ] Screen reader support
+- [ ] ARIA labels
+- [ ] Focus management
+- [ ] Color contrast
+- [ ] Alt text for images
+
+**Estimated Effort:** 2 weeks
+**Dependencies:** All UI components
+
+---
+
+### WB-069: Documentation
+
+**Phase:** Phase 8 - Performance & Polish
+**Priority:** P1 - High
+**Labels:** documentation, user-guide
+
+**Description:**
+Create comprehensive documentation including user guide, video tutorials, API documentation, component docs, templates docs, FAQ, and troubleshooting.
+
+**Acceptance Criteria:**
+- [ ] User guide
+- [ ] Video tutorials
+- [ ] API documentation
+- [ ] Component documentation
+- [ ] Template documentation
+- [ ] FAQ
+- [ ] Troubleshooting guide
+
+**Estimated Effort:** 2 weeks
+**Dependencies:** All features
+
+---
+
+### WB-070: Testing
+
+**Phase:** Phase 8 - Performance & Polish
+**Priority:** P0 - Critical
+**Labels:** testing, quality-assurance
+
+**Description:**
+Implement comprehensive testing including unit tests, integration tests, E2E tests, visual regression tests, performance tests, accessibility tests, and browser compatibility tests.
+
+**Acceptance Criteria:**
+- [ ] Unit tests
+- [ ] Integration tests
+- [ ] E2E tests (Playwright/Cypress)
+- [ ] Visual regression tests
+- [ ] Performance tests
+- [ ] Accessibility tests
+- [ ] Browser compatibility tests
+
+**Estimated Effort:** 3 weeks
+**Dependencies:** All features
+
+---
+
+### WB-071: Bug Fixes and Refinements
+
+**Phase:** Phase 8 - Performance & Polish
+**Priority:** P1 - High
+**Labels:** bug-fixes, polish, refinement
+
+**Description:**
+Final bug fixes, UI/UX refinements, performance improvements, security fixes, code cleanup, and documentation updates.
+
+**Acceptance Criteria:**
+- [ ] Bug triage and fixing
+- [ ] UI/UX refinements
+- [ ] Performance improvements
+- [ ] Security fixes
+- [ ] Code cleanup
+- [ ] Documentation updates
+
+**Estimated Effort:** Ongoing
+**Dependencies:** All features
+
+---
+
+## Summary
+
+**Total Issues:** 71
+**Phases:** 8
+**Estimated Timeline:** 32 weeks (8 months)
+**Team Size:** 2-3 developers recommended
+**Priority:** High (core BOSA functionality)
+
+### Phase Breakdown:
+- **Phase 1 (Foundation):** 8 issues, 4 weeks
+- **Phase 2 (Core Editing):** 10 issues, 4 weeks
+- **Phase 3 (Advanced Components):** 9 issues, 4 weeks
+- **Phase 4 (Styling & Design):** 10 issues, 4 weeks
+- **Phase 5 (Templates & Themes):** 7 issues, 4 weeks
+- **Phase 6 (Advanced Features):** 10 issues, 4 weeks
+- **Phase 7 (Plugin Integration):** 8 issues, 4 weeks
+- **Phase 8 (Performance & Polish):** 9 issues, 4 weeks
+
+---
+
+**Document Version:** 1.0
+**Created:** December 21, 2025
+**Status:** Ready for Linear Import
diff --git a/docs/DEVELOPER_GUIDE.md b/docs/DEVELOPER_GUIDE.md
new file mode 100644
index 0000000..1facb8e
--- /dev/null
+++ b/docs/DEVELOPER_GUIDE.md
@@ -0,0 +1,6543 @@
+# BOSA Developer Guide
+**Version:** 0.0.2.008
+**Date:** December 5, 2025
+**Audience:** Developers building apps/plugins for BOSA
+
+---
+
+## Related Documentation
+
+For comprehensive multi-language documentation, see:
+
+- **[Architecture Documentation](ARCHITECTURE.md)** - Complete system architecture overview
+- **[SDK API Reference](SDK_API_REFERENCE.md)** - Complete API reference for all SDKs (Node.js, PHP, Python, Go)
+- **[Quick Start Guides](QUICK_START_GUIDES.md)** - Language-specific quick start guides
+- **[Messaging API Reference](MESSAGING_API_REFERENCE.md)** - Complete messaging API documentation
+
+---
+
+## Table of Contents
+
+1. [Introduction](#1-introduction)
+2. [Getting Started](#2-getting-started)
+ - 2.1 [Prerequisites](#21-prerequisites)
+ - 2.2 [Creating Your First Plugin](#22-creating-your-first-plugin)
+ - 2.3 [Supported Runtimes](#23-supported-runtimes)
+ - 2.4 [BOSA SDKs](#24-bosa-sdks)
+3. [Plugin Structure](#3-plugin-structure)
+4. [Plugin Development](#4-plugin-development)
+ - 4.5 [Theme System](#45-theme-system)
+5. [BOSA API Reference](#5-bosa-api-reference)
+ - 5.1 [Database API](#51-database-api-bosadb)
+ - 5.2 [Event API](#52-event-api-bosaevents)
+ - 5.3 [Logging API](#53-logging-api-bosalog)
+ - 5.4 [Configuration API](#54-configuration-api-bosaconfig)
+ - 5.5 [Real-Time API](#55-real-time-api-bosarealtime)
+ - 5.6 [I18n Translation API](#56-i18n-translation-api-bosai18n)
+ - 5.7 [Messaging API](#57-messaging-api-rest)
+6. [Multi-Tenancy Support](#6-multi-tenancy-support)
+7. [Currency Support](#7-currency-support)
+8. [Location Services](#8-location-services)
+9. [Database Operations](#9-database-operations)
+10. [Event System](#10-event-system)
+11. [Real-Time Features](#11-real-time-features)
+12. [HTTP Routes](#12-http-routes)
+13. [Testing Plugins](#13-testing-plugins)
+14. [Best Practices](#14-best-practices)
+15. [Examples](#15-examples)
+16. [Error Logging and Monitoring](#16-error-logging-and-monitoring)
+17. [Production Deployment with Nginx](#17-production-deployment-with-nginx)
+
+---
+
+## 1. Introduction
+
+BOSA (Business Operating System Architecture) is a minimalist kernel for running business applications. It provides infrastructure services (authentication, database, events, real-time) while your business logic lives in plugins.
+
+**Key Features:**
+- **Multi-Language Support:** Lua (embedded), Node.js, PHP, Go (process-based runtimes)
+- **Database:** SQLite (primary), PostgreSQL (supported), MySQL/MariaDB, MongoDB (planned)
+- **Real-Time:** WebSocket and Server-Sent Events (SSE)
+- **Event System:** Pub/sub event bus
+- **Authentication:** JWT-based authentication built-in
+- **SDKs:** Official SDKs for all supported languages (Node.js, Python, PHP, Go) - see [BOSA SDKs](#24-bosa-sdks) section
+
+**What You Build:**
+- Business logic in your preferred language (Lua, Node.js, PHP, Go)
+- Database schema via migrations
+- HTTP routes via plugin routes
+- Real-time updates via WebSocket broadcasts
+- Full-stack applications that leverage BOSA's infrastructure services
+
+---
+
+## 2. Getting Started
+
+### 2.1 Prerequisites
+
+- **BOSA Instance:** Running BOSA server (see installation guide)
+- **Language Knowledge:**
+ - For Lua plugins: Basic Lua programming (5.4 compatible)
+ - For Node.js plugins: JavaScript/TypeScript and npm
+ - For PHP plugins: PHP and Composer
+ - For Go plugins: Go programming language
+- **SQL Knowledge:** Basic SQL for migrations
+- **Text Editor:** Any text editor (VS Code, Vim, etc.)
+
+### 2.2 Creating Your First Plugin
+
+#### Step 1: Create Plugin Directory
+
+```bash
+mkdir -p plugins/my-first-plugin
+cd plugins/my-first-plugin
+```
+
+#### Step 2: Create Manifest File
+
+Create `manifest.yaml`:
+
+```yaml
+name: my-first-plugin
+version: 1.0.0
+description: My first BOSA plugin
+author: Your Name
+
+runtime:
+ type: lua
+ entry: main.lua
+
+routes:
+ - path: /hello
+ method: GET
+ handler: hello
+
+events:
+ subscribe:
+ - user.created
+ publish:
+ - greeting.sent
+```
+
+#### Step 3: Create Main Script
+
+Create `main.lua`:
+
+```lua
+function init()
+ bosa.log.info("My first plugin initialized!")
+ return true
+end
+
+function hello(request)
+ return {
+ status = 200,
+ body = {
+ message = "Hello from my first plugin!"
+ }
+ }
+end
+```
+
+#### Step 4: Install Plugin
+
+**Option A: Via CLI**
+```bash
+# From BOSA root directory
+bosa plugin install ./plugins/my-first-plugin
+
+# Or from zip file
+bosa plugin install my-first-plugin.zip
+
+# Or from git repository
+bosa plugin install https://github.com/user/my-first-plugin.git
+```
+
+**Option B: Via UI (Super Admin)**
+1. Navigate to `/plugins` page
+2. Click "Choose File" and select `my-first-plugin.zip`
+3. Click "Install Plugin"
+4. Plugin is automatically loaded (no restart needed!)
+
+#### Step 5: Test Plugin
+
+```bash
+# Visit: http://localhost:3000/my-first-plugin/hello
+curl http://localhost:3000/my-first-plugin/hello
+```
+
+**Note:** Plugins installed via UI are automatically loaded. CLI installations require server restart.
+
+---
+
+## 2.3 Supported Runtimes
+
+BOSA supports multiple runtime types for plugin development:
+
+### Lua Runtime (Embedded)
+- **Type:** `lua`
+- **Entry:** `main.lua`
+- **Best For:** Simple plugins, quick development
+- **Execution:** Embedded in BOSA process (no separate process)
+
+### Node.js Runtime (Process-Based)
+- **Type:** `nodejs`
+- **Entry:** `index.js` or `server.js`
+- **Best For:** Full-stack JavaScript/TypeScript applications
+- **Execution:** Separate Node.js process (port range: 3001-4000)
+- **SDK:** `bosa-sdk-node` package available
+- **Requirements:** Node.js and npm installed
+
+### PHP Runtime (Process-Based)
+- **Type:** `php`
+- **Entry:** `index.php` or `server.php`
+- **Best For:** PHP applications and legacy code migration
+- **Execution:** Separate PHP process using built-in server (port range: 4001-5000)
+- **Requirements:** PHP and Composer installed
+
+### Go Runtime (Process-Based)
+- **Type:** `go`
+- **Entry:** `main.go`
+- **Best For:** High-performance native applications
+- **Execution:** Compiled Go binary as separate process (port range: 5001-6000)
+- **Requirements:** Go compiler installed
+- **Note:** Plugin is compiled to binary at install time
+
+### Choosing a Runtime
+
+| Runtime | Performance | Development Speed | Ecosystem | Use Case |
+|---------|------------|-------------------|-----------|----------|
+| Lua | High | Fast | Limited | Simple plugins, embedded scripts |
+| Node.js | Good | Very Fast | Extensive | Full-stack apps, modern web |
+| PHP | Good | Fast | Extensive | Legacy apps, web applications |
+| Go | Excellent | Moderate | Growing | High-performance, native apps |
+
+---
+
+## 2.4 BOSA SDKs
+
+BOSA provides official SDKs for all supported languages to simplify plugin development. The SDKs provide a unified API for accessing BOSA services (database, events, real-time, configuration, etc.).
+
+### SDK Locations
+
+#### Local Development (BOSA Repository)
+
+All SDKs are located in the `sdk/` directory of the BOSA repository:
+
+```
+BOSA/
+└── sdk/
+ ├── bosa-sdk-node/ # Node.js/TypeScript SDK
+ ├── bosa-sdk-python/ # Python SDK
+ ├── bosa-sdk-php/ # PHP SDK
+ └── bosa-sdk-go/ # Go SDK
+```
+
+**Local Path:** `./sdk/` (relative to BOSA root directory) or `[BOSA_INSTALL_PATH]/sdk/`
+
+#### GitHub Repository
+
+All SDKs are available in the main BOSA repository:
+
+**Repository:** `https://github.com/mmabdalla/BOSA`
+
+**SDK Paths on GitHub:**
+- Node.js: `https://github.com/mmabdalla/BOSA/tree/main/sdk/bosa-sdk-node`
+- Python: `https://github.com/mmabdalla/BOSA/tree/main/sdk/bosa-sdk-python`
+- PHP: `https://github.com/mmabdalla/BOSA/tree/main/sdk/bosa-sdk-php`
+- Go: `https://github.com/mmabdalla/BOSA/tree/main/sdk/bosa-sdk-go`
+
+### Installing SDKs
+
+#### Node.js SDK (`bosa-sdk-node`)
+
+**Installation:**
+```bash
+npm install bosa-sdk-node
+```
+
+**Local Development:**
+```bash
+# From your plugin directory
+npm install ../../sdk/bosa-sdk-node
+# Or use npm link
+cd ../../sdk/bosa-sdk-node
+npm link
+cd ../../plugins/your-plugin
+npm link bosa-sdk-node
+```
+
+**GitHub:**
+- Repository: `https://github.com/mmabdalla/BOSA/tree/main/sdk/bosa-sdk-node`
+- README: `https://github.com/mmabdalla/BOSA/blob/main/sdk/bosa-sdk-node/README.md`
+
+**Quick Start:**
+```javascript
+const { BOSA } = require('bosa-sdk-node');
+const bosa = new BOSA({
+ kernelURL: process.env.BOSA_KERNEL_URL || 'http://localhost:3000',
+ pluginName: process.env.PLUGIN_NAME,
+ pluginToken: process.env.BOSA_KERNEL_TOKEN,
+});
+await bosa.init();
+```
+
+#### Python SDK (`bosa-sdk-python`)
+
+**Installation:**
+```bash
+pip install bosa-sdk-python
+```
+
+**Local Development:**
+```bash
+# From your plugin directory
+pip install -e ../../sdk/bosa-sdk-python
+```
+
+**GitHub:**
+- Repository: `https://github.com/mmabdalla/BOSA/tree/main/sdk/bosa-sdk-python`
+- README: `https://github.com/mmabdalla/BOSA/blob/main/sdk/bosa-sdk-python/README.md`
+
+**Quick Start:**
+```python
+from bosa import BOSA
+bosa = BOSA({
+ 'kernelURL': 'http://localhost:3000',
+ 'pluginName': 'my-plugin',
+ 'pluginToken': 'your-token',
+})
+await bosa.init()
+```
+
+#### PHP SDK (`bosa-sdk-php`)
+
+**Installation:**
+```bash
+composer require bosa/bosa-sdk-php
+```
+
+**Local Development:**
+```bash
+# From your plugin directory
+composer config repositories.bosa-sdk path ../../sdk/bosa-sdk-php
+composer require bosa/bosa-sdk-php:@dev
+```
+
+**GitHub:**
+- Repository: `https://github.com/mmabdalla/BOSA/tree/main/sdk/bosa-sdk-php`
+- README: `https://github.com/mmabdalla/BOSA/blob/main/sdk/bosa-sdk-php/README.md`
+
+**Quick Start:**
+```php
+ 'http://localhost:3000',
+ 'pluginName' => 'my-plugin',
+ 'pluginToken' => 'your-token',
+]);
+$bosa->init();
+```
+
+#### Go SDK (`bosa-sdk-go`)
+
+**Installation:**
+```bash
+go get github.com/mmabdalla/BOSA/sdk/bosa-sdk-go
+```
+
+**Local Development:**
+```bash
+# Use replace directive in go.mod
+replace github.com/mmabdalla/BOSA/sdk/bosa-sdk-go => ../../sdk/bosa-sdk-go
+go get github.com/mmabdalla/BOSA/sdk/bosa-sdk-go
+```
+
+**GitHub:**
+- Repository: `https://github.com/mmabdalla/BOSA/tree/main/sdk/bosa-sdk-go`
+- README: `https://github.com/mmabdalla/BOSA/blob/main/sdk/bosa-sdk-go/README.md`
+
+**Quick Start:**
+```go
+import "github.com/mmabdalla/BOSA/sdk/bosa-sdk-go"
+
+bosa := bosa.NewBOSA(&bosa.Config{
+ KernelURL: "http://localhost:3000",
+ PluginName: "my-plugin",
+ PluginToken: "your-token",
+})
+```
+
+### SDK Features
+
+All SDKs provide consistent APIs for:
+
+- **Database Operations:** Query, insert, update, delete with automatic site scoping
+- **Event System:** Publish and subscribe to events
+- **Real-Time Communication:** WebSocket client for real-time messaging
+- **Configuration Management:** Get, set, delete configuration values
+- **Multi-Tenancy:** Automatic site ID handling in all requests
+- **I18n Support:** Translation and internationalization
+- **Currency Services:** Currency formatting and conversion
+- **Location Services:** Location detection and availability
+
+### SDK Documentation
+
+Each SDK includes comprehensive documentation:
+
+- **Node.js:** `sdk/bosa-sdk-node/README.md`
+- **Python:** `sdk/bosa-sdk-python/README.md`
+- **PHP:** `sdk/bosa-sdk-php/README.md`
+- **Go:** `sdk/bosa-sdk-go/README.md`
+
+For complete API reference, see [SDK API Reference](SDK_API_REFERENCE.md).
+
+### Environment Variables
+
+All SDKs automatically read configuration from environment variables (set by BOSA runtime):
+
+- `BOSA_KERNEL_URL` - BOSA kernel URL (default: `http://localhost:3000`)
+- `PLUGIN_NAME` - Plugin name (required)
+- `BOSA_KERNEL_TOKEN` - Plugin authentication token (required)
+- `BOSA_SITE_ID` - Site ID for multi-tenancy (optional)
+
+These are automatically set when your plugin runs in the BOSA environment.
+
+---
+
+## 3. Plugin Structure
+
+### 3.1 Directory Structure
+
+```
+plugins/my-plugin/
+├── manifest.yaml # Plugin metadata (required)
+├── main.lua # Entry script (required)
+├── migrations/ # Database migrations (optional)
+│ ├── 001_initial.sql
+│ └── 002_update.sql
+└── assets/ # Static assets (optional)
+ ├── js/ # JavaScript files
+ │ └── my-plugin.js
+ ├── css/ # Stylesheets
+ │ └── styles.css
+ └── images/ # Images
+ └── logo.png
+```
+
+**Static Assets:**
+- Static files are served from `/plugins/[plugin-name]/assets/`
+- Example: `assets/js/my-plugin.js` → `/plugins/my-plugin/assets/js/my-plugin.js`
+- Use in your Lua HTML: ``
+
+### 3.2 Documentation and Changelog Pages
+
+BOSA provides automatic documentation and changelog pages for both the main BOSA system and individual apps. Apps located in the `apps/` directory can have their own documentation and changelog pages.
+
+#### App Documentation Structure
+
+For apps in the `apps/` directory, you can provide documentation and changelog files:
+
+```
+apps/my-app/
+├── manifest.yaml # App manifest (required)
+├── docs/ # Documentation directory (optional)
+│ └── DEVELOPER_GUIDE.md # App-specific developer guide
+├── CHANGELOG.md # Changelog in Markdown format (optional)
+└── version.txt # Changelog in version.txt format (optional, fallback)
+```
+
+#### Documentation Pages
+
+**Main BOSA Documentation:**
+- **URL:** `/docs`
+- **Source:** `./docs/DEVELOPER_GUIDE.md`
+- **Description:** Main BOSA developer guide and API reference
+
+**Main BOSA Changelog:**
+- **URL:** `/docs/changelog`
+- **Source:** `./version.txt`
+- **Description:** BOSA version history and changes
+
+**App Documentation:**
+- **URL:** `/docs/[appname]`
+- **Source:** `./apps/[appname]/docs/DEVELOPER_GUIDE.md`
+- **Description:** App-specific developer guide
+- **Example:** `/docs/todo` for the todo app
+
+**App Changelog:**
+- **URL:** `/docs/[appname]/changelog`
+- **Source:** `./apps/[appname]/CHANGELOG.md` or `./apps/[appname]/version.txt`
+- **Description:** App version history and changes
+- **Example:** `/docs/todo/changelog` for the todo app changelog
+
+#### Creating App Documentation
+
+1. **Create Documentation File:**
+ ```bash
+ mkdir -p apps/my-app/docs
+ touch apps/my-app/docs/DEVELOPER_GUIDE.md
+ ```
+
+2. **Write Your Documentation:**
+ - Use Markdown format
+ - Include installation instructions
+ - Document API endpoints
+ - Provide code examples
+ - Add troubleshooting tips
+
+3. **Create Changelog:**
+ ```bash
+ # Option 1: Markdown format (preferred)
+ touch apps/my-app/CHANGELOG.md
+
+ # Option 2: version.txt format (fallback)
+ touch apps/my-app/version.txt
+ ```
+
+#### Changelog Format
+
+**Markdown Format (CHANGELOG.md):**
+```markdown
+# Version 1.0.0
+Date: December 10, 2025
+
+## Changes
+- [FEATURE] Added new task filtering
+- [FIX] Fixed issue with task deletion
+- [IMPROVEMENT] Improved performance
+```
+
+**Version.txt Format:**
+```
+My App Version 1.0.0
+Date: December 10, 2025
+
+=== Latest Changes ===
+- [FEATURE] Added new task filtering
+ - Implemented filter by status
+ - Added filter by date range
+- [FIX] Fixed issue with task deletion
+ - Resolved database constraint error
+ - Added proper error handling
+```
+
+#### Apps Dropdown Navigation
+
+All documentation pages include an "Apps" dropdown in the header navigation that:
+- Lists all available apps from the `apps/` directory
+- Provides quick links to each app's documentation
+- Provides quick links to each app's changelog
+- Highlights the current app when viewing app-specific pages
+
+**Apps are automatically discovered if they have:**
+- A `manifest.yaml` file in `apps/[appname]/manifest.yaml`, OR
+- A `docs/` directory in `apps/[appname]/docs/`
+
+### 3.3 Manifest File (`manifest.yaml`)
+
+#### Required Fields
+
+```yaml
+name: my-plugin # Plugin name (unique, alphanumeric + hyphens)
+version: 1.0.0 # Semantic version (x.y.z)
+description: Plugin description
+author: Your Name
+
+runtime:
+ type: lua # Runtime type: lua, nodejs, php, go
+ entry: main.lua # Entry file (depends on runtime type)
+```
+
+#### Optional Fields
+
+```yaml
+routes: # HTTP routes
+ - path: /todos # Route path (relative to /{plugin-name}/)
+ method: GET # HTTP method (GET, POST, PUT, DELETE, etc.)
+ handler: listTodos # Lua function name
+ - path: /todos/:id # Parameterized routes (:id, :name, etc.)
+ method: GET
+ handler: getTodo
+
+events: # Event subscriptions/publications
+ subscribe: # Events this plugin subscribes to
+ - todo.created
+ - todo.updated
+ publish: # Events this plugin publishes
+ - todo.created
+ - todo.completed
+```
+
+#### Full Manifest Example
+
+```yaml
+name: todo-plugin
+version: 1.0.0
+description: Simple todo management plugin
+author: BOSA Team
+
+runtime:
+ type: lua
+ entry: main.lua
+
+routes:
+ - path: /todos
+ method: GET
+ handler: listTodos
+ - path: /todos
+ method: POST
+ handler: createTodo
+ - path: /todos/:id
+ method: GET
+ handler: getTodo
+ - path: /todos/:id
+ method: PUT
+ handler: updateTodo
+ - path: /todos/:id
+ method: DELETE
+ handler: deleteTodo
+
+events:
+ subscribe:
+ - user.created
+ publish:
+ - todo.created
+ - todo.completed
+```
+
+### 3.4 Main Script (`main.lua`)
+
+#### Required Functions
+
+```lua
+-- init() is called when plugin loads
+function init()
+ -- Initialize plugin here
+ -- Return true on success, false on failure
+ return true
+end
+```
+
+#### Route Handler Functions
+
+```lua
+-- Handler function signature:
+-- function handlerName(request)
+-- return {
+-- status = 200, -- HTTP status code
+-- headers = {}, -- Optional HTTP headers
+-- body = {} -- Response body (JSON object)
+-- }
+-- end
+
+function listTodos(request)
+ -- Query database
+ local todos = bosa.db.query("todos")
+ :orderBy("created_at", "desc")
+ :get()
+
+ return {
+ status = 200,
+ body = { todos = todos }
+ }
+end
+```
+
+---
+
+## 4. Plugin Development
+
+### 4.1 Development Workflow
+
+1. **Create Plugin Structure**
+ - Create directory in `plugins/`
+ - Add `manifest.yaml`
+ - Add `main.lua`
+
+2. **Develop Locally**
+ - Write Lua code
+ - Test with `bosa serve`
+ - Check logs for errors
+
+3. **Install Plugin**
+ - Use `bosa plugin install `
+ - Or manually copy to `plugins/` directory
+
+4. **Test Plugin**
+ - Test routes via HTTP client (curl, Postman)
+ - Test events via event publishing
+ - Test real-time features via WebSocket
+
+5. **Iterate**
+ - Make changes
+ - Restart server (or use hot reload in dev mode)
+ - Test again
+
+### 4.2 Hot Reload (Development Mode)
+
+Enable hot reload for faster development:
+
+```bash
+# Set environment variable
+export BOSA_DEV_MODE=true
+
+# Or in config.yaml
+plugins:
+ hot_reload: true
+
+# Start server
+bosa serve
+
+# Plugin changes auto-reload (no restart needed)
+```
+
+**Note:** Hot reload only reloads Lua scripts, not manifest changes (requires restart).
+
+### 4.3 Plugin Installation Methods
+
+#### Method 1: Local Directory
+
+```bash
+# Install from local directory
+bosa plugin install ./path/to/my-plugin
+```
+
+#### Method 2: Zip File
+
+```bash
+# Install from zip file
+bosa plugin install my-plugin.zip
+```
+
+**Zip File Structure:**
+```
+my-plugin.zip
+└── my-plugin/ # Plugin name directory (optional)
+ ├── manifest.yaml
+ ├── main.lua
+ └── assets/
+```
+
+**Or:**
+```
+my-plugin.zip
+├── manifest.yaml # Can be in root
+├── main.lua
+└── assets/
+```
+
+#### Method 3: Git Repository
+
+```bash
+# Install from git repository
+bosa plugin install https://github.com/user/my-plugin.git
+
+# Or with SSH
+bosa plugin install git@github.com:user/my-plugin.git
+```
+
+**Requirements:**
+- Repository must contain `manifest.yaml`
+- Git must be installed on system
+- Repository must be publicly accessible (or use SSH keys)
+
+#### Method 4: UI Upload (Super Admin)
+
+1. Navigate to `/plugins` page (Super Admin only)
+2. Click "Choose File" and select plugin `.zip` file
+3. Click "Install Plugin"
+4. Plugin is automatically installed and loaded
+
+**Benefits:**
+- No server restart needed
+- Automatic plugin loading
+- Visual feedback during installation
+- Error messages displayed in UI
+
+### 4.4 Static File Serving
+
+#### Directory Structure
+
+```
+plugins/my-plugin/
+└── assets/
+ ├── js/
+ │ └── my-plugin.js
+ ├── css/
+ │ └── styles.css
+ └── images/
+ └── logo.png
+```
+
+#### Accessing Static Files
+
+Static files are automatically served at:
+```
+/plugins/[plugin-name]/assets/[path]
+```
+
+**Examples:**
+- `assets/js/my-plugin.js` → `/plugins/my-plugin/assets/js/my-plugin.js`
+- `assets/css/styles.css` → `/plugins/my-plugin/assets/css/styles.css`
+- `assets/images/logo.png` → `/plugins/my-plugin/assets/images/logo.png`
+
+#### Using in Lua HTML
+
+```lua
+function renderPage(request)
+ return {
+ status = 200,
+ headers = {
+ ["Content-Type"] = "text/html"
+ },
+ body = [[
+
+
+
+
+
+
+ My Plugin
+
+
+
+ ]]
+ }
+end
+```
+
+**Important:**
+- Static files are served automatically (no configuration needed) for Lua plugins
+- For process-based plugins (Node.js, PHP, Go, Python): Static files can be served in two ways:
+ 1. **Automatic serving** (recommended): BOSA kernel automatically serves files from `assets/` directory at `/[plugin-name]/assets/[path]` (smart namespace, no `/plugins/` prefix)
+ 2. **Custom route handling**: Register routes in `manifest.yaml` to handle static assets programmatically (useful for dynamic content, caching headers, etc.)
+
+#### Go Plugins - Static Asset Routes
+
+For Go plugins that need custom handling of static assets (e.g., custom headers, authentication, or dynamic content), register a route in `manifest.yaml`:
+
+```yaml
+routes:
+ - path: /assets/:filepath
+ method: GET
+ handler: StaticAssets
+```
+
+**Smart Namespace Routing:**
+- Routes defined in manifest (e.g., `/assets/:filepath`) are automatically prefixed with plugin name
+- The route `/assets/:filepath` becomes `/[plugin-name]/assets/:filepath` (no `/plugins/` prefix)
+- In your Go handler, the request path will be the original path from the manifest (e.g., `/assets/index.js`)
+- The `:filepath` parameter will capture everything after `/assets/`, including subdirectories and filenames
+- Example: Request to `/todo/assets/js/app.js` matches route `/assets/:filepath` with `filepath` = `js/app.js`
+
+**Alternative**: Static files in `assets/` directory are automatically served at `/[plugin-name]/assets/` without route definition.
+
+**Example Go Handler:**
+```go
+http.HandleFunc("/assets/", func(w http.ResponseWriter, r *http.Request) {
+ // Extract filepath parameter
+ filepath := strings.TrimPrefix(r.URL.Path, "/assets/")
+
+ // Serve file from assets directory
+ http.ServeFile(w, r, filepath.Join(os.Getenv("BOSA_PLUGIN_PATH"), "assets", filepath))
+})
+```
+
+### 4.5 Theme System
+
+BOSA provides a theme system that allows apps to apply consistent visual styling and layouts. Themes are similar to WordPress themes - they provide CSS, JavaScript, images, and templates that can be applied to any BOSA app.
+
+#### Theme Structure
+
+A BOSA theme is a directory containing:
+
+```
+themes/
+└── my-theme/
+ ├── theme.yaml # Theme manifest (required)
+ ├── assets/
+ │ ├── css/
+ │ │ └── main.css
+ │ ├── js/
+ │ │ └── main.js
+ │ └── images/
+ │ └── logo.png
+ └── templates/ # Optional template overrides
+ └── header.html
+```
+
+#### Theme Manifest (theme.yaml)
+
+Every theme must have a `theme.yaml` file in its root directory:
+
+```yaml
+name: my-theme
+version: 1.0.0
+description: A beautiful theme for BOSA apps
+author: Your Name
+parent: base-theme # Optional: inherit from another theme
+
+assets:
+ css:
+ - css/main.css
+ - css/components.css
+ js:
+ - js/main.js
+ images: images # Default: "images"
+ templates: templates # Default: "templates"
+
+config:
+ primary_color: "#007bff"
+ secondary_color: "#6c757d"
+ # Custom configuration options
+```
+
+**Required Fields:**
+- `name`: Unique theme name (must match directory name)
+- `version`: Theme version (semantic versioning recommended)
+
+**Optional Fields:**
+- `description`: Theme description
+- `author`: Theme author name
+- `parent`: Parent theme name for inheritance
+- `assets`: Asset paths configuration
+- `config`: Theme configuration options
+
+#### Theme Inheritance
+
+Themes can inherit from parent themes. When a theme specifies a `parent`, it automatically includes all CSS and JS files from the parent theme, with child theme assets loaded after parent assets.
+
+**Example:**
+
+**Parent theme (base-theme/theme.yaml):**
+```yaml
+name: base-theme
+version: 1.0.0
+assets:
+ css:
+ - css/reset.css
+ - css/base.css
+```
+
+**Child theme (my-theme/theme.yaml):**
+```yaml
+name: my-theme
+version: 1.0.0
+parent: base-theme
+assets:
+ css:
+ - css/custom.css # Loaded after parent CSS
+```
+
+When `my-theme` is applied, CSS files are loaded in this order:
+1. `base-theme/css/reset.css`
+2. `base-theme/css/base.css`
+3. `my-theme/css/custom.css`
+
+#### Applying Themes to Apps
+
+Apps specify their theme in their `manifest.yaml`:
+
+```yaml
+name: my-app
+version: 1.0.0
+theme: my-theme # Apply this theme to the app
+runtime:
+ type: go
+ entry: main.go
+```
+
+#### Theme Asset URLs
+
+Theme assets are served at:
+
+```
+/themes//assets/
+```
+
+**Examples:**
+- `/themes/my-theme/assets/css/main.css`
+- `/themes/my-theme/assets/js/main.js`
+- `/themes/my-theme/assets/images/logo.png`
+
+#### Using Themes in Apps
+
+**Go Apps:**
+
+In your Go app's HTML response, include theme assets:
+
+```go
+func Index(w http.ResponseWriter, r *http.Request) {
+ themeName := "my-theme" // Get from app config or manifest
+
+ html := fmt.Sprintf(`
+
+
+
+
+
+
+
+ My App
+
+
+ `, themeName, themeName)
+
+ w.Header().Set("Content-Type", "text/html")
+ w.Write([]byte(html))
+}
+```
+
+**Lua Apps:**
+
+In Lua apps, use theme asset URLs:
+
+```lua
+function renderPage(request)
+ local themeName = "my-theme"
+
+ return {
+ status = 200,
+ headers = {
+ ["Content-Type"] = "text/html"
+ },
+ body = string.format([[
+
+
+
+
+
+
+ My App
+
+
+ ]], themeName)
+ }
+end
+```
+
+#### Theme API
+
+BOSA provides API endpoints for theme management:
+
+**List All Themes:**
+```http
+GET /api/themes
+Authorization: Bearer
+```
+
+**Get Theme Details:**
+```http
+GET /api/themes/:name
+Authorization: Bearer
+```
+
+**Get Theme Asset URLs:**
+```http
+GET /api/themes/:name/assets
+Authorization: Bearer
+```
+
+**Get Theme HTML Head:**
+```http
+GET /api/themes/html/head?theme=my-theme
+Authorization: Bearer
+```
+
+Returns HTML `` section with theme CSS and JS includes.
+
+#### Best Practices
+
+1. **Use Semantic Versioning**: Use version numbers like `1.0.0`, `1.1.0`, `2.0.0`
+2. **Organize Assets**: Keep CSS, JS, and images in separate directories
+3. **Minimize Dependencies**: Avoid external dependencies when possible
+4. **Mobile-First**: Design themes to be mobile-responsive
+5. **Documentation**: Include a README.md in your theme directory
+6. **Test Inheritance**: Test themes with parent themes to ensure compatibility
+
+For complete theme development documentation, see [THEME_DEVELOPMENT.md](THEME_DEVELOPMENT.md).
+
+---
+
+## 5. BOSA API Reference
+
+### 5.1 Database API (`bosa.db`)
+
+#### Query Builder
+
+```lua
+-- Create query builder
+local query = bosa.db.query("table_name")
+
+-- Chain methods
+query:where("column", "=", value)
+query:where("column", ">", value)
+query:where("column", "<", value)
+query:where("column", "!=", value)
+query:where("column", "LIKE", pattern)
+query:orderBy("column", "asc") -- or "desc"
+query:limit(10)
+query:offset(20)
+
+-- Execute query
+local results = query:get() -- Returns array of rows
+local first = query:first() -- Returns first row or nil
+local count = query:count() -- Returns count
+```
+
+#### CRUD Operations
+
+```lua
+-- Insert
+local id = bosa.db.query("todos"):insert({
+ title = "New Todo",
+ status = "pending",
+ user_id = 1
+})
+-- Returns: inserted ID
+
+-- Update
+bosa.db.query("todos")
+ :where("id", "=", id)
+ :update({
+ status = "completed"
+ })
+-- Returns: number of rows affected
+
+-- Delete
+bosa.db.query("todos")
+ :where("id", "=", id)
+ :delete()
+-- Returns: number of rows affected
+```
+
+#### Example: Complex Query
+
+```lua
+local todos = bosa.db.query("todos")
+ :where("user_id", "=", 1)
+ :where("status", "!=", "deleted")
+ :orderBy("created_at", "desc")
+ :limit(10)
+ :offset(0)
+ :get()
+
+-- todos is an array of rows
+-- Each row is a table with column names as keys
+```
+
+#### SDK Examples
+
+**Node.js SDK:**
+```javascript
+const { BOSA } = require('bosa-sdk-node');
+const bosa = new BOSA({...});
+
+// Query
+const items = await bosa.db.query('items').get();
+const id = await bosa.db.query('items').insert({...});
+await bosa.db.query('items').where('id', '=', id).update({...});
+await bosa.db.query('items').where('id', '=', id).delete();
+```
+
+**PHP SDK:**
+```php
+use Bosa\BOSA;
+$bosa = new BOSA([...]);
+
+// Query
+$items = $bosa->db->query('items')->get();
+$id = $bosa->db->query('items')->insert([...]);
+$bosa->db->query('items')->where('id', '=', $id)->update([...]);
+$bosa->db->query('items')->where('id', '=', $id)->delete();
+```
+
+**Python SDK:**
+```python
+from bosa import BOSA
+bosa = BOSA({...})
+
+# Query
+items = await bosa.db.query('items').get()
+id = await bosa.db.query('items').insert({...})
+await bosa.db.query('items').where('id', '=', id).update({...})
+await bosa.db.query('items').where('id', '=', id).delete()
+```
+
+**Go SDK:**
+```go
+import "github.com/mmabdalla/BOSA/sdk/bosa-sdk-go"
+
+bosa := bosa.NewBOSA(&bosa.Config{
+ KernelURL: "http://localhost:3000",
+ PluginName: "my-plugin",
+ PluginToken: "your-token",
+})
+
+// Query
+items, err := bosa.DB.Query("items").Get()
+if err != nil {
+ log.Fatal(err)
+}
+
+// Insert
+id, err := bosa.DB.Query("items").Insert(map[string]interface{}{
+ "name": "Item 1",
+ "status": "active",
+})
+if err != nil {
+ log.Fatal(err)
+}
+
+// Update
+affected, err := bosa.DB.Query("items").
+ Where("id", "=", id).
+ Update(map[string]interface{}{
+ "status": "completed",
+ })
+if err != nil {
+ log.Fatal(err)
+}
+
+// Delete
+deleted, err := bosa.DB.Query("items").
+ Where("id", "=", id).
+ Delete()
+if err != nil {
+ log.Fatal(err)
+}
+
+// Complex query with conditions
+items, err := bosa.DB.Query("items").
+ Where("status", "=", "active").
+ Where("user_id", "=", 1).
+ OrderBy("created_at", "DESC").
+ Limit(10).
+ Offset(0).
+ Get()
+if err != nil {
+ log.Fatal(err)
+}
+
+// Get first result
+item, err := bosa.DB.Query("items").
+ Where("id", "=", 1).
+ First()
+if err != nil {
+ log.Fatal(err)
+}
+
+// Count
+count, err := bosa.DB.Query("items").
+ Where("status", "=", "pending").
+ Count()
+if err != nil {
+ log.Fatal(err)
+}
+```
+
+### 5.2 Event API (`bosa.events`)
+
+#### Subscribe to Events
+
+```lua
+-- Subscribe to event
+bosa.events.on("event.name", function(event)
+ -- event.data contains event payload
+ bosa.log.info("Event received: " .. event.name)
+ bosa.log.info("Data: " .. json.encode(event.data))
+end)
+```
+
+#### Publish Events
+
+```lua
+-- Publish event
+bosa.events.publish("event.name", {
+ key1 = "value1",
+ key2 = "value2"
+})
+```
+
+#### Example: Event-Driven Todo
+
+```lua
+-- In init() function
+bosa.events.on("todo.created", function(event)
+ bosa.log.info("New todo created: " .. event.data.todo_id)
+ -- Send notification, update cache, etc.
+end)
+
+-- In createTodo handler
+function createTodo(request)
+ local id = bosa.db.query("todos"):insert(request.body)
+
+ -- Publish event
+ bosa.events.publish("todo.created", {
+ todo_id = id,
+ user_id = request.user.id
+ })
+
+ return {
+ status = 201,
+ body = { id = id }
+ }
+end
+```
+
+#### SDK Examples
+
+**Node.js SDK:**
+```javascript
+const { BOSA } = require('bosa-sdk-node');
+const bosa = new BOSA({...});
+
+// Subscribe
+bosa.events.on('user.created', (event) => {
+ console.log('User created:', event.payload);
+});
+
+// Publish
+await bosa.events.publish('todo.created', {
+ todoId: 123,
+ userId: 456,
+});
+```
+
+**PHP SDK:**
+```php
+use Bosa\BOSA;
+$bosa = new BOSA([...]);
+
+// Subscribe
+$bosa->events->on('user.created', function($event) {
+ echo "User created: " . json_encode($event['payload']);
+});
+
+// Publish
+$bosa->events->publish('todo.created', [
+ 'todoId' => 123,
+ 'userId' => 456,
+]);
+```
+
+**Python SDK:**
+```python
+from bosa import BOSA
+bosa = BOSA({...})
+
+# Subscribe
+bosa.events.on('user.created', lambda event: print(f"User created: {event['payload']}"))
+
+# Publish
+await bosa.events.publish('todo.created', {
+ 'todoId': 123,
+ 'userId': 456,
+})
+```
+
+**Go SDK:**
+```go
+import "github.com/mmabdalla/BOSA/sdk/bosa-sdk-go"
+
+bosa := bosa.NewBOSA(&bosa.Config{
+ KernelURL: "http://localhost:3000",
+ PluginName: "my-plugin",
+ PluginToken: "your-token",
+})
+
+// Subscribe
+bosa.Events.On("user.created", func(event bosa.Event) {
+ log.Printf("User created: %v", event.Payload)
+})
+
+// Publish
+err := bosa.Events.Publish("todo.created", map[string]interface{}{
+ "todoId": 123,
+ "userId": 456,
+})
+if err != nil {
+ log.Fatal(err)
+}
+```
+
+### 5.3 Logging API (`bosa.log`)
+
+**⚠️ CRITICAL: Error Logging Requirements**
+
+All plugins **MUST** properly log errors and warnings. The BOSA error notification system automatically monitors logs and notifies super admin users when errors occur. Failure to log errors properly may result in critical issues going unnoticed.
+
+#### Log Levels
+
+```lua
+-- Log levels (ordered by severity)
+bosa.log.info("Informational message") -- General information
+bosa.log.warn("Warning message") -- Warning conditions (triggers notification)
+bosa.log.error("Error message") -- Error conditions (triggers notification)
+```
+
+**Important:**
+- `error` and `warn` level logs **automatically trigger notifications** to super admin users
+- Notifications include a direct link to the log entry in the `/logs` page
+- Duplicate notifications for the same error are prevented automatically
+- Logs are stored in memory buffer and written to log files (in production mode)
+
+#### Error Logging Requirements
+
+**1. Always Log Errors with Context**
+
+```lua
+-- ❌ BAD: Vague error message
+bosa.log.error("Error occurred")
+
+-- ✅ GOOD: Detailed error with context
+bosa.log.error("Database query failed: " .. tostring(err) .. " | Table: todos | User: " .. user_id)
+```
+
+**2. Log Errors Before Returning Error Responses**
+
+```lua
+function createTodo(request)
+ local result, err = pcall(function()
+ return bosa.db.query("todos"):insert(request.body)
+ end)
+
+ if not result then
+ -- ✅ MUST log error before returning
+ bosa.log.error("Failed to create todo: " .. tostring(err) .. " | User: " .. request.user.id)
+ return {
+ status = 500,
+ body = { error = "Internal server error" }
+ }
+ end
+
+ return {
+ status = 201,
+ body = { id = result }
+ }
+end
+```
+
+**3. Use Appropriate Log Levels**
+
+```lua
+-- ✅ Use 'error' for actual errors that need attention
+if database_connection_failed then
+ bosa.log.error("Database connection failed: " .. error_message)
+end
+
+-- ✅ Use 'warn' for recoverable issues or potential problems
+if api_rate_limit_approaching then
+ bosa.log.warn("API rate limit approaching: " .. remaining_requests .. " requests left")
+end
+
+-- ✅ Use 'info' for normal operations (does not trigger notifications)
+bosa.log.info("Todo created successfully: " .. todo_id)
+```
+
+**4. Include Source Information**
+
+The log system automatically includes the plugin name as the source. However, you can add additional context:
+
+```lua
+-- ✅ Include relevant context in error message
+bosa.log.error("Payment processing failed | Order ID: " .. order_id .. " | Amount: " .. amount .. " | Error: " .. error_message)
+```
+
+#### Example: Proper Error Handling
+
+```lua
+function getTodo(request)
+ local id = request.params.id
+
+ -- Validate input
+ if not id then
+ bosa.log.warn("Missing id parameter in getTodo request | Path: " .. request.path)
+ return {
+ status = 400,
+ body = { error = "Missing id parameter" }
+ }
+ end
+
+ -- Try to fetch todo
+ local todo, err = pcall(function()
+ return bosa.db.query("todos")
+ :where("id", "=", id)
+ :first()
+ end)
+
+ if not todo then
+ -- ✅ Log database error
+ bosa.log.error("Database query failed in getTodo: " .. tostring(err) .. " | Todo ID: " .. id)
+ return {
+ status = 500,
+ body = { error = "Internal server error" }
+ }
+ end
+
+ if not todo then
+ bosa.log.warn("Todo not found: " .. id .. " | User: " .. (request.user and request.user.id or "anonymous"))
+ return {
+ status = 404,
+ body = { error = "Todo not found" }
+ }
+ end
+
+ bosa.log.info("Returning todo: " .. id)
+ return {
+ status = 200,
+ body = todo
+ }
+end
+```
+
+#### Error Notification System
+
+**How It Works:**
+
+1. **Automatic Monitoring:** BOSA monitors the log buffer every 2 seconds for new error and warning entries
+2. **Super Admin Notification:** When an error or warning is detected, notifications are automatically created for all super admin users
+3. **Notification Details:**
+ - **Title:** "System Error" or "System Warning" (+ source if available)
+ - **Message:** Truncated error message (max 200 characters)
+ - **Link:** Direct link to the log entry (`/logs?level=error&id=`)
+ - **Metadata:** Includes log_id, log_level, log_source, and timestamp
+4. **Duplicate Prevention:** The system prevents duplicate notifications for the same log entry
+5. **Access:** Super admins receive notifications in the notification bell icon and can click to view the error in the logs page
+
+**Viewing Error Logs:**
+
+- **Via UI:** Navigate to `/logs` page (requires authentication)
+- **Via Notification:** Click the notification link to jump directly to the error entry
+- **Via CLI:** Use `bosa logs ` to view plugin-specific logs
+- **Via API:** `GET /api/logs?level=error` to fetch error logs programmatically
+
+**Best Practices:**
+
+1. **Always log errors immediately** - Don't wait or batch error logs
+2. **Include context** - Add relevant information (user ID, resource ID, operation type)
+3. **Use structured messages** - Format: `"Operation failed | Context: value | Error: message"`
+4. **Don't log sensitive data** - Never log passwords, tokens, or personal information
+5. **Test error logging** - Verify that errors appear in logs and trigger notifications
+
+#### Logging in Multi-Language Plugins
+
+**Node.js (bosa-sdk-node):**
+```javascript
+// SDK provides logging methods
+const { BOSA } = require('bosa-sdk-node');
+const plugin = new BOSA();
+
+// Log errors (automatically captured by BOSA)
+plugin.log.error('Database connection failed', {
+ table: 'todos',
+ userId: req.user.id
+});
+
+plugin.log.warn('API rate limit approaching', {
+ remaining: 10
+});
+
+plugin.log.info('Operation completed successfully');
+```
+
+**PHP (bosa-sdk-php):**
+```php
+// SDK provides logging methods
+use Bosa\BOSA;
+
+$plugin = new BOSA();
+
+// Log errors (automatically captured by BOSA)
+$plugin->log->error('Database connection failed', [
+ 'table' => 'todos',
+ 'userId' => $req->user->id
+]);
+
+$plugin->log->warn('API rate limit approaching', [
+ 'remaining' => 10
+]);
+
+$plugin->log->info('Operation completed successfully');
+```
+
+**Python (bosa-sdk-python):**
+```python
+# SDK provides logging methods
+from bosa import BOSA
+
+plugin = BOSA()
+
+# Log errors (automatically captured by BOSA)
+plugin.log.error('Database connection failed', {
+ 'table': 'todos',
+ 'userId': req.user.id
+})
+
+plugin.log.warn('API rate limit approaching', {
+ 'remaining': 10
+})
+
+plugin.log.info('Operation completed successfully')
+```
+
+**Go (bosa-sdk-go):**
+```go
+// SDK provides logging methods
+import "github.com/bosa/bosa-sdk-go"
+
+plugin := bosa.New()
+
+// Log errors (automatically captured by BOSA)
+plugin.Log().Error("Database connection failed", map[string]interface{}{
+ "table": "todos",
+ "userId": req.User.ID,
+})
+
+plugin.Log().Warn("API rate limit approaching", map[string]interface{}{
+ "remaining": 10,
+})
+
+plugin.Log().Info("Operation completed successfully")
+```
+
+**Note:** All SDK logging methods automatically send logs to the BOSA kernel's log buffer, which triggers the error notification system.
+
+#### Plugin Logging Endpoint (Process-Based Plugins)
+
+For process-based plugins (Node.js, PHP, Python, Go) that need to send logs directly via HTTP (when SDK is not available or for custom implementations), use the plugin logging endpoint:
+
+**Endpoint:** `POST /api/plugins/:name/logs`
+
+**Authentication:** Requires plugin authentication token (`X-BOSA-Plugin-Token` header)
+
+**Request Body:**
+```json
+{
+ "level": "error", // Required: "error", "warn", "info", or "debug"
+ "message": "Error message", // Required: Log message
+ "source": "my-module", // Optional: Source identifier (defaults to "plugin-{name}")
+ "data": { // Optional: Additional context data
+ "userId": 123,
+ "action": "login"
+ }
+}
+```
+
+**Response:**
+```json
+{
+ "success": true,
+ "level": "error"
+}
+```
+
+**Example: Node.js (using HTTP client)**
+```javascript
+const axios = require('axios');
+
+async function logError(message, data = {}) {
+ try {
+ await axios.post(
+ `${process.env.BOSA_KERNEL_URL}/api/plugins/${process.env.PLUGIN_NAME}/logs`,
+ {
+ level: 'error',
+ message: message,
+ source: 'my-module',
+ data: data
+ },
+ {
+ headers: {
+ 'X-BOSA-Plugin-Token': process.env.BOSA_KERNEL_TOKEN,
+ 'X-BOSA-Plugin-Name': process.env.PLUGIN_NAME,
+ 'Content-Type': 'application/json'
+ }
+ }
+ );
+ } catch (error) {
+ // Fallback to console if API call fails
+ console.error('Failed to send log to BOSA kernel:', error.message);
+ console.error('Original error:', message, data);
+ }
+}
+
+// Usage
+await logError('Database connection failed', {
+ table: 'todos',
+ userId: 123
+});
+```
+
+**Example: PHP (using cURL)**
+```php
+function logError($message, $data = []) {
+ $kernelURL = $_ENV['BOSA_KERNEL_URL'] ?? 'http://localhost:3000';
+ $pluginName = $_ENV['PLUGIN_NAME'] ?? '';
+ $pluginToken = $_ENV['BOSA_KERNEL_TOKEN'] ?? '';
+
+ $ch = curl_init("{$kernelURL}/api/plugins/{$pluginName}/logs");
+ curl_setopt_array($ch, [
+ CURLOPT_POST => true,
+ CURLOPT_RETURNTRANSFER => true,
+ CURLOPT_HTTPHEADER => [
+ 'Content-Type: application/json',
+ "X-BOSA-Plugin-Token: {$pluginToken}",
+ "X-BOSA-Plugin-Name: {$pluginName}",
+ ],
+ CURLOPT_POSTFIELDS => json_encode([
+ 'level' => 'error',
+ 'message' => $message,
+ 'source' => 'my-module',
+ 'data' => $data
+ ])
+ ]);
+
+ $response = curl_exec($ch);
+ $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+ curl_close($ch);
+
+ if ($httpCode !== 200) {
+ // Fallback to error_log if API call fails
+ error_log("Failed to send log to BOSA kernel (HTTP {$httpCode}): {$message}");
+ error_log("Data: " . json_encode($data));
+ }
+}
+
+// Usage
+logError('Database connection failed', [
+ 'table' => 'todos',
+ 'userId' => 123
+]);
+```
+
+**Example: Python (using requests)**
+```python
+import os
+import requests
+import json
+
+def log_error(message, data=None):
+ kernel_url = os.getenv('BOSA_KERNEL_URL', 'http://localhost:3000')
+ plugin_name = os.getenv('PLUGIN_NAME', '')
+ plugin_token = os.getenv('BOSA_KERNEL_TOKEN', '')
+
+ try:
+ response = requests.post(
+ f'{kernel_url}/api/plugins/{plugin_name}/logs',
+ json={
+ 'level': 'error',
+ 'message': message,
+ 'source': 'my-module',
+ 'data': data or {}
+ },
+ headers={
+ 'Content-Type': 'application/json',
+ 'X-BOSA-Plugin-Token': plugin_token,
+ 'X-BOSA-Plugin-Name': plugin_name
+ },
+ timeout=5
+ )
+ response.raise_for_status()
+ except Exception as e:
+ # Fallback to print if API call fails
+ print(f'Failed to send log to BOSA kernel: {e}')
+ print(f'Original error: {message} | Data: {data}')
+
+# Usage
+log_error('Database connection failed', {
+ 'table': 'todos',
+ 'userId': 123
+})
+```
+
+**Important Notes:**
+- The endpoint requires plugin authentication (plugin token and name)
+- Logs are automatically added to BOSA's log buffer
+- Error and warning level logs trigger super admin notifications
+- Always include fallback logging (console/print/error_log) in case the API call fails
+- The endpoint is protected by location restriction middleware (if enabled)
+- Use SDK logging methods when available (they handle the API calls automatically)
+
+### 5.4 Configuration API (`bosa.config`)
+
+#### Get Configuration Value
+
+```lua
+-- Get a configuration value for this plugin
+local apiKey = bosa.config.get("my-plugin", "api_key")
+-- Returns: value or nil if not set
+```
+
+#### Set Configuration Value
+
+```lua
+-- Set a configuration value
+bosa.config.set("my-plugin", "api_key", "secret-key-123")
+-- Saves to database (persistent across restarts)
+```
+
+#### Delete Configuration Value
+
+```lua
+-- Delete a configuration value
+bosa.config.delete("my-plugin", "api_key")
+```
+
+#### Get All Configuration
+
+```lua
+-- Get all configuration for this plugin
+local config = bosa.config.getAll("my-plugin")
+-- Returns: table with all config keys and values
+-- Example: { api_key = "secret", timeout = "30" }
+```
+
+#### Example: Plugin Configuration
+
+```lua
+function init()
+ -- Load configuration
+ local apiKey = bosa.config.get("my-plugin", "api_key")
+ local timeout = bosa.config.get("my-plugin", "timeout") or "30"
+
+ if not apiKey then
+ bosa.log.warn("API key not configured. Please set it in plugin settings.")
+ end
+
+ return true
+end
+
+function updateSettings(request)
+ -- Update configuration from API
+ bosa.config.set("my-plugin", "api_key", request.body.api_key)
+ bosa.config.set("my-plugin", "timeout", request.body.timeout)
+
+ return {
+ status = 200,
+ body = { message = "Settings updated" }
+ }
+end
+```
+
+**Configuration Storage:**
+- Stored in `plugin_config` table in database
+- Isolated per plugin (plugin_name + config_key)
+- Persistent across server restarts
+- Accessible via REST API: `GET /api/plugins/:name/config`
+
+#### SDK Examples
+
+**Node.js SDK:**
+```javascript
+const { BOSA } = require('bosa-sdk-node');
+const bosa = new BOSA({...});
+
+// Get config
+const value = await bosa.config.get('setting_key');
+
+// Set config
+await bosa.config.set('setting_key', 'value');
+
+// Delete config
+await bosa.config.delete('setting_key');
+
+// Get all config
+const allConfig = await bosa.config.getAll();
+```
+
+**PHP SDK:**
+```php
+use Bosa\BOSA;
+$bosa = new BOSA([...]);
+
+// Get config
+$value = $bosa->config->get('setting_key');
+
+// Set config
+$bosa->config->set('setting_key', 'value');
+
+// Delete config
+$bosa->config->delete('setting_key');
+
+// Get all config
+$allConfig = $bosa->config->all();
+```
+
+**Python SDK:**
+```python
+from bosa import BOSA
+bosa = BOSA({...})
+
+# Get config
+value = await bosa.config.get('setting_key')
+
+# Set config
+await bosa.config.set('setting_key', 'value')
+
+# Delete config
+await bosa.config.delete('setting_key')
+
+# Get all config
+all_config = await bosa.config.get_all()
+```
+
+**Go SDK:**
+```go
+import "github.com/mmabdalla/BOSA/sdk/bosa-sdk-go"
+
+bosa := bosa.NewBOSA(&bosa.Config{
+ KernelURL: "http://localhost:3000",
+ PluginName: "my-plugin",
+ PluginToken: "your-token",
+})
+
+// Get config
+value, err := bosa.Config.Get("setting_key")
+if err != nil {
+ log.Fatal(err)
+}
+
+// Set config
+err = bosa.Config.Set("setting_key", "value")
+if err != nil {
+ log.Fatal(err)
+}
+
+// Delete config
+err = bosa.Config.Delete("setting_key")
+if err != nil {
+ log.Fatal(err)
+}
+
+// Get all config
+allConfig, err := bosa.Config.GetAll()
+if err != nil {
+ log.Fatal(err)
+}
+
+// Clear cache
+bosa.Config.ClearCache()
+```
+
+### 5.5 Real-Time API (`bosa.realtime`)
+
+#### Broadcast to WebSocket Clients
+
+```lua
+-- Broadcast event to all connected clients
+bosa.realtime.broadcast("channel.name", {
+ key1 = "value1",
+ key2 = "value2"
+})
+```
+
+#### Example: Real-Time Todo Updates
+
+```lua
+function updateTodo(request)
+ local id = request.params.id
+
+ -- Update database
+ bosa.db.query("todos")
+ :where("id", "=", id)
+ :update(request.body)
+
+ -- Get updated todo
+ local todo = bosa.db.query("todos")
+ :where("id", "=", id)
+ :first()
+
+ -- Broadcast to WebSocket clients
+ bosa.realtime.broadcast("todo.updated", {
+ todo_id = id,
+ todo = todo
+ })
+
+ return {
+ status = 200,
+ body = todo
+ }
+end
+```
+
+#### SDK Examples
+
+**Node.js SDK:**
+```javascript
+const { BOSA } = require('bosa-sdk-node');
+const bosa = new BOSA({...});
+
+// Connect to WebSocket
+await bosa.realtime.connect();
+
+// Broadcast
+await bosa.realtime.broadcast('channel', { message: 'Hello' });
+
+// Send to user
+await bosa.realtime.sendToUser('user123', { message: 'Hello' });
+
+// Subscribe
+bosa.realtime.on('channel', (message) => {
+ console.log('Received:', message);
+});
+
+// Disconnect
+await bosa.realtime.disconnect();
+```
+
+**PHP SDK:**
+```php
+use Bosa\BOSA;
+$bosa = new BOSA([...]);
+
+// Connect (placeholder - WebSocket support pending)
+$bosa->realtime->connect();
+
+// Broadcast
+$bosa->realtime->broadcast('channel', ['message' => 'Hello']);
+
+// Send to user
+$bosa->realtime->sendToUser('user123', ['message' => 'Hello']);
+
+// Subscribe (local handler)
+$bosa->realtime->on('channel', function($message) {
+ echo "Received: " . json_encode($message);
+});
+```
+
+**Python SDK:**
+```python
+from bosa import BOSA
+bosa = BOSA({...})
+
+# Connect to WebSocket
+await bosa.realtime.connect()
+
+# Broadcast
+await bosa.realtime.broadcast('channel', {'message': 'Hello'})
+
+# Send to user
+await bosa.realtime.send_to_user('user123', {'message': 'Hello'})
+
+# Subscribe
+bosa.realtime.on('channel', lambda message: print(f"Received: {message}"))
+
+# Disconnect
+await bosa.realtime.disconnect()
+```
+
+**Go SDK:**
+```go
+import "github.com/mmabdalla/BOSA/sdk/bosa-sdk-go"
+
+bosa := bosa.NewBOSA(&bosa.Config{
+ KernelURL: "http://localhost:3000",
+ PluginName: "my-plugin",
+ PluginToken: "your-token",
+})
+
+// Connect (placeholder - WebSocket support pending)
+err := bosa.Realtime.Connect()
+if err != nil {
+ log.Fatal(err)
+}
+
+// Broadcast
+err = bosa.Realtime.Broadcast("channel", map[string]interface{}{
+ "message": "Hello",
+})
+if err != nil {
+ log.Fatal(err)
+}
+
+// Send to user
+err = bosa.Realtime.SendToUser("user123", map[string]interface{}{
+ "message": "Hello",
+})
+if err != nil {
+ log.Fatal(err)
+}
+
+// Subscribe (local handler)
+bosa.Realtime.On("channel", func(message bosa.RealtimeMessage) {
+ log.Printf("Received: %v", message.Message)
+})
+
+// Check connection status
+connected := bosa.Realtime.IsConnected()
+
+// Disconnect
+err = bosa.Realtime.Disconnect()
+if err != nil {
+ log.Fatal(err)
+}
+```
+
+### 5.6 I18n Translation API (`bosa.i18n`)
+
+BOSA provides built-in internationalization (i18n) support for translating your app content into multiple languages. The SDKs provide a simple API for retrieving translations with automatic language detection, parameter interpolation, and caching.
+
+#### Basic Translation
+
+**Node.js (bosa-sdk-node):**
+```javascript
+const bosa = require('bosa-sdk-node');
+
+const plugin = new bosa.BOSA({
+ pluginName: 'my-plugin',
+ pluginToken: process.env.BOSA_KERNEL_TOKEN
+});
+
+// Translate a key
+const greeting = await plugin.i18n.t('ui.greeting');
+// Returns: "Hello" (or translated value based on current language)
+
+// With parameters
+const message = await plugin.i18n.t('ui.welcome', { name: 'John' });
+// Translation: "Welcome {name}" → "Welcome John"
+```
+
+**PHP (bosa-sdk-php):**
+```php
+use Bosa\BOSA;
+
+$plugin = new BOSA([
+ 'pluginName' => 'my-plugin',
+ 'pluginToken' => $_ENV['BOSA_KERNEL_TOKEN']
+]);
+
+// Translate a key
+$greeting = $plugin->i18n->t('ui.greeting');
+
+// With parameters
+$message = $plugin->i18n->t('ui.welcome', ['name' => 'John']);
+```
+
+**Python (bosa-sdk-python):**
+```python
+from bosa import BOSA
+
+plugin = BOSA({
+ 'pluginName': 'my-plugin',
+ 'pluginToken': os.getenv('BOSA_KERNEL_TOKEN')
+})
+
+# Translate a key (async)
+greeting = await plugin.i18n.t('ui.greeting')
+
+# With parameters
+message = await plugin.i18n.t('ui.welcome', {'name': 'John'})
+```
+
+**Go (bosa-sdk-go):**
+```go
+import "github.com/mmabdalla/BOSA/sdk/bosa-sdk-go"
+
+plugin := bosa.NewBOSA(&bosa.Config{
+ PluginName: "my-plugin",
+ PluginToken: os.Getenv("BOSA_KERNEL_TOKEN"),
+})
+
+// Translate a key
+greeting, err := plugin.I18n().T("ui.greeting", nil)
+
+// With parameters
+message, err := plugin.I18n().T("ui.welcome", map[string]interface{}{
+ "name": "John",
+})
+```
+
+**Lua Runtime:**
+```lua
+-- Translate a key
+local greeting = bosa.i18n.t("ui.greeting")
+-- Returns: "Hello" (or translated value based on current language)
+
+-- With parameters
+local message = bosa.i18n.t("ui.welcome", { name = "John" })
+-- Translation: "Welcome {name}" → "Welcome John"
+
+-- Get current language
+local lang = bosa.i18n.getCurrentLanguage()
+-- Returns: "en" (or current language code)
+
+-- Set language (for this request)
+bosa.i18n.setLanguage("es")
+
+-- List available languages
+local languages = bosa.i18n.listLanguages()
+for i, lang in ipairs(languages) do
+ print(string.format("%s (%s): %s", lang.name, lang.code, lang.native_name))
+end
+
+-- Get app's default language
+local defaultLang = bosa.i18n.getDefaultLanguage()
+print("Default language: " .. defaultLang)
+```
+
+#### Language Management
+
+**Set Current Language:**
+```javascript
+// Node.js
+plugin.i18n.setLanguage('es');
+
+// PHP
+$plugin->i18n->setLanguage('es');
+
+// Python
+plugin.i18n.set_language('es')
+
+// Go
+plugin.I18n().SetLanguage("es")
+```
+
+**Detect Language from Request:**
+```javascript
+// Node.js - detect from Accept-Language header
+const language = plugin.i18n.detectLanguage(req.headers['accept-language']);
+plugin.i18n.setLanguage(language);
+```
+
+**PHP:**
+```php
+$language = $plugin->i18n->detectLanguage($_SERVER['HTTP_ACCEPT_LANGUAGE']);
+$plugin->i18n->setLanguage($language);
+```
+
+**Python:**
+```python
+language = plugin.i18n.detect_language(request.headers.get('Accept-Language'))
+plugin.i18n.set_language(language)
+```
+
+**Go:**
+```go
+language := plugin.I18n().DetectLanguage(r.Header.Get("Accept-Language"))
+plugin.I18n().SetLanguage(language)
+```
+
+#### Parameter Interpolation
+
+Translations support parameter interpolation using `{key}` or `{{key}}` syntax:
+
+```javascript
+// Translation stored: "Hello {name}, you have {count} messages"
+const message = await plugin.i18n.t('ui.message', {
+ name: 'John',
+ count: 5
+});
+// Returns: "Hello John, you have 5 messages"
+```
+
+#### Caching
+
+Translations are automatically cached for performance. Cache is cleared when language changes:
+
+```javascript
+// Clear cache manually
+plugin.i18n.clearCache();
+
+// Preload translations (useful for bulk loading)
+await plugin.i18n.preload([
+ 'ui.greeting',
+ 'ui.button.save',
+ 'ui.button.cancel',
+ 'ui.message.welcome'
+]);
+```
+
+#### Translation Key Format
+
+Translation keys must follow the `namespace.key` format:
+- ✅ Valid: `ui.button.save`, `messages.welcome`, `errors.validation.required`
+- ❌ Invalid: `button-save`, `welcome`, `button save`
+
+#### Managing Translations
+
+Translations are managed via the BOSA admin panel or API:
+
+**API Endpoints:**
+- `POST /api/apps/:name/i18n/translations` - Create translation
+- `PUT /api/apps/:name/i18n/translations/:key` - Update translation
+- `DELETE /api/apps/:name/i18n/translations/:key` - Delete translation
+- `GET /api/apps/:name/i18n/translations` - List translations (with filtering)
+
+**Example - Creating Translations via API:**
+```bash
+curl -X POST http://localhost:3000/api/apps/my-plugin/i18n/translations \
+ -H "Authorization: Bearer YOUR_TOKEN" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "key": "ui.greeting",
+ "language_code": "en",
+ "value": "Hello",
+ "namespace": "ui"
+ }'
+```
+
+#### Complete Example
+
+**Node.js Plugin with i18n:**
+```javascript
+const bosa = require('bosa-sdk-node');
+const express = require('express');
+
+const plugin = new bosa.BOSA({
+ pluginName: 'my-plugin',
+ pluginToken: process.env.BOSA_KERNEL_TOKEN
+});
+
+const app = express();
+
+app.get('/greeting', async (req, res) => {
+ // Detect language from request
+ const language = plugin.i18n.detectLanguage(req.headers['accept-language']);
+ plugin.i18n.setLanguage(language);
+
+ // Get translated greeting
+ const greeting = await plugin.i18n.t('ui.greeting');
+ const welcome = await plugin.i18n.t('ui.welcome', {
+ name: req.user.name
+ });
+
+ res.json({ greeting, welcome });
+});
+```
+
+**Note:** Translations are automatically cached for 5 minutes by default. The cache is cleared when the language changes to ensure fresh translations.
+
+#### Right-to-Left (RTL) Layout Support
+
+BOSA provides automatic Right-to-Left (RTL) layout support for languages that read from right to left, such as Arabic, Hebrew, Urdu, and Persian. The RTL support is automatically applied based on the language's RTL flag in the system.
+
+**How It Works:**
+
+1. **Automatic Detection:** When a user selects an RTL language (or the browser detects one), BOSA automatically:
+ - Sets the HTML `dir="rtl"` attribute
+ - Applies RTL-aware CSS classes
+ - Mirrors layout elements (navigation, buttons, forms, etc.)
+
+2. **Language RTL Flag:** Each language in the system has an `rtl` boolean flag that indicates whether it's a right-to-left language. This flag is stored in the `languages` database table.
+
+3. **Frontend Support:** All BOSA templates include:
+ - `rtl-support.js` - JavaScript utility for RTL detection and application
+ - `rtl-styles.css` - Comprehensive RTL-aware CSS styles
+
+**Checking RTL Status in SDKs:**
+
+**Node.js:**
+```javascript
+// Get language information including RTL flag
+const langInfo = await plugin.i18n.getLanguageInfo('ar');
+console.log(langInfo.rtl); // true for Arabic
+
+// Check if current language is RTL
+const isRTL = await plugin.i18n.isRTL();
+console.log(isRTL); // true or false
+```
+
+**PHP:**
+```php
+// Language info is available in the API response
+$languages = $plugin->client->get('/api/i18n/languages');
+foreach ($languages as $lang) {
+ if ($lang['code'] === 'ar') {
+ echo $lang['rtl']; // true for Arabic
+ }
+}
+```
+
+**Python:**
+```python
+# Language info is available in the API response
+languages = await plugin.client.get('/api/i18n/languages')
+for lang in languages:
+ if lang['code'] == 'ar':
+ print(lang['rtl']) # True for Arabic
+```
+
+**Go:**
+```go
+// Language info is available in the API response
+languages, _ := plugin.Client().Get("/api/i18n/languages")
+for _, lang := range languages {
+ if lang["code"] == "ar" {
+ fmt.Println(lang["rtl"]) // true for Arabic
+ }
+}
+```
+
+**Lua:**
+```lua
+-- Get language information
+local languages = bosa.i18n.listLanguages()
+for i, lang in ipairs(languages) do
+ if lang.code == "ar" then
+ print(lang.rtl) -- true for Arabic
+ end
+end
+```
+
+**Frontend RTL Support:**
+
+For frontend applications, BOSA provides a global `rtlSupport` object:
+
+```javascript
+// Check if current language is RTL
+if (window.rtlSupport && window.rtlSupport.isRTLLanguage()) {
+ console.log('Current language is RTL');
+}
+
+// Get current language code
+const currentLang = window.rtlSupport.getCurrentLanguage();
+
+// Set language (will automatically apply RTL if needed)
+await window.rtlSupport.setLanguage('ar');
+
+// Listen for RTL changes
+document.addEventListener('rtl-changed', (event) => {
+ console.log('RTL changed:', event.detail.isRTL);
+ console.log('Language:', event.detail.language);
+});
+```
+
+**RTL-Aware CSS Classes:**
+
+BOSA's RTL styles automatically handle:
+- **Flexbox layouts:** Row directions are reversed
+- **Text alignment:** Left/right are swapped
+- **Spacing:** Margins and padding are mirrored
+- **Positioning:** Left/right positioning is swapped
+- **Forms:** Input fields align to the right
+- **Tables:** Table cells align to the right
+- **Navigation:** Menu items flow from right to left
+
+**Best Practices:**
+
+1. **Use Logical Properties:** When writing custom CSS, prefer logical properties (`margin-inline-start` instead of `margin-left`) for better RTL support.
+
+2. **Test with RTL Languages:** Always test your app with Arabic or Hebrew to ensure proper layout.
+
+3. **Icons and Images:** Some icons may need mirroring in RTL. Use CSS transforms or provide RTL-specific versions.
+
+4. **Numbers and Code:** Numbers and code blocks should remain LTR even in RTL layouts. BOSA handles this automatically.
+
+5. **API Responses:** The language API (`/api/i18n/languages`) includes the `rtl` flag for each language, allowing you to conditionally adjust your UI.
+
+**Example - Conditional UI Based on RTL:**
+
+```javascript
+// In your frontend code
+const langInfo = await fetch('/api/i18n/languages').then(r => r.json());
+const currentLang = langInfo.find(l => l.code === 'ar');
+
+if (currentLang && currentLang.rtl) {
+ // Apply RTL-specific styling or logic
+ document.body.classList.add('rtl-mode');
+}
+```
+
+#### Automated Translation Service
+
+BOSA provides an **automated translation service** that uses AI-powered translation providers (Google Translate, DeepL, OpenAI) to generate translation proposals. This service helps you quickly translate your app content into multiple languages with a review workflow.
+
+**Features:**
+- **Multiple Providers:** Google Translate, DeepL, OpenAI
+- **Quality Scoring:** Automatic quality assessment for each translation
+- **Review Workflow:** Proposals can be approved or rejected before being applied
+- **Cost Tracking:** Monitor translation costs per provider and app
+- **Auto-Approve Option:** Optionally auto-approve high-quality translations
+
+**Prerequisites:**
+- Translation provider API key (see [Google Translate API Instructions](Google_Translate_API_Instructions.md))
+- Source translations must exist in your app's default language
+- Target languages must be enabled for your app
+
+**API Endpoints:**
+
+**Request Translation:**
+```bash
+POST /api/apps/:name/i18n/translate
+Authorization: Bearer YOUR_TOKEN
+Content-Type: application/json
+
+{
+ "keys": ["ui.greeting", "ui.button.save"],
+ "source_language": "en",
+ "target_languages": ["es", "fr"],
+ "provider": "google",
+ "auto_approve": false
+}
+```
+
+**Response:**
+```json
+{
+ "success": true,
+ "app_name": "my-plugin",
+ "proposals": [
+ {
+ "id": 1,
+ "key": "ui.greeting",
+ "source_language_code": "en",
+ "target_language_code": "es",
+ "source_value": "Hello",
+ "proposed_value": "Hola",
+ "status": "pending",
+ "provider": "google",
+ "quality_score": 0.95,
+ "cost_usd": 0.0001
+ }
+ ],
+ "count": 2
+}
+```
+
+**List Translation Proposals:**
+```bash
+GET /api/apps/:name/i18n/proposals?status=pending&lang=es
+Authorization: Bearer YOUR_TOKEN
+```
+
+**Approve Proposal:**
+```bash
+POST /api/apps/:name/i18n/proposals/:id/approve
+Authorization: Bearer YOUR_TOKEN
+Content-Type: application/json
+
+{
+ "notes": "Looks good!"
+}
+```
+
+**Reject Proposal:**
+```bash
+POST /api/apps/:name/i18n/proposals/:id/reject
+Authorization: Bearer YOUR_TOKEN
+Content-Type: application/json
+
+{
+ "notes": "Translation quality is poor"
+}
+```
+
+**Get Translation Costs:**
+```bash
+GET /api/apps/:name/i18n/costs?start_date=2025-12-01&end_date=2025-12-31
+Authorization: Bearer YOUR_TOKEN
+```
+
+**Response:**
+```json
+{
+ "app_name": "my-plugin",
+ "costs": [
+ {
+ "id": 1,
+ "provider": "google",
+ "date": "2025-12-03",
+ "character_count": 5000,
+ "request_count": 10,
+ "cost_usd": 0.10
+ }
+ ],
+ "count": 1
+}
+```
+
+**Using the UI:**
+
+1. Navigate to **Plugins** page (Super Admin only)
+2. Click **"Translations"** button on any enabled plugin
+3. Click **"Request New Translation"**
+4. Enter translation keys (comma-separated) and select target languages
+5. Choose translation provider (Google Translate, DeepL, or OpenAI)
+6. Optionally enable **"Auto-Approve"** for high-quality translations
+7. Click **"Request Translation"**
+8. Review proposals in the proposals list
+9. Approve or reject proposals as needed
+
+**Translation Providers:**
+
+**Google Translate:**
+- **API Key:** Set `GOOGLE_TRANSLATE_API_KEY` environment variable
+- **Cost:** $20 per million characters (500K free tier/month)
+- **Quality:** Good for general translations
+- **Setup:** See [Google Translate API Instructions](Google_Translate_API_Instructions.md)
+
+**DeepL:**
+- **API Key:** Set `DEEPL_API_KEY` environment variable
+- **Cost:** €4.99/month for 500K characters (free tier available)
+- **Quality:** Excellent for European languages
+- **Setup:** Sign up at https://www.deepl.com/pro-api
+
+**OpenAI:**
+- **API Key:** Set `OPENAI_API_KEY` environment variable
+- **Cost:** Varies by model (GPT-3.5-turbo recommended)
+- **Quality:** Excellent for context-aware translations
+- **Setup:** Get API key from https://platform.openai.com/api-keys
+
+**Quality Scoring:**
+
+Each translation proposal includes a quality score (0.0 to 1.0) based on:
+- Length similarity between source and translation
+- Placeholder preservation (`{name}` → `{name}`)
+- Character ratio analysis
+
+**Best Practices:**
+
+1. **Review Before Approving:** Always review proposals, especially for important UI text
+2. **Use Auto-Approve Sparingly:** Only enable for non-critical content or high-confidence translations
+3. **Monitor Costs:** Check translation costs regularly to stay within budget
+4. **Choose Right Provider:**
+ - Google Translate: Best for general use, good free tier
+ - DeepL: Best for European languages, excellent quality
+ - OpenAI: Best for context-aware translations, higher cost
+5. **Batch Requests:** Request multiple keys at once for efficiency
+6. **Source Language:** Ensure source translations are accurate and complete
+
+**Example - Requesting Translations via API:**
+
+```bash
+# Request translations for multiple keys
+curl -X POST http://localhost:3000/api/apps/my-plugin/i18n/translate \
+ -H "Authorization: Bearer YOUR_TOKEN" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "keys": ["ui.greeting", "ui.button.save", "ui.button.cancel"],
+ "source_language": "en",
+ "target_languages": ["es", "fr", "de"],
+ "provider": "google"
+ }'
+
+# List pending proposals
+curl http://localhost:3000/api/apps/my-plugin/i18n/proposals?status=pending \
+ -H "Authorization: Bearer YOUR_TOKEN"
+
+# Approve a proposal
+curl -X POST http://localhost:3000/api/apps/my-plugin/i18n/proposals/1/approve \
+ -H "Authorization: Bearer YOUR_TOKEN" \
+ -H "Content-Type: application/json" \
+ -d '{"notes": "Approved"}'
+
+# Check translation costs
+curl http://localhost:3000/api/apps/my-plugin/i18n/costs \
+ -H "Authorization: Bearer YOUR_TOKEN"
+```
+
+**Note:** The automated translation service requires API keys to be configured. Translations are created as proposals that must be reviewed and approved before being applied to your app. This ensures quality control and allows you to review translations before they go live.
+
+### 5.7 Messaging API (REST)
+
+**BOSA provides a comprehensive messaging system** that allows apps to enable users to communicate with each other in private conversations, groups, and channels. This is a **core BOSA infrastructure service** accessible via REST API endpoints.
+
+**Base URL:** `http://localhost:3000` (or your BOSA server URL)
+
+**Authentication:** All endpoints require JWT authentication (same as other BOSA APIs)
+
+#### Overview
+
+The messaging system supports:
+- **Private conversations** (1-on-1 messaging)
+- **Group conversations** (private groups)
+- **Public channels** (public messaging spaces)
+- **Real-time delivery** via WebSocket
+- **Message types:** text, image, file, voice, location
+- **Features:** replies, reactions, read receipts, search
+
+#### API Endpoints
+
+**Conversations:**
+- `GET /api/messaging/conversations` - List user's conversations
+- `POST /api/messaging/conversations` - Create conversation
+- `GET /api/messaging/conversations/:id` - Get conversation details
+
+**Messages:**
+- `GET /api/messaging/conversations/:id/messages` - List messages (with pagination)
+- `POST /api/messaging/conversations/:id/messages` - Send message
+- `GET /api/messaging/messages/:id` - Get message details
+- `PUT /api/messaging/messages/:id` - Edit message
+- `DELETE /api/messaging/messages/:id` - Delete message
+- `POST /api/messaging/messages/:id/read` - Mark message as read
+
+**Participants:**
+- `POST /api/messaging/conversations/:id/participants` - Add participant
+- `DELETE /api/messaging/conversations/:id/participants/:user_id` - Remove participant
+
+**Reactions:**
+- `POST /api/messaging/messages/:id/reactions` - Add emoji reaction
+- `DELETE /api/messaging/messages/:id/reactions/:emoji` - Remove reaction
+
+**Search:**
+- `GET /api/messaging/search?q=query` - Search messages across conversations
+
+#### Usage Examples
+
+**Example 1: Create Private Conversation and Send Message (Lua)**
+
+```lua
+function sendMessageToUser(request)
+ local targetUserId = request.body.user_id
+ local messageContent = request.body.message
+
+ -- Step 1: Create or get private conversation
+ local convResponse = http.post("http://localhost:3000/api/messaging/conversations", {
+ headers = {
+ ["Authorization"] = "Bearer " .. request.user.token,
+ ["Content-Type"] = "application/json"
+ },
+ body = json.encode({
+ type = "private",
+ user_ids = {targetUserId}
+ })
+ })
+
+ local conversation = json.decode(convResponse.body)
+
+ -- Step 2: Send message
+ local msgResponse = http.post("http://localhost:3000/api/messaging/conversations/" .. conversation.id .. "/messages", {
+ headers = {
+ ["Authorization"] = "Bearer " .. request.user.token,
+ ["Content-Type"] = "application/json"
+ },
+ body = json.encode({
+ content = messageContent,
+ message_type = "text"
+ })
+ })
+
+ local message = json.decode(msgResponse.body)
+
+ return {
+ status = 200,
+ body = { message = message }
+ }
+end
+```
+
+**Example 2: Create Group Conversation (Node.js)**
+
+```javascript
+const axios = require('axios');
+
+async function createGroupChat(req) {
+ const { name, description, user_ids } = req.body;
+
+ // Create group conversation
+ const convResponse = await axios.post('http://localhost:3000/api/messaging/conversations', {
+ type: 'group',
+ name: name,
+ description: description,
+ user_ids: user_ids
+ }, {
+ headers: {
+ 'Authorization': `Bearer ${req.user.token}`,
+ 'Content-Type': 'application/json'
+ }
+ });
+
+ return {
+ status: 201,
+ body: { conversation: convResponse.data }
+ };
+}
+```
+
+**Example 3: List Messages with Pagination (Lua)**
+
+```lua
+function getConversationMessages(request)
+ local conversationId = request.params.id
+ local limit = request.query.limit or 50
+ local offset = request.query.offset or 0
+
+ local response = http.get("http://localhost:3000/api/messaging/conversations/" .. conversationId .. "/messages?limit=" .. limit .. "&offset=" .. offset, {
+ headers = {
+ ["Authorization"] = "Bearer " .. request.user.token
+ }
+ })
+
+ local messages = json.decode(response.body)
+
+ return {
+ status = 200,
+ body = { messages = messages }
+ }
+end
+```
+
+**Example 4: Send Message with Reply (Lua)**
+
+```lua
+function replyToMessage(request)
+ local conversationId = request.params.conversation_id
+ local replyToId = request.body.reply_to_id
+ local content = request.body.content
+
+ local response = http.post("http://localhost:3000/api/messaging/conversations/" .. conversationId .. "/messages", {
+ headers = {
+ ["Authorization"] = "Bearer " .. request.user.token,
+ ["Content-Type"] = "application/json"
+ },
+ body = json.encode({
+ content = content,
+ message_type = "text",
+ reply_to_id = replyToId
+ })
+ })
+
+ local message = json.decode(response.body)
+
+ return {
+ status = 201,
+ body = { message = message }
+ }
+end
+```
+
+**Example 5: Add Reaction to Message (Lua)**
+
+```lua
+function addReaction(request)
+ local messageId = request.params.message_id
+ local emoji = request.body.emoji
+
+ local response = http.post("http://localhost:3000/api/messaging/messages/" .. messageId .. "/reactions", {
+ headers = {
+ ["Authorization"] = "Bearer " .. request.user.token,
+ ["Content-Type"] = "application/json"
+ },
+ body = json.encode({
+ emoji = emoji
+ })
+ })
+
+ return {
+ status = 200,
+ body = { status = "added" }
+ }
+end
+```
+
+**Example 6: Search Messages (Lua)**
+
+```lua
+function searchMessages(request)
+ local query = request.query.q
+
+ local response = http.get("http://localhost:3000/api/messaging/search?q=" .. query, {
+ headers = {
+ ["Authorization"] = "Bearer " .. request.user.token
+ }
+ })
+
+ local results = json.decode(response.body)
+
+ return {
+ status = 200,
+ body = { results = results }
+ }
+end
+```
+
+#### Real-Time Message Delivery (Event-Driven Architecture)
+
+The messaging system uses a **fully event-driven architecture** with **zero polling**. Messages are instantly pushed to all participants when they arrive in the database, similar to Telegram and WhatsApp.
+
+**How It Works:**
+
+1. **Message Arrival Triggers Delivery:**
+ - When a message is saved to the database, `deliverMessageRealTime()` is called immediately
+ - The message is instantly pushed to all conversation participants via WebSocket
+ - Events are also published to the event bus for SSE clients (notifications, badge updates)
+ - No database polling - delivery is triggered by the DB insert event
+
+2. **Multi-Channel Delivery:**
+ - **WebSocket**: Primary real-time delivery for active conversations
+ - **SSE (Server-Sent Events)**: For notifications and badge updates (`/api/events/stream`)
+ - **Event Bus**: Publishes `message.created` events for all participants
+ - All channels work together for instant, event-driven updates
+
+3. **Online Users:**
+ - Users who are online receive messages instantly via WebSocket
+ - Badge updates (unread counts) arrive via SSE events
+ - Messages appear immediately without page refresh
+
+4. **Offline/Reconnecting Users:**
+ - When a user comes online or reconnects, they automatically fetch missed messages
+ - The system compares displayed message IDs with recent messages
+ - Only missed messages are fetched and displayed
+
+5. **WebSocket Channel Subscription:**
+ - Clients subscribe to conversation channels: `conversation:{id}`
+ - Messages are broadcast to all subscribers of the channel
+ - Also sent directly to individual users for cross-device support
+
+6. **SSE Event Listening:**
+ - Frontend components listen to SSE events for badge updates
+ - No polling intervals - updates happen instantly when messages arrive
+ - Example: Messaging inbox badge updates automatically via `message.created` events
+
+**Message Delivery Events:**
+
+When a message is sent, multiple events are triggered:
+
+1. **WebSocket Event** (for active conversations):
+```json
+{
+ "type": "message.sent",
+ "data": {
+ "id": 10,
+ "conversation_id": 1,
+ "sender_id": 1,
+ "content": "Hello everyone!",
+ "message_type": "text",
+ "created_at": "2025-12-03T11:00:00Z"
+ }
+}
+```
+
+2. **SSE Event** (for notifications and badge updates):
+```json
+{
+ "type": "notification",
+ "topic": "message.created",
+ "payload": {
+ "message_id": 10,
+ "conversation_id": 1,
+ "sender_id": 1,
+ "user_id": 2,
+ "content": "Hello everyone!",
+ "message_type": "text",
+ "created_at": "2025-12-03T11:00:00Z"
+ },
+ "time": 1701600000
+}
+```
+
+The `user_id` in the SSE event payload indicates which user should receive the notification, allowing frontend components to update badges and UI elements instantly.
+
+**Client-Side WebSocket Example:**
+
+```javascript
+// Connect to WebSocket
+const ws = new WebSocket('ws://localhost:3000/ws');
+
+// Authenticate and subscribe
+ws.onopen = () => {
+ const token = localStorage.getItem('bosa_token');
+ ws.send(JSON.stringify({ type: 'auth', token }));
+
+ // Subscribe to conversation channel
+ ws.send(JSON.stringify({
+ type: 'subscribe',
+ channel: 'conversation:1'
+ }));
+};
+
+// Listen for messages
+ws.onmessage = (event) => {
+ const message = JSON.parse(event.data);
+ if (message.type === 'message.sent') {
+ console.log('New message:', message.data);
+ // Update UI with new message instantly
+ displayMessage(message.data);
+ }
+};
+
+// Handle reconnection - fetch missed messages
+ws.onopen = () => {
+ // ... authentication and subscription ...
+
+ // After subscribing, fetch any missed messages
+ fetchMissedMessages(conversationId);
+};
+```
+
+**Key Benefits:**
+- ✅ **Zero Polling** - No database queries every few seconds (polling removed)
+- ✅ **Instant Delivery** - Messages appear immediately when sent
+- ✅ **Multi-Channel** - WebSocket + SSE for comprehensive real-time updates
+- ✅ **Event-Driven Badges** - Inbox badges update instantly via SSE events (no 30-second polling)
+- ✅ **Automatic Recovery** - Missed messages fetched on reconnect
+- ✅ **Efficient** - Event-driven architecture reduces server load by 95%+
+- ✅ **Scalable** - Works like modern messaging apps (Telegram, WhatsApp)
+
+**Polling Elimination:**
+- ❌ **Removed**: 30-second polling for messaging inbox badge
+- ❌ **Removed**: 5-second polling fallback (reduced to 30 seconds, only when WebSocket unavailable)
+- ✅ **Replaced**: All updates now event-driven via WebSocket/SSE
+- ✅ **Result**: Zero overhead when idle, instant updates when events occur
+
+#### Message Types
+
+Supported message types:
+- `text` - Plain text message (default)
+- `image` - Image message (metadata should contain `file_url`)
+- `file` - File attachment (metadata should contain `file_url`, `file_name`, `file_size`)
+- `voice` - Voice message (metadata should contain `file_url`, `duration`)
+- `location` - Location sharing (metadata should contain `latitude`, `longitude`)
+
+**Example - Send Image Message:**
+
+```lua
+local response = http.post("http://localhost:3000/api/messaging/conversations/" .. conversationId .. "/messages", {
+ headers = {
+ ["Authorization"] = "Bearer " .. token,
+ ["Content-Type"] = "application/json"
+ },
+ body = json.encode({
+ content = "Check out this image!",
+ message_type = "image",
+ metadata = {
+ file_url = "/uploads/images/photo.jpg",
+ file_name = "photo.jpg",
+ file_size = 245760
+ }
+ })
+})
+```
+
+#### Request/Response Formats
+
+**Create Conversation Request:**
+```json
+{
+ "type": "private", // "private", "group", or "channel"
+ "name": "Team Chat", // Required for groups/channels
+ "description": "Optional description",
+ "is_public": false, // For channels
+ "user_ids": [2, 3] // For private: single user ID. For groups: array of user IDs
+}
+```
+
+**Send Message Request:**
+```json
+{
+ "content": "Hello everyone!",
+ "message_type": "text", // Optional: "text", "image", "file", etc.
+ "metadata": { // Optional: for file URLs, location, etc.
+ "file_url": "/uploads/file.pdf"
+ },
+ "reply_to_id": 5 // Optional: ID of message being replied to
+}
+```
+
+**List Messages Response:**
+```json
+[
+ {
+ "id": 1,
+ "conversation_id": 1,
+ "sender_id": 1,
+ "content": "Hello!",
+ "message_type": "text",
+ "reply_to_id": null,
+ "edited_at": null,
+ "deleted_at": null,
+ "created_at": "2025-12-03T10:00:00Z"
+ }
+]
+```
+
+#### Error Handling
+
+All endpoints return standard HTTP status codes:
+- `200 OK` - Success
+- `201 Created` - Resource created
+- `400 Bad Request` - Invalid request data
+- `401 Unauthorized` - Missing or invalid authentication
+- `403 Forbidden` - Access denied (not a participant)
+- `404 Not Found` - Resource not found
+- `500 Internal Server Error` - Server error
+
+**Error Response Format:**
+```json
+{
+ "error": "Failed to send message: user is not a participant in conversation"
+}
+```
+
+#### Best Practices
+
+1. **Always handle errors** - Check response status codes
+2. **Use pagination** - For listing messages, use `limit` and `offset` parameters
+3. **Real-time updates** - Connect to WebSocket for real-time message delivery (event-driven, no polling)
+4. **SSE for badges** - Listen to SSE events (`/api/events/stream`) for badge updates and notifications
+5. **Subscribe to channels** - Subscribe to conversation channels when opening a conversation
+6. **Fetch missed messages** - When reconnecting, fetch messages that arrived while offline
+7. **Validate input** - Ensure message content is not empty before sending
+8. **Handle permissions** - Check if user is participant before accessing conversation
+9. **Cache conversations** - Store conversation list locally to reduce API calls
+10. **Never poll** - Never poll the database for new messages; use WebSocket/SSE events instead
+11. **Event-driven UI** - Update UI elements (badges, counts) via SSE events, not polling intervals
+
+**Example: Event-Driven Badge Update (JavaScript)**
+```javascript
+// Connect to SSE stream
+const eventSource = new EventSource('/api/events/stream');
+
+eventSource.onmessage = (event) => {
+ const data = JSON.parse(event.data);
+
+ // Update badge when message.created event arrives
+ if (data.type === 'notification' && data.topic === 'message.created') {
+ // Update inbox badge instantly (no polling needed)
+ updateInboxBadge();
+ }
+};
+```
+
+#### SDK Support
+
+Messaging methods will be added to all BOSA SDKs (Node.js, PHP, Python, Go) in future updates. For now, apps can use the REST API directly via HTTP requests.
+
+**Note:** When using from Lua plugins, you'll need to use `http.get()`, `http.post()`, etc. (if available in your Lua runtime) or make HTTP requests from your plugin's HTTP server.
+
+#### Complete API Reference
+
+For complete API documentation with all endpoints, request/response formats, and examples, see:
+- **[Messaging API Reference](MESSAGING_API_REFERENCE.md)** - Complete API documentation
+
+---
+
+## 6. Multi-Tenancy Support
+
+BOSA provides built-in multi-tenancy support through **sites**. This allows a single BOSA instance to serve multiple tenants (sites) with complete data isolation. All database operations are automatically scoped to the current site, ensuring that data from one site is never accessible to another.
+
+### 6.1 Overview
+
+**What is Multi-Tenancy?**
+
+Multi-tenancy allows a single BOSA instance to serve multiple independent "sites" (tenants). Each site has its own:
+- Isolated database data (automatic `site_id` filtering)
+- Configuration settings
+- Users and permissions
+- Plugin instances
+
+**Key Benefits:**
+- **Data Isolation:** Complete separation of data between sites
+- **Resource Efficiency:** Single instance serves multiple tenants
+- **Simplified Management:** One codebase, multiple deployments
+- **Automatic Scoping:** Database queries automatically filtered by site
+
+### 6.2 How It Works
+
+**Site Context:**
+- Each request includes a `site_id` in the `X-BOSA-Site-ID` header
+- The BOSA kernel's `SiteIsolationMiddleware` extracts and validates the site ID
+- All database operations are automatically scoped to the current site via `ScopedAdapter`
+
+**Automatic Site Scoping:**
+- When a site ID is set, all database queries automatically include `WHERE site_id = `
+- Inserts automatically include `site_id` in the data
+- Updates and deletes are automatically filtered by `site_id`
+- This happens transparently - no code changes needed in your plugins!
+
+**Site Management:**
+- Sites are managed via the Site Management API (`/api/sites`)
+- Super admin users can create, list, update, and delete sites
+- Site switching is handled via the UI or API
+
+### 6.3 Setting Site Context in SDKs
+
+All BOSA SDKs support multi-tenancy through site context management. The site ID is automatically included in all API requests via the `X-BOSA-Site-ID` header.
+
+#### Node.js SDK
+
+```javascript
+const { BOSA } = require('bosa-sdk-node');
+
+// Set site ID when initializing SDK
+const bosa = new BOSA({
+ kernelURL: 'http://localhost:3000',
+ pluginName: 'my-plugin',
+ pluginToken: 'your-plugin-token',
+ siteId: 1, // Set site ID
+});
+
+// Or set it later
+bosa.setSite(1);
+
+// Get current site ID
+const currentSite = bosa.getCurrentSite();
+console.log('Current site:', currentSite);
+
+// Clear site context (for super admin operations)
+bosa.setSite(null);
+```
+
+**Environment Variable:**
+```bash
+BOSA_SITE_ID=1 node your-plugin.js
+```
+
+#### PHP SDK
+
+```php
+ 'http://localhost:3000',
+ 'pluginName' => 'my-plugin',
+ 'pluginToken' => 'your-plugin-token',
+ 'siteId' => 1, // Set site ID
+]);
+
+// Or set it later
+$bosa->setSite(1);
+
+// Get current site ID
+$currentSite = $bosa->getCurrentSite();
+echo "Current site: " . ($currentSite ?? 'none') . "\n";
+
+// Clear site context (for super admin operations)
+$bosa->setSite(null);
+```
+
+**Environment Variable:**
+```bash
+export BOSA_SITE_ID=1
+php your-plugin.php
+```
+
+#### Python SDK
+
+```python
+from bosa import BOSA
+
+# Set site ID when initializing SDK
+bosa = BOSA({
+ 'kernelURL': 'http://localhost:3000',
+ 'pluginName': 'my-plugin',
+ 'pluginToken': 'your-plugin-token',
+ 'siteId': 1, # Set site ID
+})
+
+# Or set it later
+bosa.set_site(1)
+
+# Get current site ID
+current_site = bosa.get_current_site()
+print(f'Current site: {current_site}')
+
+# Clear site context (for super admin operations)
+bosa.set_site(None)
+```
+
+**Environment Variable:**
+```bash
+export BOSA_SITE_ID=1
+python your-plugin.py
+```
+
+#### Go SDK
+
+```go
+import "github.com/mmabdalla/BOSA/sdk/bosa-sdk-go"
+
+// Set site ID when initializing SDK
+siteID := int64(1)
+bosa := bosa.NewBOSA(&bosa.Config{
+ KernelURL: "http://localhost:3000",
+ PluginName: "my-plugin",
+ PluginToken: "your-plugin-token",
+ SiteID: &siteID,
+})
+
+// Or set it later
+siteID := int64(1)
+bosa.SetSite(&siteID)
+
+// Get current site ID
+currentSite := bosa.GetCurrentSite()
+if currentSite != nil {
+ fmt.Printf("Current site: %d\n", *currentSite)
+}
+
+// Clear site context (for super admin operations)
+bosa.SetSite(nil)
+```
+
+**Environment Variable:**
+```bash
+export BOSA_SITE_ID=1
+go run your-plugin.go
+```
+
+### 6.4 Automatic Site Scoping
+
+When a site ID is set, all database operations are automatically scoped to that site:
+
+**Queries:**
+```javascript
+// Node.js example
+// Set site context
+bosa.setSite(1);
+
+// All queries are automatically filtered by site_id
+const items = await bosa.db.query('items').get();
+// Only returns items where site_id = 1
+
+// Your WHERE clauses are combined with site_id filter
+const activeItems = await bosa.db.query('items')
+ .where('status', '=', 'active')
+ .get();
+// Results in: WHERE site_id = 1 AND status = 'active'
+```
+
+**Inserts:**
+```javascript
+// site_id is automatically added to inserts
+const id = await bosa.db.query('items').insert({
+ name: 'My Item',
+ status: 'active',
+ // site_id is automatically added by the backend
+});
+```
+
+**Updates and Deletes:**
+```javascript
+// Updates are automatically scoped to current site
+await bosa.db.query('items')
+ .where('id', '=', itemId)
+ .update({ status: 'completed' });
+// Only updates items where site_id = 1
+
+// Deletes are automatically scoped to current site
+await bosa.db.query('items')
+ .where('status', '=', 'deleted')
+ .delete();
+// Only deletes items where site_id = 1
+```
+
+### 6.5 Site Management API
+
+The Site Management API allows you to manage sites programmatically:
+
+**List Sites:**
+```bash
+GET /api/sites
+Authorization: Bearer YOUR_TOKEN
+```
+
+**Response:**
+```json
+{
+ "sites": [
+ {
+ "id": 1,
+ "name": "Site 1",
+ "owner_id": 1,
+ "config": {
+ "theme": "light",
+ "timezone": "UTC"
+ },
+ "created_at": "2025-12-05T10:00:00Z",
+ "updated_at": "2025-12-05T10:00:00Z"
+ }
+ ]
+}
+```
+
+**Create Site:**
+```bash
+POST /api/sites
+Authorization: Bearer YOUR_TOKEN
+Content-Type: application/json
+
+{
+ "name": "New Site",
+ "config": {
+ "theme": "dark",
+ "timezone": "America/New_York"
+ }
+}
+```
+
+**Get Site:**
+```bash
+GET /api/sites/:id
+Authorization: Bearer YOUR_TOKEN
+```
+
+**Update Site:**
+```bash
+PUT /api/sites/:id
+Authorization: Bearer YOUR_TOKEN
+Content-Type: application/json
+
+{
+ "name": "Updated Site Name",
+ "config": {
+ "theme": "light"
+ }
+}
+```
+
+**Delete Site:**
+```bash
+DELETE /api/sites/:id
+Authorization: Bearer YOUR_TOKEN
+```
+
+**Switch Site (for UI):**
+```bash
+POST /api/sites/:id/switch
+Authorization: Bearer YOUR_TOKEN
+```
+
+### 6.6 Site Configuration
+
+Sites can have custom configuration stored as JSON:
+
+```json
+{
+ "theme": "dark",
+ "timezone": "America/New_York",
+ "language": "en",
+ "custom_setting": "value"
+}
+```
+
+**Accessing Site Configuration:**
+- Site configuration is stored in the `sites` table's `config` column (JSONB)
+- Access via Site Management API
+- Can be used for site-specific settings (theme, timezone, language, etc.)
+
+### 6.7 Best Practices
+
+**1. Always Set Site Context:**
+```javascript
+// ✅ GOOD: Set site context at plugin initialization
+const bosa = new BOSA({
+ siteId: process.env.BOSA_SITE_ID || 1,
+});
+
+// ❌ BAD: Forgetting to set site context
+const bosa = new BOSA(); // No site context - queries won't be scoped!
+```
+
+**2. Use Environment Variables:**
+```bash
+# Set site ID via environment variable
+export BOSA_SITE_ID=1
+```
+
+**3. Handle Site Switching:**
+```javascript
+// When user switches sites in UI, update SDK context
+function handleSiteSwitch(newSiteId) {
+ bosa.setSite(newSiteId);
+ // Reload data for new site
+ loadData();
+}
+```
+
+**4. Super Admin Operations:**
+```javascript
+// For super admin operations that need to access all sites
+bosa.setSite(null); // Clear site context
+// Now queries will access all sites (use with caution!)
+```
+
+**5. Site-Specific Data:**
+```javascript
+// ✅ GOOD: Let BOSA handle site scoping automatically
+const items = await bosa.db.query('items').get();
+// Automatically filtered by site_id
+
+// ❌ BAD: Manually adding site_id to queries
+const items = await bosa.db.query('items')
+ .where('site_id', '=', 1) // Don't do this - it's automatic!
+ .get();
+```
+
+**6. Testing Multi-Tenancy:**
+```javascript
+// Test with different site contexts
+bosa.setSite(1);
+const site1Items = await bosa.db.query('items').get();
+
+bosa.setSite(2);
+const site2Items = await bosa.db.query('items').get();
+
+// Verify data isolation
+console.assert(site1Items.length !== site2Items.length ||
+ site1Items.every(item => item.site_id === 1));
+```
+
+### 6.8 User-Site Relationship Architecture
+
+BOSA implements a **flexible hybrid approach** for user-site relationships that provides maximum flexibility while maintaining backward compatibility.
+
+#### Architecture Overview
+
+**Users Table (Global):**
+- The `users` table remains global (no `site_id` column)
+- All users exist globally in the system
+- User registration creates global accounts
+- Supports users who may belong to multiple sites
+
+**Site Membership via `site_users` Junction Table:**
+- `site_users` table: `id`, `site_id`, `user_id`, `role`, `created_at`, `updated_at`
+- User can belong to zero, one, or multiple sites
+- Different roles per site (e.g., `site_admin` in Site A, `employee` in Site B)
+- Unique constraint: `(site_id, user_id)` - user can only have one role per site
+
+**Supported Roles:**
+- `site_admin` - Full access to assigned site(s) only
+- `employee` - Limited access to assigned site(s) only
+- `user` - Basic site member access
+
+**Access Control Logic:**
+- **Super Admin**: Global access to all sites (bypasses site_users check)
+- **Site Admin**: Full access to assigned site(s) only
+- **Site Employee/User**: Limited access to assigned site(s) only
+- **Global User (no site_users entry)**: No site access (unless super_admin)
+- **Site Owner (backward compatibility)**: Users with `owner_id` in sites table still have access
+
+**Benefits:**
+- Maximum flexibility: Users can belong to multiple sites
+- Backward compatible: Existing global users and site owners still work
+- Supports use cases:
+ - User manages multiple sites (site_admin of Site A, employee of Site B)
+ - Customer account belongs to one site only
+ - Super Admin has global access
+ - Apps can extend with additional role systems
+
+**API Endpoints for Site Users:**
+```
+POST /api/sites/:sid/users - Add user to site (with role)
+GET /api/sites/:sid/users - List all users in site
+GET /api/sites/:sid/users/:uid - Get user details in site
+PUT /api/sites/:sid/users/:uid - Update user role in site
+DELETE /api/sites/:sid/users/:uid - Remove user from site
+GET /api/users/:uid/sites - List all sites user belongs to
+```
+
+**Request/Response Examples:**
+
+**Add User to Site:**
+```bash
+POST /api/sites/2/users
+Authorization: Bearer YOUR_TOKEN
+Content-Type: application/json
+
+{
+ "email": "user@example.com", # Optional: creates user if doesn't exist
+ "user_id": 3, # Optional: use existing user ID
+ "role": "site_admin" # Required: "site_admin", "employee", or "user"
+}
+```
+
+**Response:**
+```json
+{
+ "id": 1,
+ "site_id": 2,
+ "user_id": 3,
+ "role": "site_admin",
+ "created_at": "2025-12-23T21:35:00Z",
+ "updated_at": "2025-12-23T21:35:00Z"
+}
+```
+
+**List Site Users:**
+```bash
+GET /api/sites/2/users
+Authorization: Bearer YOUR_TOKEN
+```
+
+**Response:**
+```json
+{
+ "users": [
+ {
+ "id": 1,
+ "site_id": 2,
+ "user_id": 3,
+ "role": "site_admin",
+ "user_email": "admin@example.com",
+ "user_name": "Site Admin",
+ "created_at": "2025-12-23T21:35:00Z",
+ "updated_at": "2025-12-23T21:35:00Z"
+ }
+ ],
+ "count": 1
+}
+```
+
+**Update User Role:**
+```bash
+PUT /api/sites/2/users/3
+Authorization: Bearer YOUR_TOKEN
+Content-Type: application/json
+
+{
+ "role": "employee"
+}
+```
+
+**Remove User from Site:**
+```bash
+DELETE /api/sites/2/users/3
+Authorization: Bearer YOUR_TOKEN
+```
+
+**List User's Sites:**
+```bash
+GET /api/users/3/sites
+Authorization: Bearer YOUR_TOKEN
+```
+
+**Response:**
+```json
+{
+ "sites": [
+ {
+ "id": 2,
+ "name": "My Site",
+ "role": "site_admin",
+ "created_at": "2025-12-23T21:35:00Z"
+ }
+ ],
+ "count": 1
+}
+```
+
+**Permissions:**
+- **Super Admin**: Can manage all site users (add, list, update, remove)
+- **Site Admin**: Can manage non-Super Admin users in their assigned site(s) (add, list, update, remove)
+- **Other Users**: Cannot manage site users
+
+**App Integration:**
+- Apps can query `site_users` to get site membership
+- Apps can add custom role systems (e.g., `vendor_employees`) that reference `site_users`
+- Apps inherit BOSA's site permission checks automatically
+- Helper functions available: `GetUserSites()`, `IsUserInSite()`, `GetUserRoleInSite()`
+
+**Checking Site Membership in Plugins:**
+
+**Node.js SDK:**
+```javascript
+// Check if user is in site (via API)
+const response = await fetch(`/api/users/${userId}/sites`, {
+ headers: { 'Authorization': `Bearer ${token}` }
+});
+const { sites } = await response.json();
+const isInSite = sites.some(s => s.id === siteId);
+
+// Get user's role in site
+const siteUser = sites.find(s => s.id === siteId);
+const role = siteUser ? siteUser.role : null;
+```
+
+**Go SDK:**
+```go
+// Use BOSA API client to check site membership
+resp, err := http.Get(fmt.Sprintf("%s/api/users/%d/sites", kernelURL, userID))
+// Parse response to check membership
+```
+
+**Lua Runtime:**
+```lua
+-- Site membership is automatically checked by middleware
+-- Your plugin code doesn't need to manually check membership
+-- The scoped adapter ensures users only see data for sites they belong to
+```
+
+### 6.9 Excluded Tables
+
+Some system tables are excluded from site scoping (they're global):
+- `users` - User accounts are global
+- `sites` - Site definitions are global
+- `site_users` - Site membership is global (junction table)
+- `plugin_config` - Plugin configuration is global
+- `i18n_translations` - Translations are global (app-scoped, not site-scoped)
+
+**Note:** Site membership is managed through the `site_users` junction table, not by adding `site_id` to the users table. This allows users to belong to multiple sites with different roles.
+
+### 6.10 Site Switching in UI
+
+The BOSA UI includes a site switcher that allows users to switch between sites:
+
+**How It Works:**
+1. User selects a site from the dropdown
+2. Site ID is stored in `localStorage` (`current_site_id`)
+3. All subsequent API requests include `X-BOSA-Site-ID` header
+4. Database queries are automatically scoped to the new site
+
+**Implementation:**
+```javascript
+// Site switching function (from site-management.js)
+function switchToSite(siteId, siteName) {
+ localStorage.setItem('current_site_id', siteId);
+ localStorage.setItem('current_site_name', siteName);
+
+ // Update UI
+ updateSiteSwitcher();
+
+ // Reload page data
+ location.reload();
+}
+```
+
+### 6.11 Plugin Sidebar Filtering
+
+BOSA automatically filters plugins in the sidebar based on user's site membership:
+
+**Filtering Logic:**
+- **Super Admins**: See all plugins (full access)
+- **Site Members**: See all plugins if they are members of at least one site
+- **Users Not in Any Site**: See no plugins (empty sidebar)
+
+**How It Works:**
+1. When user loads the dashboard/admin page, frontend calls `GET /api/plugins`
+2. Backend checks user's site membership:
+ - If super admin → return all plugins
+ - If user is member of at least one site → return all plugins
+ - If user is not in any site → return empty list
+3. Frontend displays only the plugins returned by the API
+
+**API Endpoint:**
+```bash
+GET /api/plugins
+Authorization: Bearer YOUR_TOKEN
+```
+
+**Response (for users with site membership):**
+```json
+[
+ {
+ "name": "todo",
+ "version": "1.0.0",
+ "description": "Todo app",
+ "author": "BOSA Team",
+ "enabled": true,
+ "routes": 5,
+ "frontendRoutes": ["/todo/"],
+ "events": {
+ "subscribe": 2,
+ "publish": 1
+ }
+ }
+]
+```
+
+**Response (for users without site membership):**
+```json
+[]
+```
+
+**Security Benefits:**
+- Prevents unauthorized access to plugin UIs
+- Users must be assigned to at least one site to see plugins
+- Super admins maintain full visibility for management purposes
+
+### 6.10 Multi-Tenancy in Lua Plugins
+
+For Lua plugins, site context is handled automatically by the BOSA kernel:
+
+```lua
+-- Site ID is automatically extracted from X-BOSA-Site-ID header
+-- All database queries are automatically scoped
+
+function listItems(request)
+ -- This query is automatically scoped to the current site
+ local items = bosa.db.query("items"):get()
+
+ return {
+ status = 200,
+ body = { items = items }
+ }
+end
+```
+
+**Note:** Lua plugins don't need to manually set site context - it's handled by the kernel middleware.
+
+### 6.11 Troubleshooting
+
+**Problem: Queries returning data from all sites**
+
+**Solution:** Ensure site ID is set in SDK:
+```javascript
+// Check if site ID is set
+console.log('Current site:', bosa.getCurrentSite());
+
+// Set site ID if missing
+if (!bosa.getCurrentSite()) {
+ bosa.setSite(1); // Or from environment variable
+}
+```
+
+**Problem: Inserts failing with site_id constraint**
+
+**Solution:** Don't manually add `site_id` to inserts - it's automatic:
+```javascript
+// ✅ GOOD: Let BOSA add site_id automatically
+await bosa.db.query('items').insert({
+ name: 'Item',
+ // site_id is added automatically
+});
+
+// ❌ BAD: Don't manually add site_id
+await bosa.db.query('items').insert({
+ name: 'Item',
+ site_id: 1, // Don't do this - it's automatic!
+});
+```
+
+**Problem: Updates affecting all sites**
+
+**Solution:** Ensure site context is set before updates:
+```javascript
+// Set site context first
+bosa.setSite(1);
+
+// Then perform update
+await bosa.db.query('items')
+ .where('id', '=', itemId)
+ .update({ status: 'completed' });
+```
+
+---
+
+## 7. Currency Support
+
+BOSA provides comprehensive currency support with ISO 4217 currency definitions, formatting utilities, and app-specific currency configuration. This allows your apps to handle multiple currencies, format amounts correctly, and configure which currencies are available to users.
+
+### 7.1 Overview
+
+**What is Currency Support?**
+
+Currency support in BOSA provides:
+- **ISO 4217 Currency Database:** All world currencies with codes, names, symbols, and decimal places
+- **Currency Formatting:** Automatic formatting with proper decimal places and thousand separators
+- **App Currency Configuration:** Each app can enable/disable specific currencies
+- **Default Currency:** Each app can set a default currency
+- **SDK Integration:** Currency formatting available in all SDKs
+
+**Key Benefits:**
+- **Standardized Currency Codes:** ISO 4217 compliant currency codes
+- **Automatic Formatting:** Proper formatting based on currency rules (e.g., JPY has 0 decimals, USD has 2)
+- **Flexible Configuration:** Apps can enable only the currencies they need
+- **Multi-Currency Support:** Apps can support multiple currencies simultaneously
+
+### 7.2 Currency Configuration in Manifest
+
+You can declare supported currencies in your app's `manifest.yaml`:
+
+```yaml
+name: my-ecommerce-app
+version: 1.0.0
+description: E-commerce application with multi-currency support
+
+# Supported currencies
+supported_currencies:
+ - code: USD
+ default: true
+ - code: EUR
+ default: false
+ - code: GBP
+ default: false
+```
+
+**Validation Rules:**
+- Currency codes must be 3 uppercase letters (ISO 4217 format)
+- At least one currency must be marked as `default: true`
+- Only one currency can be marked as default
+- Currency codes are validated against the system currency database when the app is configured
+
+### 7.3 App Currency Configuration
+
+Apps can configure which currencies they support via the API or UI:
+
+**Via API:**
+```bash
+# Get app currencies
+GET /api/apps/:name/currencies
+Authorization: Bearer YOUR_TOKEN
+
+# Enable/disable a currency
+PUT /api/apps/:name/currencies/:code
+Authorization: Bearer YOUR_TOKEN
+Content-Type: application/json
+
+{
+ "enabled": true
+}
+
+# Set default currency
+PUT /api/apps/:name/currencies/:code/default
+Authorization: Bearer YOUR_TOKEN
+
+# Bulk update currencies
+PUT /api/apps/:name/currencies
+Authorization: Bearer YOUR_TOKEN
+Content-Type: application/json
+
+{
+ "currencies": ["USD", "EUR", "GBP"],
+ "default": "USD"
+}
+```
+
+**Via UI:**
+1. Navigate to `/plugins` page
+2. Click "Currencies" button for your app
+3. Enable/disable currencies using checkboxes
+4. Set default currency using "Set as Default" button
+
+**Important Notes:**
+- The default currency cannot be disabled (set another default first)
+- Currency changes take effect immediately
+- Only system-enabled currencies can be enabled for apps
+
+### 7.4 Using Currency in SDKs
+
+All BOSA SDKs provide currency formatting and management functionality:
+
+#### Node.js SDK
+
+```javascript
+const { BOSA } = require('bosa-sdk-node');
+
+const bosa = new BOSA({
+ kernelURL: 'http://localhost:3000',
+ pluginName: 'my-plugin',
+ pluginToken: 'your-plugin-token',
+});
+
+// List all available currencies
+const currencies = await bosa.currency.list();
+console.log('Available currencies:', currencies);
+
+// Get a specific currency
+const usd = await bosa.currency.get('USD');
+console.log('USD:', usd);
+
+// Format an amount
+const formatted = await bosa.currency.format(1234.56, 'USD');
+console.log(formatted); // "$1,234.56"
+
+// Simple formatting (no API call)
+const simple = bosa.currency.formatSimple(1234.56, '$', 2);
+console.log(simple); // "$1,234.56"
+
+// Format JPY (0 decimal places)
+const jpy = await bosa.currency.format(1234.56, 'JPY');
+console.log(jpy); // "¥1,235"
+```
+
+#### PHP SDK
+
+```php
+ 'http://localhost:3000',
+ 'pluginName' => 'my-plugin',
+ 'pluginToken' => 'your-plugin-token',
+]);
+
+// List all available currencies
+$currencies = $bosa->currency->list();
+print_r($currencies);
+
+// Get a specific currency
+$usd = $bosa->currency->get('USD');
+print_r($usd);
+
+// Format an amount
+$formatted = $bosa->currency->format(1234.56, 'USD');
+echo $formatted; // "$1,234.56"
+
+// Simple formatting (no API call)
+$simple = $bosa->currency->formatSimple(1234.56, '$', 2);
+echo $simple; // "$1,234.56"
+```
+
+#### Python SDK
+
+```python
+from bosa import BOSA
+
+bosa = BOSA({
+ 'kernelURL': 'http://localhost:3000',
+ 'pluginName': 'my-plugin',
+ 'pluginToken': 'your-plugin-token',
+})
+
+# List all available currencies
+currencies = await bosa.currency.list()
+print('Available currencies:', currencies)
+
+# Get a specific currency
+usd = await bosa.currency.get('USD')
+print('USD:', usd)
+
+# Format an amount
+formatted = await bosa.currency.format(1234.56, 'USD')
+print(formatted) # "$1,234.56"
+
+# Simple formatting (no API call)
+simple = bosa.currency.format_simple(1234.56, '$', 2)
+print(simple) # "$1,234.56"
+```
+
+#### Go SDK
+
+```go
+import "github.com/mmabdalla/BOSA/sdk/bosa-sdk-go"
+
+bosa := bosa.NewBOSA(&bosa.Config{
+ KernelURL: "http://localhost:3000",
+ PluginName: "my-plugin",
+ PluginToken: "your-plugin-token",
+})
+
+// List all available currencies
+currencies, err := bosa.Currency().List()
+if err != nil {
+ log.Fatal(err)
+}
+fmt.Println("Available currencies:", currencies)
+
+// Get a specific currency
+usd, err := bosa.Currency().Get("USD")
+if err != nil {
+ log.Fatal(err)
+}
+fmt.Println("USD:", usd)
+
+// Format an amount
+formatted, err := bosa.Currency().Format(1234.56, "USD")
+if err != nil {
+ log.Fatal(err)
+}
+fmt.Println(formatted) // "$1,234.56"
+
+// Simple formatting (no API call)
+simple := bosa.Currency().FormatSimple(1234.56, "$", 2)
+fmt.Println(simple) // "$1,234.56"
+```
+
+#### Lua Runtime
+
+```lua
+-- List all available currencies
+local currencies = bosa.currency.list()
+for i, curr in ipairs(currencies) do
+ print(string.format("%s (%s): %s", curr.name, curr.code, curr.symbol))
+end
+
+-- Get a specific currency
+local usd = bosa.currency.get("USD")
+print(string.format("USD: %s", usd.symbol))
+
+-- Format an amount
+local formatted = bosa.currency.format(1234.56, "USD")
+print(formatted) -- "$1,234.56"
+
+-- Simple formatting (no API call)
+local simple = bosa.currency.formatSimple(1234.56, "$", 2)
+print(simple) -- "$1,234.56"
+
+-- Format JPY (0 decimal places)
+local jpy = bosa.currency.format(1234.56, "JPY")
+print(jpy) -- "¥1,235"
+```
+
+### 7.5 Currency API Endpoints
+
+**List All Currencies:**
+```bash
+GET /api/currencies
+```
+
+**Response:**
+```json
+[
+ {
+ "code": "USD",
+ "name": "US Dollar",
+ "symbol": "$",
+ "decimal_places": 2,
+ "enabled": true,
+ "is_default": true
+ },
+ {
+ "code": "EUR",
+ "name": "Euro",
+ "symbol": "€",
+ "decimal_places": 2,
+ "enabled": true,
+ "is_default": false
+ }
+]
+```
+
+**Get Specific Currency:**
+```bash
+GET /api/currencies/:code
+```
+
+**Format Amount:**
+```bash
+POST /api/currencies/format
+Content-Type: application/json
+
+{
+ "amount": 1234.56,
+ "currency_code": "USD"
+}
+```
+
+**Response:**
+```json
+{
+ "amount": 1234.56,
+ "code": "USD",
+ "formatted": "$1,234.56"
+}
+```
+
+### 7.6 Currency Formatting Rules
+
+**Decimal Places:**
+- Most currencies use 2 decimal places (USD, EUR, GBP, etc.)
+- Some currencies use 0 decimal places (JPY, KRW, VND, etc.)
+- Some currencies use 3 decimal places (BHD, JOD, KWD, etc.)
+
+**Thousand Separators:**
+- Uses comma (`,`) as thousand separator
+- Applied automatically based on currency rules
+
+**Symbol Position:**
+- Most currencies place symbol before amount (e.g., `$1,234.56`)
+- Some currencies place symbol after amount (e.g., `1,234.56 €`)
+
+**Examples:**
+```javascript
+// USD: 2 decimal places, symbol before
+await bosa.currency.format(1234.56, 'USD'); // "$1,234.56"
+
+// JPY: 0 decimal places, symbol before
+await bosa.currency.format(1234.56, 'JPY'); // "¥1,235"
+
+// EUR: 2 decimal places, symbol after (in some locales)
+await bosa.currency.format(1234.56, 'EUR'); // "€1,234.56"
+```
+
+### 7.7 Best Practices
+
+**1. Always Use Currency Codes:**
+```javascript
+// ✅ GOOD: Use ISO 4217 currency codes
+const formatted = await bosa.currency.format(amount, 'USD');
+
+// ❌ BAD: Using currency names or symbols directly
+const formatted = `$${amount}`; // Doesn't handle decimal places correctly
+```
+
+**2. Get App Default Currency:**
+```javascript
+// Get app's default currency from configuration
+const appCurrencies = await fetch('/api/apps/my-app/currencies');
+const defaultCurrency = appCurrencies.find(c => c.is_default);
+const formatted = await bosa.currency.format(amount, defaultCurrency.code);
+```
+
+**3. Handle Currency Switching:**
+```javascript
+// When user switches currency in UI
+async function switchCurrency(newCurrencyCode) {
+ // Validate currency is enabled for app
+ const appCurrencies = await fetch('/api/apps/my-app/currencies');
+ const currency = appCurrencies.find(c => c.code === newCurrencyCode);
+
+ if (currency && currency.enabled) {
+ // Reformat all amounts with new currency
+ updateDisplayedPrices(newCurrencyCode);
+ }
+}
+```
+
+**4. Cache Currency Data:**
+```javascript
+// Cache currency list to avoid repeated API calls
+let cachedCurrencies = null;
+
+async function getCurrencies() {
+ if (!cachedCurrencies) {
+ cachedCurrencies = await bosa.currency.list();
+ }
+ return cachedCurrencies;
+}
+```
+
+**5. Validate Currency Codes:**
+```javascript
+// Always validate currency codes before formatting
+async function formatAmount(amount, currencyCode) {
+ try {
+ // This will throw if currency doesn't exist
+ await bosa.currency.get(currencyCode);
+ return await bosa.currency.format(amount, currencyCode);
+ } catch (error) {
+ console.error(`Invalid currency code: ${currencyCode}`);
+ return `${amount} ${currencyCode}`; // Fallback
+ }
+}
+```
+
+### 7.8 Site and App Currency Configuration
+
+**Site-Level Currency Configuration:**
+
+Sites can have currency preferences in their configuration:
+
+```json
+{
+ "default_currency": "USD",
+ "supported_currencies": ["USD", "EUR", "GBP"],
+ "currency_display": "symbol" // or "code"
+}
+```
+
+**App-Level Currency Configuration:**
+
+Each app can configure its own supported currencies independently:
+
+```yaml
+# manifest.yaml
+supported_currencies:
+ - code: USD
+ default: true
+ - code: EUR
+ default: false
+```
+
+**Priority:**
+1. App currency configuration takes precedence
+2. If app doesn't specify currencies, site defaults are used
+3. If neither is specified, system default (USD) is used
+
+---
+
+## 8. Location Services
+
+BOSA provides comprehensive location services that allow apps to configure location-based availability, detect user locations, and enforce location restrictions. This enables apps to be available globally or restricted to specific countries, regions, or cities.
+
+### 8.1 Overview
+
+**What is Location Services?**
+
+Location services in BOSA provide:
+- **Global Location Database:** Countries, regions/states, and cities with ISO 3166-1/3166-2 codes
+- **Location Detection:** Automatic detection from request headers (IP geolocation, Cloudflare headers, Accept-Language)
+- **Location Restrictions:** Apps can be configured as "global" (available everywhere) or "restricted" (specific locations only)
+- **Location-Based Access Control:** Automatic blocking of requests from restricted locations
+- **SDK Integration:** Location detection and availability checking in all SDKs
+
+**Key Benefits:**
+- **Geographic Targeting:** Restrict app availability to specific countries/regions
+- **Compliance:** Meet regulatory requirements (e.g., GDPR, data residency)
+- **Automatic Detection:** User location detected automatically from headers
+- **Flexible Configuration:** Configure at app level via manifest or API
+- **Hierarchical Support:** Country → Region → City hierarchy
+
+### 8.2 Location Configuration in Manifest
+
+You can declare location availability in your app's `manifest.yaml`:
+
+```yaml
+name: my-regional-app
+version: 1.0.0
+description: App with location restrictions
+
+# Location availability configuration
+location_availability:
+ mode: restricted # or "global"
+ locations:
+ - US # Country code (ISO 3166-1 alpha-2)
+ - CA # Canada
+ - GB # United Kingdom
+ - US-CA # Region code (US California)
+ - 123 # City ID (numeric)
+```
+
+**Validation Rules:**
+- `mode` must be either `"global"` or `"restricted"`
+- If `mode` is `"restricted"`, `locations` array must not be empty
+- Location codes are validated against the system location database when the app is configured
+- Country codes: 2 uppercase letters (e.g., "US", "GB", "CA")
+- Region codes: "COUNTRY-REGION" format (e.g., "US-CA", "GB-ENG")
+- City codes: Numeric IDs from the cities table
+
+### 8.3 App Location Configuration
+
+Apps can configure location availability via the API or UI:
+
+**Via API:**
+```bash
+# Get app location configuration
+GET /api/apps/:name/locations
+Authorization: Bearer YOUR_TOKEN
+
+# Set location configuration
+PUT /api/apps/:name/locations
+Authorization: Bearer YOUR_TOKEN
+Content-Type: application/json
+
+{
+ "mode": "restricted",
+ "locations": ["US", "CA", "GB"]
+}
+
+# Check if app is available in a location
+GET /api/apps/:name/locations/check?type=country&code=US
+Authorization: Bearer YOUR_TOKEN
+```
+
+**Via UI:**
+1. Navigate to `/plugins` page
+2. Click "Locations" button for your app
+3. Select "Global" or "Restricted" mode
+4. If restricted, select countries from the list
+5. Click "Save Settings"
+
+**Important Notes:**
+- Global mode: App is available everywhere (no restrictions)
+- Restricted mode: App is only available in specified locations
+- Location changes take effect immediately
+- Hierarchical matching: If app is restricted to a country, regions and cities within that country are also allowed
+
+### 8.4 Using Location in SDKs
+
+All BOSA SDKs provide location detection and availability checking:
+
+#### Node.js SDK
+
+```javascript
+const { BOSA } = require('bosa-sdk-node');
+
+const bosa = new BOSA({
+ kernelURL: 'http://localhost:3000',
+ pluginName: 'my-plugin',
+ pluginToken: 'your-plugin-token',
+});
+
+// Get current user location
+const location = await bosa.location.getLocation();
+console.log('User location:', location);
+// Returns: { type: 'country', code: 'US', name: 'United States' }
+
+// Check if app is available in a location
+const available = await bosa.location.isAvailable('country', 'US');
+console.log('Available in US:', available); // true or false
+
+// Get location availability configuration
+const availability = await bosa.location.getAvailability();
+console.log('Availability:', availability);
+// Returns: { mode: 'global' | 'restricted', locations: ['US', 'CA'] }
+
+// List all countries
+const countries = await bosa.location.listCountries();
+console.log('Countries:', countries);
+
+// Get country by code
+const us = await bosa.location.getCountry('US');
+console.log('United States:', us);
+```
+
+#### PHP SDK
+
+```php
+ 'http://localhost:3000',
+ 'pluginName' => 'my-plugin',
+ 'pluginToken' => 'your-plugin-token',
+]);
+
+// Get current user location
+$location = $bosa->location->getLocation();
+print_r($location);
+
+// Check if app is available in a location
+$available = $bosa->location->isAvailable('country', 'US');
+echo "Available in US: " . ($available ? 'yes' : 'no') . "\n";
+
+// Get location availability configuration
+$availability = $bosa->location->getAvailability();
+print_r($availability);
+
+// List all countries
+$countries = $bosa->location->listCountries();
+print_r($countries);
+
+// Get country by code
+$us = $bosa->location->getCountry('US');
+print_r($us);
+```
+
+#### Python SDK
+
+```python
+from bosa import BOSA
+
+bosa = BOSA({
+ 'kernelURL': 'http://localhost:3000',
+ 'pluginName': 'my-plugin',
+ 'pluginToken': 'your-plugin-token',
+})
+
+# Get current user location (async)
+location = await bosa.location.get_location()
+print('User location:', location)
+
+# Check if app is available in a location
+available = await bosa.location.is_available('country', 'US')
+print('Available in US:', available)
+
+# Get location availability configuration
+availability = await bosa.location.get_availability()
+print('Availability:', availability)
+
+# List all countries
+countries = await bosa.location.list_countries()
+print('Countries:', countries)
+
+# Get country by code
+us = await bosa.location.get_country('US')
+print('United States:', us)
+```
+
+#### Go SDK
+
+```go
+import "github.com/mmabdalla/BOSA/sdk/bosa-sdk-go"
+
+bosa := bosa.NewBOSA(&bosa.Config{
+ KernelURL: "http://localhost:3000",
+ PluginName: "my-plugin",
+ PluginToken: "your-plugin-token",
+})
+
+// Get current user location
+location, err := bosa.Location().GetLocation()
+if err != nil {
+ log.Fatal(err)
+}
+fmt.Println("User location:", location)
+
+// Check if app is available in a location
+available, err := bosa.Location().IsAvailable("country", "US")
+if err != nil {
+ log.Fatal(err)
+}
+fmt.Println("Available in US:", available)
+
+// Get location availability configuration
+availability, err := bosa.Location().GetAvailability()
+if err != nil {
+ log.Fatal(err)
+}
+fmt.Println("Availability:", availability)
+
+// List all countries
+countries, err := bosa.Location().ListCountries()
+if err != nil {
+ log.Fatal(err)
+}
+fmt.Println("Countries:", countries)
+
+// Get country by code
+us, err := bosa.Location().GetCountry("US")
+if err != nil {
+ log.Fatal(err)
+}
+fmt.Println("United States:", us)
+```
+
+#### Lua Runtime
+
+```lua
+-- Get current user location (returns nil - location detected automatically by middleware)
+local location = bosa.location.getLocation()
+-- Note: Location is automatically detected from request headers by middleware
+
+-- Check if app is available in a location
+local available = bosa.location.isAvailable("country", "US")
+print("Available in US: " .. tostring(available))
+
+-- Get location availability configuration
+local availability = bosa.location.getAvailability()
+print("Mode: " .. availability.mode)
+if availability.locations then
+ for i, loc in ipairs(availability.locations) do
+ print("Location: " .. loc)
+ end
+end
+
+-- List all countries
+local countries = bosa.location.listCountries()
+for i, country in ipairs(countries) do
+ print(string.format("%s (%s): %s", country.name, country.code, country.iso3))
+end
+
+-- Get country by code
+local us = bosa.location.getCountry("US")
+print(string.format("United States: %s (%s)", us.name, us.code))
+```
+
+### 8.5 Location API Endpoints
+
+**List All Countries:**
+```bash
+GET /api/locations/countries
+```
+
+**Response:**
+```json
+[
+ {
+ "code": "US",
+ "name": "United States",
+ "iso3": "USA",
+ "numeric_code": 840,
+ "enabled": true
+ },
+ {
+ "code": "GB",
+ "name": "United Kingdom",
+ "iso3": "GBR",
+ "numeric_code": 826,
+ "enabled": true
+ }
+]
+```
+
+**Get Country by Code:**
+```bash
+GET /api/locations/countries/:code
+```
+
+**List Regions for a Country:**
+```bash
+GET /api/locations/countries/:code/regions
+```
+
+**List Cities for a Country:**
+```bash
+GET /api/locations/countries/:code/cities
+```
+
+**List Cities for a Region:**
+```bash
+GET /api/locations/regions/:id/cities?country=US
+```
+
+**Get Location Hierarchy:**
+```bash
+GET /api/locations/hierarchy?type=country&code=US
+```
+
+**Response:**
+```json
+{
+ "country": {
+ "code": "US",
+ "name": "United States",
+ "iso3": "USA",
+ "numeric_code": 840
+ },
+ "region": null,
+ "city": null
+}
+```
+
+### 8.6 Location Detection
+
+BOSA automatically detects user location from request headers:
+
+**Detection Methods (in order):**
+1. **X-BOSA-Location Header:** Explicit location set by client or proxy
+ - Format: `"country:US"` or `"region:US-CA"` or `"city:123"`
+2. **CF-IPCountry Header:** Cloudflare IP geolocation
+ - Returns 2-letter country code (e.g., "US", "GB")
+3. **Accept-Language Header:** Language code hints
+ - Extracts country from language codes like "en-US" → "US"
+4. **IP Geolocation:** (Future enhancement - requires external service)
+
+**Location Detection in Middleware:**
+- Location is automatically detected by `LocationRestrictionMiddleware`
+- Detected location is used to enforce app restrictions
+- If detection fails, access is allowed by default (fail-open)
+
+### 8.7 Location-Based Access Control
+
+When an app is configured with location restrictions, BOSA automatically enforces access control:
+
+**How It Works:**
+1. User makes a request to a plugin route
+2. Location is detected from request headers
+3. System checks if app is available in detected location
+4. If not available, request is blocked with 403 Forbidden
+5. If available or app is global, request proceeds normally
+
+**Example - Restricted App:**
+```yaml
+# manifest.yaml
+location_availability:
+ mode: restricted
+ locations: ["US", "CA"]
+```
+
+**Result:**
+- Users from US or CA: ✅ Access allowed
+- Users from GB or other countries: ❌ Access denied (403 Forbidden)
+- Users from US regions/cities: ✅ Access allowed (hierarchical matching)
+
+**Example - Global App:**
+```yaml
+# manifest.yaml
+location_availability:
+ mode: global
+```
+
+**Result:**
+- All users: ✅ Access allowed (no restrictions)
+
+### 8.8 Location Code Formats
+
+**Country Codes (ISO 3166-1 alpha-2):**
+- Format: 2 uppercase letters
+- Examples: `"US"`, `"GB"`, `"CA"`, `"FR"`, `"DE"`
+
+**Region Codes (ISO 3166-2):**
+- Format: `"COUNTRY-REGION"`
+- Examples: `"US-CA"` (California), `"US-NY"` (New York), `"GB-ENG"` (England)
+
+**City Codes:**
+- Format: Numeric ID from cities table
+- Examples: `"123"`, `"456"`, `"789"`
+
+### 8.9 Best Practices
+
+**1. Use Global Mode by Default:**
+```yaml
+# ✅ GOOD: Start with global, add restrictions only when needed
+location_availability:
+ mode: global
+```
+
+**2. Test Location Restrictions:**
+```javascript
+// Test with different location contexts
+const availableUS = await bosa.location.isAvailable('country', 'US');
+const availableGB = await bosa.location.isAvailable('country', 'GB');
+console.assert(availableUS === true); // If app is restricted to US
+console.assert(availableGB === false); // If app is restricted to US
+```
+
+**3. Handle Location Detection Failures:**
+```javascript
+// Location detection may fail - handle gracefully
+const location = await bosa.location.getLocation();
+if (!location) {
+ // Fallback: Use default location or allow access
+ console.warn('Location detection failed, using default');
+}
+```
+
+**4. Use Hierarchical Matching:**
+```javascript
+// If app is restricted to a country, regions and cities within that country are also allowed
+// Example: App restricted to "US" allows "US-CA" (California) and cities in US
+```
+
+**5. Cache Location Data:**
+```javascript
+// Cache country list to avoid repeated API calls
+let cachedCountries = null;
+
+async function getCountries() {
+ if (!cachedCountries) {
+ cachedCountries = await bosa.location.listCountries();
+ }
+ return cachedCountries;
+}
+```
+
+**6. Validate Location Codes:**
+```javascript
+// Always validate location codes before using
+async function checkLocation(code) {
+ try {
+ const country = await bosa.location.getCountry(code);
+ return country !== null;
+ } catch (error) {
+ return false;
+ }
+}
+```
+
+### 8.10 Location Restrictions in Plugin Routes
+
+Location restrictions are automatically enforced for all plugin routes:
+
+**Automatic Enforcement:**
+- All plugin API routes (`/api/plugins/:name/*`) are checked for location restrictions
+- Database, events, realtime, and config routes are all protected
+- No code changes needed in your plugin - enforcement is automatic
+
+**Bypassing Restrictions (Super Admin):**
+- Super admin users can bypass location restrictions
+- Useful for testing and administration
+
+**Example - Plugin with Location Restrictions:**
+```yaml
+# manifest.yaml
+name: regional-ecommerce
+location_availability:
+ mode: restricted
+ locations: ["US", "CA"]
+```
+
+**Result:**
+- Users from US/CA can access all plugin routes
+- Users from other countries receive 403 Forbidden
+- Super admins can access regardless of location
+
+### 8.11 Location Data Structure
+
+**Country Object:**
+```json
+{
+ "code": "US",
+ "name": "United States",
+ "iso3": "USA",
+ "numeric_code": 840,
+ "enabled": true
+}
+```
+
+**Region Object:**
+```json
+{
+ "id": 1,
+ "country_code": "US",
+ "code": "US-CA",
+ "name": "California",
+ "type": "state",
+ "enabled": true
+}
+```
+
+**City Object:**
+```json
+{
+ "id": 123,
+ "region_id": 1,
+ "country_code": "US",
+ "name": "Los Angeles",
+ "latitude": 34.0522,
+ "longitude": -118.2437,
+ "timezone": "America/Los_Angeles",
+ "enabled": true
+}
+```
+
+### 8.12 Troubleshooting
+
+**Problem: App always returns 403 Forbidden**
+
+**Solution:** Check location configuration:
+```bash
+# Get app location configuration
+curl -H "Authorization: Bearer TOKEN" \
+ http://localhost:3000/api/apps/my-app/locations
+
+# Verify location detection
+# Check request headers: X-BOSA-Location, CF-IPCountry, Accept-Language
+```
+
+**Problem: Location detection not working**
+
+**Solution:** Set explicit location header:
+```javascript
+// In your client, set location header
+fetch('/api/plugins/my-app/route', {
+ headers: {
+ 'X-BOSA-Location': 'country:US'
+ }
+});
+```
+
+**Problem: App should be global but shows as restricted**
+
+**Solution:** Update location configuration:
+```bash
+# Set app to global mode
+curl -X PUT http://localhost:3000/api/apps/my-app/locations \
+ -H "Authorization: Bearer TOKEN" \
+ -H "Content-Type: application/json" \
+ -d '{"mode": "global", "locations": []}'
+```
+
+---
+
+## 9. Database Operations
+
+### ⚠️ CRITICAL: NEVER Use Direct Database Communication
+
+**ABSOLUTE REQUIREMENT: All database operations MUST go through the BOSA SDK. Direct database connections are FORBIDDEN.**
+
+**Why This Rule Exists:**
+- BOSA provides database abstraction for multi-database support (SQLite, PostgreSQL, MySQL, MongoDB)
+- Automatic site scoping (multi-tenancy) requires SDK usage
+- Connection pooling and transaction management are handled by the kernel
+- Security and access control are enforced through the SDK
+- Using direct database connections defeats the purpose of using BOSA as a platform
+
+**❌ FORBIDDEN - Never Do This:**
+```javascript
+// ❌ NEVER use direct SQLite connections
+const sqlite3 = require('sqlite3');
+const db = new sqlite3.Database('database.db');
+
+// ❌ NEVER use direct PostgreSQL connections
+const { Client } = require('pg');
+const client = new Client({ connectionString: 'postgresql://...' });
+
+// ❌ NEVER use direct MySQL connections
+const mysql = require('mysql');
+const connection = mysql.createConnection({...});
+```
+
+**✅ REQUIRED - Always Do This:**
+```javascript
+// ✅ ALWAYS use BOSA SDK for database operations
+const { BOSA } = require('bosa-sdk-node');
+const bosa = new BOSA({...});
+await bosa.init();
+
+// All database operations through SDK
+const todos = await bosa.db.query('todos').get();
+const id = await bosa.db.query('todos').insert({...});
+await bosa.db.query('todos').where('id', '=', 1).update({...});
+```
+
+**This Rule Applies To:**
+- All BOSA apps/plugins regardless of language (Node.js, PHP, Python, Go, Lua)
+- All database operations (queries, inserts, updates, deletes, transactions)
+- All database types (SQLite, PostgreSQL, MySQL, MongoDB)
+
+**Violation Consequences:**
+- Apps using direct database connections will be rejected
+- Multi-tenancy will not work correctly
+- Database migrations may fail
+- Platform features (events, real-time, logging) will not integrate properly
+
+### 6.1 Creating Tables (Migrations)
+
+Create migration files in `migrations/` directory:
+
+```sql
+-- migrations/001_initial.sql
+CREATE TABLE IF NOT EXISTS todos (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ title TEXT NOT NULL,
+ description TEXT,
+ status TEXT NOT NULL DEFAULT 'pending',
+ user_id INTEGER NOT NULL,
+ created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ FOREIGN KEY (user_id) REFERENCES users(id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_todos_user_id ON todos(user_id);
+CREATE INDEX IF NOT EXISTS idx_todos_status ON todos(status);
+```
+
+**Migration Naming:**
+- Format: `001_description.sql`, `002_description.sql`, etc.
+- Must be sequential numbers
+- Applied automatically on plugin load
+
+### 6.2 Query Examples
+
+#### Select All
+
+```lua
+local todos = bosa.db.query("todos"):get()
+```
+
+#### Select with Conditions
+
+```lua
+local activeTodos = bosa.db.query("todos")
+ :where("status", "=", "active")
+ :where("user_id", "=", 1)
+ :get()
+```
+
+#### Select First
+
+```lua
+local todo = bosa.db.query("todos")
+ :where("id", "=", 1)
+ :first()
+```
+
+#### Pagination
+
+```lua
+local todos = bosa.db.query("todos")
+ :orderBy("created_at", "desc")
+ :limit(10)
+ :offset(20)
+ :get()
+```
+
+#### Count
+
+```lua
+local count = bosa.db.query("todos")
+ :where("status", "=", "pending")
+ :count()
+```
+
+#### Insert
+
+```lua
+local id = bosa.db.query("todos"):insert({
+ title = "New Todo",
+ status = "pending",
+ user_id = 1
+})
+```
+
+#### Update
+
+```lua
+bosa.db.query("todos")
+ :where("id", "=", 1)
+ :update({
+ status = "completed",
+ updated_at = os.date("!%Y-%m-%d %H:%M:%S")
+ })
+```
+
+#### Delete
+
+```lua
+bosa.db.query("todos")
+ :where("id", "=", 1)
+ :delete()
+```
+
+---
+
+## 10. Event System
+
+### 7.1 Subscribing to Events
+
+```lua
+function init()
+ -- Subscribe to events in init()
+ bosa.events.on("user.created", function(event)
+ bosa.log.info("New user created: " .. event.data.user_id)
+ -- Handle event
+ end)
+
+ return true
+end
+```
+
+### 7.2 Publishing Events
+
+```lua
+-- Publish event from handler
+function createTodo(request)
+ local id = bosa.db.query("todos"):insert(request.body)
+
+ -- Publish event
+ bosa.events.publish("todo.created", {
+ todo_id = id,
+ user_id = request.user.id
+ })
+
+ return {
+ status = 201,
+ body = { id = id }
+ }
+end
+```
+
+### 7.3 Event Data Structure
+
+```lua
+-- Event object structure:
+{
+ name = "event.name", -- Event name
+ data = { -- Event payload (table)
+ key1 = "value1",
+ key2 = "value2"
+ }
+}
+```
+
+---
+
+## 11. Real-Time Features
+
+### 8.1 Broadcasting Events
+
+```lua
+-- Broadcast to all connected WebSocket clients
+bosa.realtime.broadcast("channel.name", {
+ key1 = "value1",
+ key2 = "value2"
+})
+```
+
+### 8.2 Client-Side WebSocket
+
+```javascript
+// Connect to WebSocket
+const ws = new WebSocket('ws://localhost:3000/ws');
+
+// Send authentication token
+ws.onopen = () => {
+ const token = localStorage.getItem('bosa_token');
+ ws.send(JSON.stringify({ type: 'auth', token }));
+};
+
+// Listen for messages
+ws.onmessage = (event) => {
+ const message = JSON.parse(event.data);
+ if (message.type === 'event') {
+ console.log('Event:', message.event, message.data);
+ }
+};
+```
+
+---
+
+## 12. HTTP Routes
+
+### 12.1 Smart Namespace Routing
+
+BOSA uses a **smart namespace** routing system that makes plugin URLs shorter and cleaner while maintaining uniqueness.
+
+#### How It Works
+
+- **Plugin name becomes the first URL segment**: `/todo/` instead of `/plugins/todo/` (60% shorter!)
+- **Routes are registered relative to plugin name**: Route `/` becomes `/todo/` for the `todo` plugin
+- **API routes remain in global namespace**: `/api/todo/tasks` (no change)
+- **Reserved namespaces prevent conflicts**: Kernel routes like `/admin`, `/api`, `/login` are protected
+
+#### Route Registration Rules
+
+1. **API Routes** (`/api/...`): Registered exactly as written
+ ```yaml
+ routes:
+ - path: /api/todo/tasks
+ method: GET
+ handler: listTasks
+ ```
+ **Accessible at**: `GET /api/todo/tasks`
+
+2. **Frontend Routes** (`/` or `/page`): Auto-prefixed with plugin name
+ ```yaml
+ routes:
+ - path: /
+ method: GET
+ handler: Index
+ - path: /dashboard
+ method: GET
+ handler: Dashboard
+ ```
+ **Accessible at**:
+ - `GET /todo/` (for `todo` plugin)
+ - `GET /todo/dashboard` (for `todo` plugin)
+
+3. **Asset Routes** (`/assets/...`): Auto-prefixed with plugin name
+ ```yaml
+ routes:
+ - path: /assets/:filepath
+ method: GET
+ handler: StaticAssets
+ ```
+ **Accessible at**: `GET /todo/assets/index.js` (for `todo` plugin)
+
+#### Reserved Namespaces
+
+Plugin names cannot conflict with these reserved kernel routes:
+- `api`, `admin`, `login`, `profile`, `settings`, `dashboard`
+- `marketplace`, `developers`, `docs`, `sites`, `plugins`
+- `qa`, `logs`, `static`, `templates`, `ws`
+- `favicon.ico`, `vite.svg`
+
+**Plugin load will fail** if the name conflicts with a reserved namespace.
+
+#### Examples
+
+**Todo Plugin** (`name: todo`):
+```yaml
+routes:
+ # API routes - registered as-is
+ - path: /api/todo/tasks
+ method: GET
+ handler: listTasks
+
+ # Frontend route - becomes /todo/
+ - path: /
+ method: GET
+ handler: serveTodoPage
+
+ # Asset route - becomes /todo/assets/:filepath
+ - path: /assets/:filepath
+ method: GET
+ handler: StaticAssets
+```
+
+**Access URLs**:
+- `GET /api/todo/tasks` → API endpoint
+- `GET /todo/` → Frontend page
+- `GET /todo/assets/index.js` → Static asset
+
+### 12.2 Request Object
+
+```lua
+function handler(request)
+ -- request.method: HTTP method (GET, POST, PUT, DELETE, etc.)
+ -- request.path: Full path (/plugin-name/route) - includes plugin name prefix
+ -- request.params: Route parameters (for :id, :name, etc.)
+ -- request.query: Query parameters (?key=value)
+ -- request.body: Request body (JSON parsed)
+ -- request.headers: HTTP headers
+ -- request.user: Authenticated user (if route is protected)
+
+ return {
+ status = 200,
+ headers = {}, -- Optional HTTP headers
+ body = {} -- Response body (JSON object)
+ }
+end
+```
+
+### 12.3 Route Parameters
+
+```yaml
+routes:
+ - path: /todos/:id # :id is a parameter
+ method: GET
+ handler: getTodo
+```
+
+```lua
+function getTodo(request)
+ local id = request.params.id -- Access route parameter
+ -- ...
+end
+```
+
+**Note**: For route `/todos/:id` in `todo` plugin, the full URL is `/todo/todos/:id`, and `request.params.id` contains the parameter value.
+
+### 9.3 Query Parameters
+
+```lua
+function listTodos(request)
+ local limit = request.query.limit or 10
+ local offset = request.query.offset or 0
+ -- ...
+end
+```
+
+### 9.4 Request Body
+
+```lua
+function createTodo(request)
+ local title = request.body.title
+ local description = request.body.description
+ -- ...
+end
+```
+
+### 9.5 Response Format
+
+```lua
+return {
+ status = 200, -- HTTP status code
+ headers = { -- Optional headers
+ ["Content-Type"] = "application/json"
+ },
+ body = { -- Response body (JSON object)
+ key1 = "value1",
+ key2 = "value2"
+ }
+}
+```
+
+---
+
+## 13. Testing Plugins
+
+### 10.1 Manual Testing
+
+**Smart Namespace URLs** (plugin name is first segment):
+
+```bash
+# Test GET route (frontend route)
+curl http://localhost:3000/todo/
+
+# Test GET route with sub-path
+curl http://localhost:3000/todo/dashboard
+
+# Test API route (global namespace)
+curl http://localhost:3000/api/todo/tasks
+
+# Test POST route
+curl -X POST http://localhost:3000/api/todo/tasks \
+ -H "Content-Type: application/json" \
+ -d '{"title": "New Task"}'
+
+# Test with authentication
+curl http://localhost:3000/api/todo/tasks \
+ -H "Authorization: Bearer YOUR_TOKEN"
+
+# Test asset route
+curl http://localhost:3000/todo/assets/index.js
+```
+
+**Note**: Replace `todo` with your plugin name. The plugin name is the first URL segment (no `/plugins/` prefix).
+
+### 10.2 Testing Events
+
+```lua
+-- In plugin code
+bosa.events.publish("test.event", { test = true })
+
+-- Check server logs for event handling
+```
+
+---
+
+## 14. Best Practices
+
+### 11.1 Error Handling
+
+```lua
+function handler(request)
+ -- Validate input
+ if not request.body.title then
+ return {
+ status = 400,
+ body = { error = "Title is required" }
+ }
+ end
+
+ -- Try-catch pattern (Lua doesn't have try-catch, but check for errors)
+ local result, err = pcall(function()
+ -- Database operation
+ return bosa.db.query("todos"):insert(request.body)
+ end)
+
+ if not result then
+ bosa.log.error("Database error: " .. tostring(err))
+ return {
+ status = 500,
+ body = { error = "Internal server error" }
+ }
+ end
+
+ return {
+ status = 200,
+ body = { success = true }
+ }
+end
+```
+
+### 11.2 Logging
+
+**⚠️ CRITICAL REQUIREMENT: All plugins MUST implement proper error logging.**
+
+The BOSA error notification system automatically monitors logs and notifies super admin users when errors occur. This is a **critical feature** for production monitoring and debugging.
+
+#### Error Logging Checklist
+
+- [ ] All error conditions are logged with `bosa.log.error()`
+- [ ] All warning conditions are logged with `bosa.log.warn()`
+- [ ] Error messages include relevant context (user ID, resource ID, operation type)
+- [ ] Errors are logged before returning error responses
+- [ ] No sensitive data (passwords, tokens) is logged
+- [ ] Error messages are clear and actionable
+
+#### Logging Examples
+
+```lua
+-- ✅ GOOD: Detailed error logging
+function processPayment(request)
+ local result, err = pcall(function()
+ return process_payment_logic(request.body)
+ end)
+
+ if not result then
+ -- Log error with full context
+ bosa.log.error("Payment processing failed | Order ID: " .. request.body.order_id ..
+ " | Amount: " .. request.body.amount ..
+ " | User: " .. request.user.id ..
+ " | Error: " .. tostring(err))
+ return {
+ status = 500,
+ body = { error = "Payment processing failed" }
+ }
+ end
+
+ bosa.log.info("Payment processed successfully | Order ID: " .. request.body.order_id)
+ return {
+ status = 200,
+ body = { success = true }
+ }
+end
+
+-- ❌ BAD: Missing error logging
+function processPayment(request)
+ local result, err = pcall(function()
+ return process_payment_logic(request.body)
+ end)
+
+ if not result then
+ -- ❌ Error not logged - super admin won't be notified!
+ return {
+ status = 500,
+ body = { error = "Payment processing failed" }
+ }
+ end
+
+ return {
+ status = 200,
+ body = { success = true }
+ }
+end
+```
+
+#### Logging Best Practices
+
+1. **Log Immediately:** Log errors as soon as they occur, don't delay
+2. **Include Context:** Add relevant information to help debugging:
+ - User ID (if applicable)
+ - Resource ID (order ID, todo ID, etc.)
+ - Operation type (create, update, delete)
+ - Input parameters (sanitized, no sensitive data)
+3. **Use Structured Format:** `"Operation failed | Context: value | Error: message"`
+4. **Test Error Logging:** Verify errors appear in `/logs` page and trigger notifications
+5. **Monitor Notifications:** Super admins will receive notifications for all errors and warnings
+
+#### Error Notification Flow
+
+```
+1. Plugin logs error → bosa.log.error("message")
+2. Log added to buffer → LogBuffer.Add("error", "message", "plugin-name")
+3. ErrorMonitor detects error → Checks every 2 seconds
+4. Notification created → For each super admin user
+5. Notification appears → In notification bell icon
+6. Super admin clicks → Opens /logs page with error highlighted
+```
+
+#### Viewing and Managing Logs
+
+**Via Web UI:**
+- Navigate to `/logs` page (requires authentication)
+- Filter by level: `error`, `warning`, `info`, `debug`, or `all`
+- Click on log entries to view details
+- Use URL parameter `?id=` to jump to specific log entry
+
+**Via CLI:**
+```bash
+# View logs for specific plugin
+bosa logs my-plugin
+
+# View all logs (requires server running)
+# Navigate to http://localhost:3000/logs
+```
+
+**Via API:**
+```bash
+# Get error logs
+curl -H "Authorization: Bearer TOKEN" \
+ http://localhost:3000/api/logs?level=error
+
+# Get specific log entry
+curl -H "Authorization: Bearer TOKEN" \
+ http://localhost:3000/api/logs?id=123
+```
+
+#### Production Considerations
+
+- **Log Files:** In production mode (`bosa serve prod`), logs are written to `./logs/bosa-YYYY-MM-DD.log`
+- **Log Buffer:** In-memory buffer (default: 1000 entries) for quick access
+- **Log Retention:** Log files are kept per day, rotate automatically
+- **Performance:** Logging is non-blocking and optimized for performance
+- **Monitoring:** Super admins are automatically notified of all errors and warnings
+
+### 11.3 Database Transactions
+
+Currently, BOSA doesn't support explicit transactions in Lua API. Use error handling and validation instead.
+
+### 11.4 Security
+
+- **Input Validation:** Always validate input data
+- **SQL Injection:** Use parameterized queries (bosa.db API handles this)
+- **Authentication:** Protected routes automatically require authentication
+- **Authorization:** Check user permissions in handlers
+
+---
+
+## 15. Examples
+
+### 12.1 Complete Todo Plugin
+
+See `plugins/todo/` for a complete example.
+
+### 12.2 Simple Counter Plugin
+
+```yaml
+# manifest.yaml
+name: counter
+version: 1.0.0
+description: Simple counter plugin
+author: BOSA Team
+
+runtime:
+ type: lua
+ entry: main.lua
+
+routes:
+ - path: /increment
+ method: POST
+ handler: increment
+ - path: /value
+ method: GET
+ handler: getValue
+```
+
+```lua
+-- main.lua
+local count = 0
+
+function init()
+ -- Initialize counter from database if exists
+ local row = bosa.db.query("counter")
+ :where("id", "=", 1)
+ :first()
+
+ if row then
+ count = row.value
+ else
+ bosa.db.query("counter"):insert({ id = 1, value = 0 })
+ end
+
+ return true
+end
+
+function increment(request)
+ count = count + 1
+
+ bosa.db.query("counter")
+ :where("id", "=", 1)
+ :update({ value = count })
+
+ bosa.realtime.broadcast("counter.updated", { value = count })
+
+ return {
+ status = 200,
+ body = { value = count }
+ }
+end
+
+function getValue(request)
+ return {
+ status = 200,
+ body = { value = count }
+ }
+end
+```
+
+---
+
+## 13. Plugin Distribution
+
+### 13.1 Creating Plugin Zip
+
+```bash
+# Create zip file from plugin directory
+cd /path/to/my-plugin
+zip -r my-plugin.zip . -x "*.git*" -x "*.DS_Store"
+
+# Or on Windows (PowerShell)
+Compress-Archive -Path .\* -DestinationPath my-plugin.zip
+```
+
+**Include in zip:**
+- ✅ `manifest.yaml` (required)
+- ✅ `main.lua` (required)
+- ✅ `migrations/` (if any)
+- ✅ `assets/` (if any)
+- ❌ `.git/` (exclude)
+- ❌ `node_modules/` (exclude)
+- ❌ `.env` files (exclude)
+
+### 13.2 Plugin Configuration
+
+Plugins can store configuration in the database:
+
+**Via Lua API:**
+```lua
+-- Set configuration
+bosa.config.set("my-plugin", "api_key", "secret")
+
+-- Get configuration
+local apiKey = bosa.config.get("my-plugin", "api_key")
+```
+
+**Via REST API:**
+```bash
+# Get all config
+GET /api/plugins/my-plugin/config
+Authorization: Bearer YOUR_TOKEN
+
+# Set config
+PUT /api/plugins/my-plugin/config/api_key
+Authorization: Bearer YOUR_TOKEN
+Content-Type: application/json
+Body: { "value": "secret-key" }
+
+# Delete config
+DELETE /api/plugins/my-plugin/config/api_key
+Authorization: Bearer YOUR_TOKEN
+```
+
+### 13.3 Plugin Location
+
+**Configurable in `config.yaml`:**
+```yaml
+plugins:
+ directory: "/path/to/plugins" # Change this to your preferred location
+ hot_reload: false
+```
+
+**Benefits:**
+- Plugins can be in separate repositories
+- No hardcoded paths
+- Easy to move plugins between environments
+- Supports both relative and absolute paths
+
+## 14. Testing Your Plugin
+
+### 14.1 Testing Strategy
+
+BOSA provides comprehensive testing infrastructure for plugins:
+
+- **Unit Tests:** Test individual functions in isolation
+- **Integration Tests:** Test plugin loading, routes, database, events, WebSocket
+- **E2E Tests:** Test complete workflows (init → serve → use plugin)
+
+### 14.2 Integration Tests
+
+Integration tests verify that your plugin works correctly with BOSA's infrastructure.
+
+**Test Coverage:**
+- ✅ Plugin loading from different sources (directory, zip, git)
+- ✅ Route handling with HTTP requests
+- ✅ Database operations through plugin API
+- ✅ Event publishing and subscribing
+- ✅ WebSocket connections and real-time broadcasting
+
+**Example Integration Test:**
+
+```go
+// tests/integration/plugin_test.go
+func TestMyPlugin_Loading(t *testing.T) {
+ helper := NewTestHelper(t)
+ defer helper.Cleanup()
+
+ pluginDir := helper.CreateTestPlugin(t, "my-plugin", routes)
+ plugin, err := helper.Manager.LoadPlugin(pluginDir)
+ // ... verify plugin loaded correctly
+}
+```
+
+### 14.3 E2E Tests
+
+End-to-end tests verify complete user workflows.
+
+**Test Coverage:**
+- ✅ `bosa init` → `bosa serve` → use plugin
+- ✅ Login → access plugin → logout
+- ✅ Create data → query data → delete data
+
+**Running E2E Tests:**
+
+```bash
+# Build BOSA binary first
+go build -o bosa.exe ./cmd/bosa
+
+# Run E2E tests
+go test ./tests/e2e/... -v
+```
+
+**Note:** E2E tests require a built BOSA binary and may take longer to run. Use `-short` flag to skip E2E tests:
+
+```bash
+go test ./tests/... -short # Skips E2E tests
+```
+
+### 14.4 Testing Best Practices
+
+1. **Test Plugin Loading:**
+ - Test with valid manifest
+ - Test with invalid manifest (should fail gracefully)
+ - Test with missing entry file
+ - Test with migrations
+
+2. **Test Routes:**
+ - Test all HTTP methods (GET, POST, PUT, DELETE)
+ - Test parameterized routes (`/items/:id`)
+ - Test query parameters
+ - Test request body parsing
+ - Test error responses (404, 400, 500)
+
+3. **Test Database Operations:**
+ - Test CRUD operations
+ - Test user isolation (users only see their own data)
+ - Test migrations run correctly
+ - Test complex queries (joins, aggregations)
+
+4. **Test Events:**
+ - Test event publishing
+ - Test event subscription
+ - Test event data structure
+
+5. **Test Real-Time:**
+ - Test WebSocket connections
+ - Test real-time broadcasting
+ - Test channel-based messaging
+
+### 14.5 Test Helper Utilities
+
+BOSA provides test helpers in `tests/integration/plugin_test.go`:
+
+- `NewTestHelper(t)` - Creates test environment with database, event bus, server
+- `CreateTestPlugin(t, name, routes)` - Creates a test plugin
+- `MakeRequest(t, method, path, body)` - Makes HTTP request
+- `ParseJSONResponse(t, resp)` - Parses JSON response
+
+**Example Usage:**
+
+```go
+helper := NewTestHelper(t)
+defer helper.Cleanup()
+
+pluginDir := helper.CreateTestPlugin(t, "test-plugin", []map[string]string{
+ {"path": "/test", "method": "GET", "handler": "test_handler"},
+})
+
+plugin, err := helper.Manager.LoadPlugin(pluginDir)
+// ... test plugin
+```
+
+### 14.6 Continuous Integration
+
+BOSA tests are designed to run in CI/CD pipelines:
+
+```yaml
+# Example GitHub Actions workflow
+- name: Run Tests
+ run: |
+ go test ./tests/integration/... -v
+ go test ./tests/e2e/... -v -short # Skip long E2E tests in CI
+```
+
+**Test Coverage Requirements:**
+- Integration tests: 85%+ coverage
+- All tests must pass before merge
+- E2E tests run on pull requests (optional, can be skipped with `-short`)
+
+---
+
+---
+
+## 15. Multi-Language Runtime Support
+
+BOSA supports multiple runtime types beyond Lua, allowing you to build plugins in your preferred language.
+
+### 15.1 Node.js Runtime
+
+#### Plugin Structure
+
+```
+plugins/my-node-plugin/
+├── manifest.yaml
+├── package.json
+├── index.js # Entry file
+└── node_modules/ # Dependencies
+```
+
+#### Manifest Configuration
+
+```yaml
+name: my-node-plugin
+version: 1.0.0
+runtime:
+ type: nodejs
+ entry: index.js
+routes:
+ - path: /api/items
+ method: GET
+ handler: listItems
+```
+
+#### Entry File Example
+
+```javascript
+// index.js
+const { BOSA } = require('bosa-sdk-node');
+
+const plugin = new BOSA();
+await plugin.init();
+
+// Register route handlers
+plugin.route('GET', '/api/items', async (req) => {
+ const items = await plugin.db.query('items')
+ .where('user_id', '=', req.user.id)
+ .get();
+
+ return {
+ status: 200,
+ body: { items }
+ };
+});
+
+// Start plugin server
+plugin.start(process.env.PLUGIN_PORT || 3001);
+```
+
+#### SDK Installation
+
+```bash
+cd plugins/my-node-plugin
+npm install bosa-sdk-node
+```
+
+**Features:**
+- Automatic dependency installation (`npm install`)
+- Separate Node.js process (port range: 3001-4000)
+- Full access to BOSA APIs via SDK
+- TypeScript support
+
+### 15.2 PHP Runtime
+
+#### Plugin Structure
+
+```
+plugins/my-php-plugin/
+├── manifest.yaml
+├── composer.json
+├── index.php # Entry file
+└── vendor/ # Dependencies
+```
+
+#### Manifest Configuration
+
+```yaml
+name: my-php-plugin
+version: 1.0.0
+runtime:
+ type: php
+ entry: index.php
+routes:
+ - path: /api/users
+ method: GET
+ handler: listUsers
+```
+
+#### Entry File Example
+
+```php
+ getenv('BOSA_KERNEL_URL') ?: 'http://localhost:3000',
+]);
+
+$plugin->route('GET', '/api/users', function($req) {
+ $users = $plugin->db->query('users')
+ ->where('status', '=', 'active')
+ ->get();
+
+ return [
+ 'status' => 200,
+ 'body' => ['users' => $users]
+ ];
+});
+
+$plugin->start();
+```
+
+**Features:**
+- Automatic dependency installation (`composer install`)
+- PHP built-in server (port range: 4001-5000)
+- Full access to BOSA APIs via SDK (when available)
+
+### 15.3 Go Runtime
+
+#### Plugin Structure
+
+```
+plugins/my-go-plugin/
+├── manifest.yaml
+├── main.go # Entry file
+├── go.mod
+└── go.sum
+```
+
+#### Manifest Configuration
+
+```yaml
+name: my-go-plugin
+version: 1.0.0
+runtime:
+ type: go
+ entry: main.go
+routes:
+ - path: /api/data
+ method: GET
+ handler: getData
+ - path: /assets/:filepath
+ method: GET
+ handler: StaticAssets # Optional: for custom static asset handling
+```
+
+**Route Registration Notes:**
+- Routes defined in manifest are automatically prefixed with `/plugins/[plugin-name]/` by BOSA kernel
+- Example: Route `/api/data` becomes `/plugins/my-go-plugin/api/data`
+- Your Go server should register routes **without** the `/plugins/[plugin-name]` prefix
+- The kernel forwards requests to your plugin with the original manifest path
+
+#### Entry File Example
+
+```go
+// main.go
+package main
+
+import (
+ "net/http"
+ "os"
+)
+
+func main() {
+ port := os.Getenv("PLUGIN_PORT")
+ if port == "" {
+ port = "5001"
+ }
+
+ http.HandleFunc("/api/data", func(w http.ResponseWriter, r *http.Request) {
+ // Use BOSA SDK (when available) or HTTP client
+ w.WriteHeader(http.StatusOK)
+ w.Write([]byte(`{"data": "Hello from Go plugin"}`))
+ })
+
+ http.ListenAndServe(":"+port, nil)
+}
+```
+
+**Features:**
+- Automatic compilation to binary at install time
+- Separate Go process (port range: 5001-6000)
+- Best performance for CPU-intensive operations
+
+### 15.4 Python Runtime
+
+#### Plugin Structure
+
+```
+plugins/my-python-plugin/
+├── manifest.yaml
+├── requirements.txt
+├── main.py # Entry file
+└── venv/ # Virtual environment (optional)
+```
+
+#### Manifest Configuration
+
+```yaml
+name: my-python-plugin
+version: 1.0.0
+runtime:
+ type: python
+ entry: main.py
+routes:
+ - path: /api/data
+ method: GET
+ handler: getData
+```
+
+#### Entry File Example
+
+```python
+# main.py
+from flask import Flask, request, jsonify
+import os
+
+app = Flask(__name__)
+
+@app.route('/api/data', methods=['GET'])
+def get_data():
+ # Use BOSA SDK (when available) or HTTP client
+ return jsonify({'data': 'Hello from Python plugin'}), 200
+
+@app.route('/health', methods=['GET'])
+def health():
+ return jsonify({'status': 'ok'}), 200
+
+if __name__ == '__main__':
+ port = int(os.getenv('PLUGIN_PORT', 6001))
+ app.run(host='localhost', port=port, debug=False)
+```
+
+**Features:**
+- Automatic dependency installation (`pip install -r requirements.txt`)
+- Separate Python process (port range: 6001-7000)
+- Support for Flask, FastAPI, or any HTTP framework
+- Python 3.x support (python3 or python command)
+
+**Requirements:**
+- Python 3.x must be installed
+- Plugins should start their own HTTP server
+- Health endpoint at `/health` is recommended
+
+### 15.5 Runtime Port Ranges
+
+Each runtime type uses a separate port range to avoid conflicts:
+
+| Runtime | Port Range | Default Port |
+|---------|-----------|--------------|
+| Node.js | 3001-4000 | 3001 |
+| PHP | 4001-5000 | 4001 |
+| Go | 5001-6000 | 5001 |
+| Python | 6001-7000 | 6001 |
+
+Ports are automatically assigned by the BOSA kernel when a plugin starts.
+
+### 15.6 Environment Variables
+
+All process-based runtimes receive these environment variables:
+
+- `PLUGIN_PORT` - Port assigned to the plugin
+- `PLUGIN_NAME` - Plugin name from manifest
+- `BOSA_PLUGIN_PATH` - Absolute path to plugin directory
+- `BOSA_KERNEL_URL` - Kernel API URL (default: http://localhost:3000)
+- `BOSA_DEV_MODE` - Set to "true" if dev mode enabled
+
+### 15.6 SDK Status
+
+| Runtime | SDK Status | Notes |
+|---------|-----------|-------|
+| Node.js | ✅ Available | `bosa-sdk-node` package |
+| PHP | ⏳ Planned | Coming soon |
+| Go | ⏳ Planned | Coming soon |
+
+---
+
+---
+
+## 16. CLI Process Management
+
+BOSA provides CLI commands for monitoring and managing running plugins.
+
+### 16.1 List Running Plugins (`bosa ps`)
+
+View all running plugins with process information:
+
+```bash
+bosa ps
+```
+
+**Output includes:**
+- Plugin name
+- Runtime type (lua, nodejs, php, go)
+- Status (running, stopped, error)
+- Process ID (PID) - for process-based runtimes
+- Port number - for process-based runtimes
+- Uptime - time since plugin started
+- Plugin URL - HTTP endpoint
+- Health errors (if any)
+
+**Example output:**
+```
+Running Plugins:
+----------------------------------------------------------------------------------------------------
+NAME RUNTIME STATUS PID PORT UPTIME URL
+----------------------------------------------------------------------------------------------------
+my-node-plugin nodejs running 12345 3001 2h 15m http://localhost:3001
+my-php-plugin php running 12346 4001 1h 30m http://localhost:4001
+my-go-plugin go running 12347 5001 45m http://localhost:5001
+todo lua running - - 5h 12m -
+----------------------------------------------------------------------------------------------------
+Total: 4 plugin(s)
+```
+
+**Note:** Requires BOSA server to be running (`bosa serve`).
+
+### 16.2 View Plugin Logs (`bosa logs `)
+
+View logs for a specific plugin:
+
+```bash
+bosa logs my-node-plugin
+```
+
+**Features:**
+- Filters log entries containing plugin name
+- Shows timestamp, level, message, and source
+- Displays last 100 entries
+- Provides link to full logs UI
+
+**Example output:**
+```
+Logs for plugin 'my-node-plugin':
+====================================================================================================
+[2025-11-27 14:30:15] INFO | Plugin 'my-node-plugin' started successfully
+[2025-11-27 14:30:16] INFO | Route registered: GET /api/items
+ Source: plugin
+[2025-11-27 14:31:20] ERROR | Database query failed: connection timeout
+ Source: plugin
+====================================================================================================
+Total: 2 log entry/entries
+
+Note: Only showing last 100 entries. View all logs at http://localhost:3000/logs
+```
+
+**Note:** Requires BOSA server to be running and plugin must be loaded.
+
+---
+
+## 16. Error Logging and Monitoring
+
+**⚠️ CRITICAL: This section is MANDATORY reading for all plugin developers.**
+
+BOSA includes an automatic error notification system that monitors logs and notifies super admin users when errors occur. **All plugins MUST implement proper error logging** to ensure issues are detected and resolved quickly.
+
+### 13.1 Error Notification System Overview
+
+The BOSA error notification system:
+
+1. **Automatically monitors** all log entries in real-time (checks every 2 seconds)
+2. **Detects errors and warnings** from all plugins and the kernel
+3. **Creates notifications** for all super admin users when errors/warnings occur
+4. **Provides direct links** to error log entries for quick debugging
+5. **Prevents duplicates** - same error won't create multiple notifications
+
+**This system is ALWAYS ACTIVE** in both development and production modes.
+
+### 13.2 Mandatory Error Logging Requirements
+
+**ALL plugins MUST:**
+
+1. ✅ **Log all errors** using `bosa.log.error()` (or SDK equivalent) before returning error responses
+2. ✅ **Log all warnings** using `bosa.log.warn()` (or SDK equivalent) for recoverable issues
+3. ✅ **Include context** in error messages (user ID, resource ID, operation type)
+4. ✅ **Test error logging** to ensure errors appear in logs and trigger notifications
+5. ✅ **Never log sensitive data** (passwords, tokens, personal information)
+
+**Failure to implement proper error logging may result in:**
+- Critical issues going unnoticed
+- Delayed problem resolution
+- Poor user experience
+- Production incidents
+
+### 13.3 Error Logging Implementation by Language
+
+#### Lua Plugins
+
+```lua
+-- ✅ REQUIRED: Always log errors with context
+function createTodo(request)
+ -- Validate input
+ if not request.body.title then
+ bosa.log.warn("CreateTodo: Missing title parameter | User: " .. request.user.id)
+ return {
+ status = 400,
+ body = { error = "Title is required" }
+ }
+ end
+
+ -- Attempt database operation
+ local result, err = pcall(function()
+ return bosa.db.query("todos"):insert({
+ title = request.body.title,
+ user_id = request.user.id
+ })
+ end)
+
+ if not result then
+ -- ✅ MUST log error before returning
+ bosa.log.error("CreateTodo: Database insert failed | User: " .. request.user.id ..
+ " | Title: " .. request.body.title ..
+ " | Error: " .. tostring(err))
+ return {
+ status = 500,
+ body = { error = "Internal server error" }
+ }
+ end
+
+ bosa.log.info("CreateTodo: Todo created successfully | ID: " .. result .. " | User: " .. request.user.id)
+ return {
+ status = 201,
+ body = { id = result }
+ }
+end
+```
+
+#### Node.js Plugins (bosa-sdk-node)
+
+```javascript
+// ✅ REQUIRED: Use SDK logging methods
+const { BOSA } = require('bosa-sdk-node');
+const plugin = new BOSA();
+
+plugin.route('POST', '/todos', async (req) => {
+ try {
+ if (!req.body.title) {
+ plugin.log.warn(`CreateTodo: Missing title | User: ${req.user.id}`);
+ return {
+ status: 400,
+ body: { error: 'Title is required' }
+ };
+ }
+
+ const id = await plugin.db.query('todos').insert({
+ title: req.body.title,
+ user_id: req.user.id
+ });
+
+ plugin.log.info(`CreateTodo: Todo created | ID: ${id} | User: ${req.user.id}`);
+ return {
+ status: 201,
+ body: { id }
+ };
+ } catch (err) {
+ // ✅ MUST log error before returning
+ plugin.log.error(`CreateTodo: Database insert failed | User: ${req.user.id} | Title: ${req.body.title} | Error: ${err.message}`);
+ return {
+ status: 500,
+ body: { error: 'Internal server error' }
+ };
+ }
+});
+```
+
+#### PHP Plugins (bosa-sdk-php)
+
+```php
+route('POST', '/todos', function($req) use ($plugin) {
+ try {
+ if (!isset($req->body['title'])) {
+ $plugin->log->warn("CreateTodo: Missing title | User: {$req->user->id}");
+ return [
+ 'status' => 400,
+ 'body' => ['error' => 'Title is required']
+ ];
+ }
+
+ $id = $plugin->db->query('todos')->insert([
+ 'title' => $req->body['title'],
+ 'user_id' => $req->user->id
+ ]);
+
+ $plugin->log->info("CreateTodo: Todo created | ID: {$id} | User: {$req->user->id}");
+ return [
+ 'status' => 201,
+ 'body' => ['id' => $id]
+ ];
+ } catch (Exception $e) {
+ // ✅ MUST log error before returning
+ $plugin->log->error("CreateTodo: Database insert failed | User: {$req->user->id} | Title: {$req->body['title']} | Error: {$e->getMessage()}");
+ return [
+ 'status' => 500,
+ 'body' => ['error' => 'Internal server error']
+ ];
+ }
+});
+```
+
+#### Python Plugins (bosa-sdk-python)
+
+```python
+# ✅ REQUIRED: Use SDK logging methods
+from bosa import BOSA
+
+plugin = BOSA()
+
+@plugin.route('POST', '/todos')
+def create_todo(req):
+ try:
+ if not req.body.get('title'):
+ plugin.log.warn(f"CreateTodo: Missing title | User: {req.user.id}")
+ return {
+ 'status': 400,
+ 'body': {'error': 'Title is required'}
+ }
+
+ todo_id = plugin.db.query('todos').insert({
+ 'title': req.body['title'],
+ 'user_id': req.user.id
+ })
+
+ plugin.log.info(f"CreateTodo: Todo created | ID: {todo_id} | User: {req.user.id}")
+ return {
+ 'status': 201,
+ 'body': {'id': todo_id}
+ }
+ except Exception as e:
+ # ✅ MUST log error before returning
+ plugin.log.error(f"CreateTodo: Database insert failed | User: {req.user.id} | Title: {req.body.get('title')} | Error: {str(e)}")
+ return {
+ 'status': 500,
+ 'body': {'error': 'Internal server error'}
+ }
+```
+
+#### Go Plugins (bosa-sdk-go)
+
+```go
+// ✅ REQUIRED: Use SDK logging methods
+import "github.com/bosa/bosa-sdk-go"
+import "fmt"
+
+plugin := bosa.New()
+
+plugin.Route("POST", "/todos", func(req *bosa.Request) *bosa.Response {
+ if req.Body["title"] == nil {
+ plugin.Log().Warn(fmt.Sprintf("CreateTodo: Missing title | User: %v", req.User.ID))
+ return &bosa.Response{
+ Status: 400,
+ Body: map[string]interface{}{"error": "Title is required"},
+ }
+ }
+
+ id, err := plugin.DB().Query("todos").Insert(map[string]interface{}{
+ "title": req.Body["title"],
+ "user_id": req.User.ID,
+ })
+
+ if err != nil {
+ // ✅ MUST log error before returning
+ plugin.Log().Error(fmt.Sprintf("CreateTodo: Database insert failed | User: %v | Title: %v | Error: %v",
+ req.User.ID, req.Body["title"], err))
+ return &bosa.Response{
+ Status: 500,
+ Body: map[string]interface{}{"error": "Internal server error"},
+ }
+ }
+
+ plugin.Log().Info(fmt.Sprintf("CreateTodo: Todo created | ID: %v | User: %v", id, req.User.ID))
+ return &bosa.Response{
+ Status: 201,
+ Body: map[string]interface{}{"id": id},
+ }
+})
+```
+
+### 13.4 Error Message Format
+
+**Standard Format:**
+```
+"[Operation Name]: [What failed] | [Context Key]: [Value] | Error: [Error message]"
+```
+
+**Examples:**
+```lua
+-- ✅ GOOD: Clear, structured error message
+bosa.log.error("CreateTodo: Database insert failed | User: 123 | Title: My Todo | Error: connection timeout")
+
+-- ✅ GOOD: Include all relevant context
+bosa.log.error("ProcessPayment: Payment gateway error | Order ID: 456 | Amount: 99.99 | User: 123 | Error: invalid API key")
+
+-- ❌ BAD: Vague error message
+bosa.log.error("Error occurred")
+
+-- ❌ BAD: Missing context
+bosa.log.error("Database error")
+```
+
+### 13.5 Viewing Error Logs
+
+#### Via Web UI
+
+1. **Navigate to `/logs` page** (requires authentication)
+2. **Filter by level:** Click buttons to filter by `error`, `warning`, `info`, `debug`, or `all`
+3. **View specific log:** Click on a log entry or use URL `?id=` to jump to specific entry
+4. **From notification:** Click notification link to jump directly to error log entry
+
+#### Via CLI
+
+```bash
+# View logs for specific plugin
+bosa logs my-plugin
+
+# View all logs (requires server running)
+# Navigate to http://localhost:3000/logs
+```
+
+#### Via API
+
+```bash
+# Get error logs
+curl -H "Authorization: Bearer TOKEN" \
+ http://localhost:3000/api/logs?level=error
+
+# Get specific log entry
+curl -H "Authorization: Bearer TOKEN" \
+ http://localhost:3000/api/logs?id=123
+
+# Get warning logs
+curl -H "Authorization: Bearer TOKEN" \
+ http://localhost:3000/api/logs?level=warning
+```
+
+### 13.6 Error Notification Details
+
+When an error or warning is logged, super admin users receive a notification with:
+
+- **Title:** "System Error" or "System Warning" (+ source plugin name if available)
+- **Message:** Truncated error message (first 200 characters)
+- **Link:** Direct link to log entry (`/logs?level=error&id=`)
+- **Metadata:** Includes log_id, log_level, log_source, and timestamp
+
+**Notification Flow:**
+1. Error logged → Added to log buffer
+2. ErrorMonitor detects error (checks every 2 seconds)
+3. System checks for duplicate notifications (by log_id)
+4. Notification created for each super admin user
+5. Notification appears in notification bell icon
+6. Super admin clicks notification → Opens `/logs` page with error highlighted
+
+### 13.7 Testing Error Logging
+
+**Before deploying your plugin, verify:**
+
+1. ✅ Errors are logged with `bosa.log.error()` or SDK equivalent
+2. ✅ Errors appear in `/logs` page
+3. ✅ Errors trigger notifications for super admin users
+4. ✅ Error messages include sufficient context for debugging
+5. ✅ No sensitive data is logged
+
+**Test Procedure:**
+
+```lua
+-- In your plugin, trigger a test error
+function testErrorLogging(request)
+ -- This should trigger a notification
+ bosa.log.error("TestError: This is a test error | Plugin: my-plugin | User: " .. request.user.id)
+ return {
+ status = 200,
+ body = { message = "Test error logged" }
+ }
+end
+```
+
+Then:
+1. Call the test endpoint
+2. Check `/logs` page - error should appear
+3. Check notification bell - super admin should receive notification
+4. Click notification - should jump to error in logs page
+
+### 13.8 Production Considerations
+
+- **Log Files:** In production mode (`bosa serve prod`), logs are written to `./logs/bosa-YYYY-MM-DD.log`
+- **Log Buffer:** In-memory buffer (default: 1000 entries) for quick access via UI
+- **Log Retention:** Log files are kept per day, rotate automatically
+- **Performance:** Logging is non-blocking and optimized for performance
+- **Monitoring:** Super admins are automatically notified of ALL errors and warnings
+- **No Configuration Needed:** Error notification system is always active
+
+### 13.9 Common Mistakes to Avoid
+
+❌ **Don't:**
+- Log errors without context
+- Skip error logging "because it's obvious"
+- Log sensitive data (passwords, tokens, credit cards)
+- Use `info` level for errors
+- Return error responses without logging
+
+✅ **Do:**
+- Always log errors before returning error responses
+- Include relevant context in error messages
+- Use appropriate log levels (error, warn, info)
+- Test error logging in development
+- Monitor notifications in production
+
+---
+
+## 17. Production Deployment with Nginx
+
+### 17.1 Overview
+
+BOSA can run behind nginx as a reverse proxy for production deployments. This setup provides:
+- SSL/TLS termination
+- Better static file performance
+- Compression and caching
+- Security headers
+- Rate limiting
+- Load balancing (if multiple instances)
+
+### 17.2 When to Use Nginx vs Internal Server
+
+**Use Nginx (Recommended for Production):**
+- Production deployments
+- Need SSL/TLS (HTTPS)
+- Want better static file performance
+- Require advanced features (rate limiting, caching)
+- Public-facing applications
+- High-traffic scenarios
+
+**Use Internal Server (BOSA's built-in server):**
+- Development and testing
+- Simple deployments without SSL
+- Internal applications
+- Quick prototyping
+- Single-user scenarios
+
+### 17.3 Quick Setup
+
+**Linux/macOS:**
+```bash
+# Run setup script
+sudo ./scripts/setup-nginx.sh
+
+# Follow interactive prompts:
+# - Choose template (basic, development, production, static-optimized)
+# - Enter BOSA port (default: 3000)
+# - Enter domain name
+# - Enter BOSA installation path
+```
+
+**Windows:**
+```powershell
+# Run setup script (as Administrator)
+.\scripts\setup-nginx.ps1
+
+# Follow interactive prompts
+```
+
+**Manual Setup:**
+1. Install nginx (see [NGINX_SETUP.md](NGINX_SETUP.md))
+2. Choose a template from `docs/nginx/`
+3. Replace template variables
+4. Configure BOSA: set `behind_proxy: true` in `config.yaml`
+5. Restart BOSA
+
+### 17.4 Configuration
+
+**BOSA Configuration (`config.yaml`):**
+```yaml
+server:
+ port: 3000
+ host: "0.0.0.0"
+ behind_proxy: true # Enable proxy header trust
+```
+
+**Why `behind_proxy: true`?**
+- BOSA will trust `X-Forwarded-For` and `X-Real-IP` headers for real client IPs
+- BOSA will trust `X-Forwarded-Proto` header for HTTPS detection
+- Logs will show real client IPs instead of proxy IP
+
+### 17.5 SSL/TLS Setup
+
+For production with HTTPS:
+
+```bash
+# Run SSL setup script (Linux only)
+sudo ./scripts/setup-nginx-ssl.sh
+
+# Or manually (see NGINX_SSL_SETUP.md)
+sudo certbot --nginx -d yourdomain.com
+```
+
+### 17.6 Available Templates
+
+1. **`basic.conf`** - Simple HTTP reverse proxy
+2. **`development.conf`** - Development with verbose logging
+3. **`production.conf`** - Production with SSL/TLS and security headers
+4. **`static-optimized.conf`** - High-performance static file serving
+
+See [nginx/README.md](nginx/README.md) for detailed template descriptions.
+
+### 17.7 Documentation
+
+- **[NGINX_SETUP.md](NGINX_SETUP.md)** - Complete setup guide for all platforms
+- **[NGINX_SSL_SETUP.md](NGINX_SSL_SETUP.md)** - SSL/TLS certificate setup
+- **[NGINX_PRODUCTION.md](NGINX_PRODUCTION.md)** - Production deployment best practices
+- **[nginx/README.md](nginx/README.md)** - Configuration templates guide
+
+### 17.8 Troubleshooting
+
+**502 Bad Gateway:**
+- Verify BOSA is running: `./bosa serve`
+- Check BOSA port matches nginx config
+- Verify `behind_proxy: true` in config.yaml
+
+**Real Client IP Not Logged:**
+- Ensure `behind_proxy: true` in BOSA config.yaml
+- Verify nginx sends `X-Forwarded-For` and `X-Real-IP` headers
+- Restart BOSA after config changes
+
+**WebSocket Connection Fails:**
+- Verify `/ws` location block has WebSocket upgrade headers
+- Check nginx version (requires 1.3.13+)
+
+See [NGINX_SETUP.md](NGINX_SETUP.md) for complete troubleshooting guide.
+
+---
+
+## Next Steps
+
+- Review existing plugins (`plugins/todo/`, `plugins/crm/`)
+- Explore BOSA API documentation
+- Build your first plugin in your preferred language
+- **Implement proper error logging** (see Section 13 - MANDATORY)
+- Write tests for your plugin
+- Use `bosa ps` and `bosa logs` to monitor your plugins
+- **Set up nginx for production** (see Section 17)
+- Share your plugins with the community
+
+**Happy coding!** 🚀
+
+