🌍 AfriCode Framework

The Design System of Sovereignty
Bridging modern web performance with the fractal geometry and rich semiotics of African heritage.

Overview

AfriCode is a full-stack UI framework built on Bun and Vanilla JavaScript. It provides a reactive core, a procedural pattern engine, file-based routing, and a suite of high-performance Web Components designed for the African context (mobile-first, low-latency).

✨ Features

• 🧠 Reactive Core: Lightweight Proxy-based state management with effects (core/state.js).
• 🎨 Cultural Patterns: Procedural SVG generation for Kente, Shuka, Ndebele, and more.
• 📱 Mobile Optimized: "Profound Dark" theme with responsive grids and touch targets.
• ⚡ Native Performance: Built for Bun, zero-build runtime capable.
• 🔄 Hot Module Replacement (HMR): Real-time file change detection during development (5-10x faster iteration).
• 🗂️ File-Based Routing: Next.js-style routing with dynamic [id] and catch-all routes.
• 🔐 Authentication: Built-in session-based auth with HttpOnly cookies and Argon2id password hashing.
• 📦 33 Web Components: Pre-built UI elements ready for African-centric design.
• ✅ Comprehensive Tests: 389+ tests covering HTML templates, routing, state, HMR, authentication, ORM, WebSocket, middleware, security, and plugins.

🚀 Quick Start

Create a New Project

bunx create-africode my-app
cd my-app
bun install
bun run dev

This scaffolds a new AfriCode project with:

• Pre-configured pages/ directory for file-based routing
• styles/ folder with design tokens
• Auto-generated index.js entry point with Layout component
• Ready-to-run dev server with HMR

Install in Existing Project

bun add africode

Local Development (Framework Contributors)

If you are developing the framework itself:

1. Clone and navigate to the framework directory
2. Register the link: bun link
3. Use in another project: bun link africode
4. Run validation: bun scripts/validate-fresh-install.js

Usage (SDK)

Import the core SDK to generate patterns, use the state engine, or handle routing:

import { patterns, store, components } from 'africode';
import { FileSystemRouter } from 'africode/core/router.js';

// Generate a Maasai Shuka pattern
const shukaPattern = patterns.generateShuka();
document.body.style.backgroundImage = `url("${shukaPattern}")`;

// Use Global State
store.ui.theme = 'tanzania';
store.ui.theme; // 'tanzania' - triggers effects on change

// Use File-Based Routing
const router = new FileSystemRouter('./pages');
const route = await router.matchRoute('/users/123');
// { page, params: { id: '123' }, path: '/users/[id]' }

Usage (Authentication)

AfriCode includes built-in session-based authentication:

// API endpoints (automatically available)
POST / api / auth / register; // { email, username, password, fullname }
POST / api / auth / login; // { email/username, password }
POST / api / auth / logout; // Clears session
GET / api / auth / me; // Current user (requires session)
POST / api / auth / refresh; // Extend session expiry

Passwords are hashed with Argon2id (built into Bun), sessions use HttpOnly cookies with SameSite=Strict protection.

Usage (UI Components)

Simply import the components to register them as Custom Elements:

import 'africode/components';

Then use them in your HTML:

<af-navbar theme="tanzania" logo="My App"></af-navbar>

<af-kanga-card proverb="Haraka haraka haina baraka.">
  <h3>Project Title</h3>
  <p>Content goes here...</p>
</af-kanga-card>

<af-button onclick="handleClick()">Click Me</af-button>

⚙️ Development

Hot Module Replacement (HMR)

During bun run dev, any file changes trigger automatic browser refresh. This provides 5-10x faster iteration compared to manual reloads:

bun run dev
# Edit a file → browser updates instantly

HMR is smart about what to reload:

• .js files: Full page reload
• .css files: Incremental style update
• .html files: DOM refresh

File-Based Routing

Create files in pages/ and they automatically become routes:

pages/
  index.js          → /
  about.js          → /about
  users/
    [id].js         → /users/123
  api/
    users.js        → POST /api/users
    [...rest].js    → Catch-all: /api/foo/bar/baz

Route parameters are automatically extracted: params.id, params.rest, etc.

🏗️ Architecture

core/
  ├── html.js           → Tagged template literals with XSS protection (RawHtml wrapper)
  ├── state.js          → Proxy-based reactive state management
  ├── router.js         → File-based routing with dynamic routes
  ├── hmr.js            → Hot Module Replacement server
  ├── hmr-client.js     → Browser reconnection logic with exponential backoff
  ├── db.js             → SQLite ORM with User/Project/Session models
  ├── auth.js           → Password hashing and session utilities
  └── server/
      ├── auth-endpoints.js    → Authentication API endpoints
      ├── router.js            → Request routing and handler delegation
      └── render.js            → Server-side rendering with HTML injection

components/
  ├── base.js           → Web Component base class
  ├── button.js, navbar.js, modal.js, ... → 33+ UI components
  └── af-*.html         → Custom element definitions

patterns/
  ├── Kente, Shuka, Ndebele, Maasai patterns → Procedurally generated SVG
  └── Cultural design system with African semiotics

📊 Test Coverage

All core systems have comprehensive test coverage:

• ✅ HTML Templates (html.test.js) - Nested rendering, escaping, arrays, XSS prevention
• ✅ File-Based Routing (router.test.js) - Dynamic routes, catch-all, parameter extraction
• ✅ State Management (state.test.js, store.test.js) - Reactivity, effects, signals, deep updates
• ✅ HMR System (hmr.test.js) - WebSocket server, client reconnection, file watching
• ✅ Authentication (auth.test.js) - Registration, login, session management, Argon2id hashing
• ✅ Validation (validation.test.js) - Zod schemas, email, phone, URL, AfriFieldBuilder
• ✅ Advanced ORM (orm-advanced.test.js) - QueryBuilder, transactions, migrations, WAL mode
• ✅ WebSocket (websocket.test.js) - Connections, rooms, presence, message queueing, heartbeats
• ✅ Middleware (middleware.test.js) - CORS, logging, rate limiting, auth, security headers
• ✅ Security (security.test.js) - CSRF, injection prevention, token validation
• ✅ Plugin System (plugins.test.js) - Hook execution, timeouts, isolation, safe/strict modes
• ✅ Cultural Patterns (patterns.test.js) - SVG output, Kente, Ndebele, Kuba, Masai, Zulu
• ✅ Accessibility (a11y.test.js) - ARIA roles, keyboard navigation, focus management
• ✅ Framework Core (framework.test.js) - SDK init, config, component lifecycle

Total: 389 passing tests with zero regressions

📜 Licensing

AfriCode is Dual Licensed:

1. AGPL v3: For open-source projects. You must open-source your code if you use AfriCode.
2. Commercial: For proprietary projects. Contact us for a commercial license to build closed-source apps.

🤝 Contribution

We welcome contributions! Please see CONTRIBUTING.md for details.

Built with ❤️ by the AfriCode Team