mabdalla/bp_wb
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Initial commit: Add documentation and issue tracking for BP_WB project

Browse source
This commit is contained in:
mmabdalla 2025-12-28 14:38:51 +02:00
commit 744c8a833b
12 changed files with 10290 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

19
.cursor/rules/00-base-safety.mdc Normal file
View file

@ -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.

890
.cursor/rules/bosa_constitution.md Normal file
View file

@ -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)*

11
.cursor/rules/change-discipline.mdc Normal file
View file

@ -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.

10
.cursor/rules/no-hallucinations.mdc Normal file
View file

@ -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.

13
.cursor/rules/testing-first.mdc Normal file
View file

@ -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.

5
.cursor/worktrees.json Normal file
View file

@ -0,0 +1,5 @@
{
"setup-worktree": [
"npm install"
]
}

51
.gitignore vendored Normal file
View file

@ -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

43
README.md Normal file
View file

@ -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]

387
docs/BP_WB_DEVELOPMENT_ROADMAP.md Normal file
View file

@ -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

659
docs/BP_WB_FEATURES_LIST.md Normal file
View file

@ -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

1659
docs/BP_WB_LINEAR_ISSUES.md Normal file
View file

File diff suppressed because it is too large Load diff

6543
docs/DEVELOPER_GUIDE.md Normal file
View file

File diff suppressed because it is too large Load diff