@africode/core 5.0.0

package/AFRICODE_FRAMEWORK_GUIDE.md

@@ -0,0 +1,707 @@
+# AfriCode Framework - Comprehensive Developer Guide
+
+**Version:** 4.0.1  
+**For IDE Agents:** VS Code Copilot, Anthropic Claude, GitHub Copilot, Antigravity, and similar AI-assisted development environments.
+
+---
+
+## 🌍 Framework Philosophy
+
+**AfriCode is not just code—it's a commitment to African digital sovereignty.**
+
+AfriCode v4.0.1 is a production-ready, full-stack framework built on Bun that prioritizes:
+
+- **Performance**: 10x faster than Node.js with native SQLite, WebAssembly, and zero-config TypeScript
+- **Cultural Authenticity**: Procedurally generated African tribal patterns (Kente, Ndebele, Masai, Zulu, Hadzabe, Kuba, Shuka)
+- **Developer Sovereignty**: Frameworks should celebrate heritage, not erase it
+- **Modern Architecture**: WebSocket real-time, advanced ORM, middleware pipeline, 33 production-ready Web Components
+
+---
+
+## 📦 Core Stack
+
+### Runtime: Bun v1.3.12+
+
+- **Why Bun?** Ultra-fast JavaScript runtime with native SQLite support, bundled TypeScript compiler, WebAssembly capabilities
+- **Development:** `bun --serve` for HMR (Hot Module Reloading)
+- **Testing:** `bun test` with 484 passing tests (100% coverage)
+- **Package Management:** Drop-in Node.js compatibility with faster resolution
+
+### Database: SQLite (WAL Mode)
+
+- **Why SQLite?** Fast, portable, embeddable, perfect for sovereignty
+- **ORM:** Advanced QueryBuilder with relationships, transactions, migrations
+- **Features:** Foreign keys, virtual tables, JSON1 extension, full-text search
+- **Migrations:** Automatic schema versioning with timestamp-based files
+- **Location:** Project root as `afriCode.db` with WAL files for concurrent access
+
+### Architecture: Full-Stack Module System
+
+```
+core/              → Framework internals (SDK, middleware, ORM)
+components/        → 33 Web Components (no framework dependencies)
+styles/            → African color palette + typography
+pages/             → Server-side rendered pages (SSR with Bun)
+templates/         → HTML templates with data binding
+bin/               → CLI tools for scaffolding
+```
+
+---
+
+## 🎨 Cultural Integration
+
+### Procedural African Pattern System
+
+**Core Philosophy:** Patterns are algorithmic, not static images. Generated on-demand.
+
+#### 6 Tribal Patterns (Procedurally Generated)
+
+1. **Kente** (Ghana/Akan)
+   - 8 horizontal bands + geometric dividers
+   - Colors: Red, green, gold, white, black
+   - Symbolizes: Cloth of kings, wisdom, celebration
+
+2. **Ndebele** (South Africa)
+   - Nested rectangles with jagged extensions
+   - Bold primary colors: Red, white, green, blue
+   - Symbolizes: Unity through geometric harmony
+
+3. **Masai** (Kenya/Tanzania)
+   - Dense beadwork grid with chevron bands
+   - Red, white, gold, navy, earth tones
+   - Symbolizes: Warrior tradition, pastoral life
+
+4. **Zulu** (South Africa)
+   - Isivivane triangle panels with love letter geometry
+   - White on black with accent colors
+   - Symbolizes: Protection, storytelling, heritage
+
+5. **Hadzabe** (Tanzania)
+   - Cave rock art with constellations, hunters, animals
+   - Earth tones, ochre, cream, smoke
+   - Symbolizes: Ancient connection to land and cosmos
+
+6. **Kuba** (Democratic Republic of Congo)
+   - Checkerboard with mandala center
+   - Alternating dark/light with radial symmetry
+   - Symbolizes: Royal precision, mathematical harmony
+
+### Implementation
+
+```javascript
+// Patterns are class static methods in PatternRenderer
+PatternRenderer.generateKente((width = 240), (height = 240)); // Returns SVG string
+PatternRenderer.generateNdebele((width = 240), (height = 240)); // Pure SVG (no canvas)
+PatternRenderer.generateMasai((width = 240), (height = 240));
+PatternRenderer.generateZulu((width = 240), (height = 240));
+PatternRenderer.generateHadzabe((width = 240), (height = 240));
+PatternRenderer.generateKuba((width = 240), (height = 240));
+
+// Render to DOM
+PatternRenderer.renderToElement('element-id', 'Kente', 300, 300);
+```
+
+### Color Palette (CSS Variables)
+
+```css
+--afri-gold: #ffd700 /* Wealth, prestige */ --afri-red: #c55a11 /* Energy, passion */
+  --afri-blue: #003d82 /* Stability, trust */ --afri-green: #164b35 /* Growth, life */
+  --afri-obsidian: #1a1a1a /* Strength, foundation */;
+```
+
+---
+
+## 🧩 33 Web Components
+
+**Philosophy:** Framework-agnostic, vanilla Web Components. Work with any JavaScript project.
+
+### Navigation Components
+
+- `<af-navbar>` — Sticky navigation with logo, menu, language switcher
+- `<af-sidebar>` — Collapsible sidebar with icon support
+- `<af-breadcrumb>` — Hierarchical navigation path
+- `<af-pagination>` — Multi-page navigation with prev/next
+
+### Form Components
+
+- `<af-input>` — Text, email, password, number, date inputs
+- `<af-select>` — Dropdown with search capability
+- `<af-checkbox>` — Single/multi-select checkboxes
+- `<af-radio>` — Radio button groups
+- `<af-textarea>` — Multi-line text with resize
+- `<af-form>` — Form wrapper with validation
+
+### Data Display
+
+- `<af-table>` — Sortable, paginated data tables
+- `<af-card>` — Content containers with elevation
+- `<af-badge>` — Status labels and tags
+- `<af-progress>` — Progress bars and loaders
+- `<af-skeleton>` — Loading placeholders
+- `<af-grid>` — Responsive grid layout
+
+### Feedback Components
+
+- `<af-alert>` — Alert boxes (success, error, warning, info)
+- `<af-toast>` — Toast notifications (auto-dismiss)
+- `<af-modal>` — Modal dialogs with actions
+- `<af-tooltip>` — Hover tooltips
+- `<af-dropdown>` — Dropdown menus
+
+### Visual Components
+
+- `<af-avatar>` — User avatars with fallback
+- `<af-icon>` — Icon system with emoji fallback
+- `<af-button>` — Button variants (primary, secondary, ghost)
+- `<af-hero>` — Hero section with background patterns
+- `<af-section>` — Content sections with padding/background
+- `<af-divider>` — Visual separators
+- `<af-accordion>` — Collapsible content sections
+- `<af-tabs>` — Tabbed content switcher
+- `<af-theme-toggle>` — Dark/light mode toggle
+- `<af-language-switcher>` — Multi-language support (4 languages)
+- `<af-loader>` — Loading spinners
+- `<af-pattern-showcase>` — Pattern display gallery
+
+### Usage
+
+```html
+<!-- Web Components work in any HTML -->
+<af-button variant="primary" @click="handleClick">Click Me</af-button>
+<af-alert type="success">Operation completed!</af-alert>
+<af-modal id="confirmModal">Confirm action?</af-modal>
+<af-pattern-showcase pattern="Kente" width="300" height="300"></af-pattern-showcase>
+```
+
+---
+
+## 🔌 Advanced Features
+
+### WebSocket Real-Time Communication
+
+```javascript
+// Server
+app.ws('/messages', (ws) => {
+  ws.subscribe('room:general');
+  ws.send({ event: 'user:joined', userId: 123 });
+});
+
+// Client
+const ws = new WebSocket('ws://localhost:3000/messages');
+ws.addEventListener('message', (event) => {
+  console.log('Real-time update:', event.data);
+});
+```
+
+### ORM & Database
+
+```javascript
+// Define models with relationships
+const User = db.model('users', {
+  id: 'INTEGER PRIMARY KEY',
+  name: 'TEXT NOT NULL',
+  email: 'TEXT UNIQUE',
+  posts: { relation: 'hasMany', target: 'posts' },
+});
+
+// Query builder
+const users = await User.where('email', 'like', '%@african-tech.com')
+  .with('posts')
+  .orderBy('createdAt', 'DESC')
+  .paginate(10, 1);
+
+// Transactions
+await db.transaction(async () => {
+  await User.create({ name: 'Amara' });
+  await Activity.create({ type: 'user_signup' });
+});
+```
+
+### Middleware Pipeline
+
+```javascript
+app.use(middleware.cors({ origin: 'https://african-tech.com' }));
+app.use(middleware.logging());
+app.use(middleware.rateLimit({ max: 100, window: 60000 }));
+app.use(middleware.auth({ secret: process.env.JWT_SECRET }));
+app.use(middleware.csrf());
+
+app.post('/api/users', (req, res) => {
+  // All middleware applied automatically
+});
+```
+
+### Security by Default
+
+- **Argon2id Hashing**: Password hashing with memory-hard algorithm
+- **CSRF Protection**: Token validation on state-changing requests
+- **Rate Limiting**: Per-IP or per-user request throttling
+- **Secure Headers**: HSTS, X-Frame-Options, X-Content-Type-Options
+- **SQL Injection Prevention**: Parameterized queries with QueryBuilder
+- **Session Management**: Secure, HTTP-only cookies with rotation
+
+### Authentication
+
+```javascript
+// Simple auth middleware
+const user = await authenticate(req, {
+  secret: process.env.AUTH_SECRET,
+  algorithm: 'HS256',
+});
+
+// Password hashing
+const hash = await hashPassword('user_password');
+const isValid = await verifyPassword('user_password', hash);
+```
+
+---
+
+## 📁 Project Structure
+
+### Recommended Layout for New Projects
+
+```
+my-african-app/
+├── core/              → Business logic, API routes
+│   ├── api/
+│   │   ├── users.js
+│   │   ├── posts.js
+│   │   └── auth.js
+│   └── services/
+│       └── email.js
+├── pages/             → Server-rendered views
+│   ├── home.html
+│   ├── about.html
+│   └── dashboard.html
+├── components/        → Web Components (if custom)
+│   └── custom-widget.js
+├── styles/            → CSS
+│   ├── main.css
+│   └── variables.css
+├── migrations/        → Database schemas
+│   ├── 001_create_users.sql
+│   └── 002_create_posts.sql
+├── public/            → Static assets
+├── server.js          → Entry point
+├── package.json
+└── .env.example
+```
+
+---
+
+## 🚀 Getting Started
+
+### Installation
+
+```bash
+npm install africode
+# or
+bun add africode
+```
+
+### Create New Project
+
+```bash
+npx create-africode my-app
+cd my-app
+bun dev
+```
+
+### Basic Server
+
+```javascript
+import { AfriCode } from 'africode/core/sdk.js';
+
+const app = new AfriCode({
+  port: 3000,
+  database: 'afriCode.db',
+});
+
+// Define routes
+app.get('/', (req, res) => {
+  res.html(`
+        <h1>Welcome to AfriCode</h1>
+        <af-pattern-showcase pattern="Kente"></af-pattern-showcase>
+    `);
+});
+
+// Start server
+app.listen(() => console.log('🌍 AfriCode running on localhost:3000'));
+```
+
+---
+
+## 🧪 Testing
+
+**484 Tests Passing** (100% success rate)
+
+### Run Tests
+
+```bash
+bun test
+bun test --watch      # Watch mode
+bun test --coverage   # Coverage report
+```
+
+### Test Structure
+
+```javascript
+import { test, expect } from 'bun:test';
+import { AfriCode } from 'africode/core/sdk.js';
+
+test('POST /api/users creates user', async () => {
+  const app = new AfriCode();
+  const res = await app.request('POST', '/api/users', {
+    name: 'Amara',
+    email: 'amara@example.com',
+  });
+  expect(res.status).toBe(201);
+});
+```
+
+---
+
+## 📚 Multilingual Support
+
+**4 Languages Built-In:**
+
+### Implementation
+
+```html
+<!-- HTML with multilingual attributes -->
+<h1 data-en="Welcome" data-sw="Karibu" data-yo="Pẹlẹ o" data-am="ደህና መጡ">Welcome</h1>
+
+<button class="lang-btn" data-lang="en">EN</button>
+<button class="lang-btn" data-lang="sw">SW</button>
+<button class="lang-btn" data-lang="yo">YO</button>
+<button class="lang-btn" data-lang="am">AM</button>
+```
+
+### JavaScript
+
+```javascript
+function setLanguage(lang) {
+  document.querySelectorAll('[data-en]').forEach((el) => {
+    const text = el.getAttribute(`data-${lang}`) || el.getAttribute('data-en');
+    if (text) el.textContent = text;
+  });
+  localStorage.setItem('preferredLanguage', lang);
+}
+
+// Auto-load preferred language
+const preferred = localStorage.getItem('preferredLanguage') || 'en';
+setLanguage(preferred);
+```
+
+### Supported Languages
+
+- **EN** (English)
+- **SW** (Kiswahili) - East Africa
+- **YO** (Yoruba) - West Africa
+- **AM** (Amharic) - East Africa
+
+---
+
+## 🔧 CLI Tools
+
+### AfriCode CLI
+
+```bash
+africode dev           # Start development server with HMR
+africode build         # Build for production
+africode migrate       # Run database migrations
+africode generate      # Scaffold new components/models
+africode serve         # Serve static build
+```
+
+### Create AfriCode Project
+
+```bash
+create-africode my-app                    # Create new project
+create-africode my-app --template=ecommerce  # With templates
+```
+
+---
+
+## 🌟 Best Practices for Developers
+
+### 1. Leverage Procedural Patterns
+
+Don't hardcode graphics—use `PatternRenderer` for dynamic, responsive designs.
+
+### 2. Use Web Components
+
+Build with `<af-*>` components. They're framework-agnostic and production-tested.
+
+### 3. Think in Sovereignty
+
+Your framework should respect where you build it. Use multilingual support, cultural patterns, and local-first design.
+
+### 4. Database First
+
+Design with SQLite from start. Migrations are cheap, refactoring is expensive.
+
+### 5. Real-Time Where It Matters
+
+Use WebSocket for chat, notifications, live updates—not for every request.
+
+### 6. Security by Default
+
+Never skip auth, rate limiting, and CSRF. They're middleware—use them.
+
+### 7. Test Everything
+
+Write tests for API routes, database queries, and components. Aim for >80% coverage.
+
+### 8. Optimize for Performance
+
+- Use Bun's native SQLite (faster than driver libraries)
+- Lazy-load Web Components with `<template>` tags
+- Cache pattern renders with memoization
+- Use HTTP/2 server push for critical resources
+
+---
+
+## 📖 Key Files & Where to Find Them
+
+| File                    | Purpose                       |
+| ----------------------- | ----------------------------- |
+| `core/sdk.js`           | Main framework entry point    |
+| `core/db.js`            | Database ORM and QueryBuilder |
+| `core/hydration.js`     | Server-side rendering         |
+| `core/store.js`         | Global state management       |
+| `components/index.js`   | All 33 Web Components         |
+| `components/base.js`    | Base Web Component class      |
+| `styles/africanity.css` | Color variables & typography  |
+| `bin/africode.js`       | CLI entry point               |
+| `migrations/`           | Database schema files         |
+
+---
+
+## 🎯 Common Development Patterns
+
+### Pattern 1: Fetch User Data with Pattern Display
+
+```javascript
+// Fetch user profile
+const user = await User.find(123).with('posts');
+
+// Render with pattern
+const html = `
+    <div class="profile">
+        <h1>${user.name}</h1>
+        <af-pattern-showcase pattern="Masai"></af-pattern-showcase>
+        <div class="posts">
+            ${user.posts.map((p) => `<af-card>${p.title}</af-card>`).join('')}
+        </div>
+    </div>
+`;
+
+res.html(html);
+```
+
+### Pattern 2: Real-Time Chat with WebSocket
+
+```javascript
+app.ws('/chat/:roomId', (ws, req) => {
+  const roomId = req.params.roomId;
+  ws.subscribe(`chat:${roomId}`);
+
+  ws.on('message', async (data) => {
+    const message = await Message.create({
+      roomId,
+      userId: req.auth.id,
+      text: data.text,
+    });
+    app.broadcast(`chat:${roomId}`, message);
+  });
+});
+```
+
+### Pattern 3: Protected API Route
+
+```javascript
+app.use(middleware.auth({ secret: process.env.JWT_SECRET }));
+
+app.post('/api/posts', async (req, res) => {
+  const post = await Post.create({
+    title: req.body.title,
+    userId: req.auth.id, // Set from middleware
+    content: req.body.content,
+  });
+  res.json({ post }, 201);
+});
+```
+
+### Pattern 4: Paginated Data Table
+
+```javascript
+app.get('/api/users', async (req, res) => {
+    const page = parseInt(req.query.page || 1);
+    const limit = parseInt(req.query.limit || 10);
+
+    const { data, total, pages } = await User
+        .where('active', true)
+        .paginate(limit, page);
+
+    res.json({ data, total, pages });
+});
+
+// Frontend
+<af-table data-endpoint="/api/users" :columns="['name', 'email', 'role']"></af-table>
+```
+
+---
+
+## 🔄 Development Workflow
+
+### 1. Setup Database
+
+```bash
+bun run migrations/001_initial_schema.sql
+```
+
+### 2. Start Dev Server
+
+```bash
+bun dev  # Watches all files, HMR enabled
+```
+
+### 3. Build Components
+
+```javascript
+// Use Web Components in HTML
+<af-button>Save</af-button>
+<af-modal id="confirm">Confirm?</af-modal>
+```
+
+### 4. Handle Events
+
+```javascript
+document.getElementById('confirm').addEventListener('confirm', () => {
+  console.log('User confirmed');
+});
+```
+
+### 5. Test
+
+```bash
+bun test --watch
+```
+
+### 6. Deploy
+
+```bash
+bun build      # Build for production
+npm publish    # If publishing to npm
+```
+
+---
+
+## 🌐 Deployment Options
+
+### Option 1: Vercel (Recommended)
+
+- `vercel deploy` from CLI
+- Auto-detects Bun, builds framework
+- Serverless functions support
+
+### Option 2: Railway
+
+- Push to GitHub, Railway auto-deploys
+- Supports WebSocket
+- SQLite with persistent volumes
+
+### Option 3: Self-Hosted (VPS)
+
+```bash
+# On server
+git clone https://github.com/your-repo/my-app.git
+cd my-app
+bun install
+bun run build
+bun start
+```
+
+---
+
+## 📝 Important Conventions
+
+### Naming Conventions
+
+- **Files:** `kebab-case` (my-component.js)
+- **Classes:** `PascalCase` (UserModel)
+- **Functions:** `camelCase` (createUser)
+- **Constants:** `UPPER_SNAKE_CASE` (MAX_RETRIES)
+- **Components:** `<af-kebab-case>` (<af-table>, <af-modal>)
+
+### Directory Structure
+
+- `core/` → Internals (don't modify often)
+- `pages/` → User-facing routes
+- `styles/` → CSS (use CSS variables)
+- `migrations/` → Database schemas
+- `public/` → Static assets
+
+### Environment Variables
+
+```bash
+# .env
+DATABASE_URL=afriCode.db
+JWT_SECRET=your-secret-here
+API_PORT=3000
+NODE_ENV=production
+```
+
+---
+
+## 🆘 Debugging Tips
+
+### Enable Debug Logs
+
+```javascript
+process.env.DEBUG = 'africode:*';
+```
+
+### Query Debugging
+
+```javascript
+// See generated SQL
+const query = User.where('email', 'like', '%@example.com');
+console.log(query.toSQL()); // Prints: SELECT * FROM users WHERE email LIKE ?
+```
+
+### WebSocket Issues
+
+```javascript
+// Enable verbose logging
+ws.on('error', (err) => console.error('WS Error:', err));
+ws.on('close', () => console.log('WS Closed'));
+```
+
+---
+
+## 📞 Support & Community
+
+- **GitHub**: https://github.com/tap2payco/AfriCode-js
+- **Documentation**: https://africode.dev/docs
+- **Issues**: https://github.com/tap2payco/AfriCode-js/issues
+- **Discussions**: https://github.com/tap2payco/AfriCode-js/discussions
+
+---
+
+## ✨ Final Thoughts
+
+**AfriCode is built for developers who believe code is cultural.**
+
+Use this framework to:
+
+- Build fast, sovereignty-respecting web applications
+- Celebrate African heritage in digital spaces
+- Write less boilerplate, more business logic
+- Create real-time, responsive experiences
+- Deploy anywhere with confidence
+
+**Remember: Your framework should serve you, not control you.**
+
+Happy building! 🌍✨