@africode/core 5.0.11 → 5.0.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (221) hide show
  1. package/AGENTS.md +585 -585
  2. package/AGENT_INSTRUCTIONS.md +595 -595
  3. package/COMPONENT_SCHEMA.json +1826 -1800
  4. package/LICENSE +623 -623
  5. package/README.md +476 -476
  6. package/bin/africode.js +73 -73
  7. package/bin/cli.ts +82 -82
  8. package/bin/create-africode.js +220 -220
  9. package/bin/scaffold.ts +218 -218
  10. package/components/accordion.js +183 -183
  11. package/components/alert.js +131 -131
  12. package/components/auth-form.js +154 -154
  13. package/components/auth.js +172 -172
  14. package/components/avatar.js +117 -117
  15. package/components/badge.js +104 -104
  16. package/components/base.d.ts +139 -139
  17. package/components/base.js +234 -234
  18. package/components/breadcrumb.js +76 -72
  19. package/components/button.js +164 -164
  20. package/components/card.js +144 -137
  21. package/components/carousel.js +32 -32
  22. package/components/cart-drawer.js +28 -28
  23. package/components/code-block.js +20 -20
  24. package/components/contact-form.js +25 -25
  25. package/components/cookie-consent.js +23 -23
  26. package/components/cta-banner.js +38 -38
  27. package/components/cultural-card.js +243 -243
  28. package/components/dashboard-activity-list.js +103 -103
  29. package/components/dashboard-card.js +85 -85
  30. package/components/dashboard-metric.js +81 -81
  31. package/components/dashboard-shell.js +85 -85
  32. package/components/dashboard-topbar.js +84 -84
  33. package/components/divider.js +83 -83
  34. package/components/dropdown.js +171 -171
  35. package/components/error-boundary.js +155 -155
  36. package/components/faq-accordion.js +23 -23
  37. package/components/feature-grid.js +85 -85
  38. package/components/file-uploader.js +22 -22
  39. package/components/filter-bar.js +19 -19
  40. package/components/footer.js +113 -113
  41. package/components/form.js +131 -131
  42. package/components/gallery.js +22 -22
  43. package/components/hero.js +140 -138
  44. package/components/icon.js +36 -36
  45. package/components/index.js +128 -128
  46. package/components/input.js +252 -256
  47. package/components/kanga-card.js +185 -185
  48. package/components/kyc-upload.js +173 -173
  49. package/components/language-switcher.js +108 -108
  50. package/components/loader.js +80 -80
  51. package/components/modal.js +262 -262
  52. package/components/motion.js +84 -84
  53. package/components/nav-drawer.js +216 -216
  54. package/components/navbar.js +243 -236
  55. package/components/newsletter-signup.js +24 -24
  56. package/components/pagination.js +31 -31
  57. package/components/pattern-showcase.js +225 -225
  58. package/components/pricing-card.js +100 -100
  59. package/components/product-card.js +41 -41
  60. package/components/progress.js +132 -134
  61. package/components/react.js +111 -111
  62. package/components/search-box.js +24 -24
  63. package/components/section.js +54 -54
  64. package/components/select.js +321 -322
  65. package/components/sidebar.js +180 -180
  66. package/components/simple-chart.js +22 -22
  67. package/components/skeleton.js +85 -85
  68. package/components/stepper.js +28 -28
  69. package/components/table.js +181 -181
  70. package/components/tabs.js +202 -202
  71. package/components/team-grid.js +23 -23
  72. package/components/testimonial.js +94 -94
  73. package/components/theme-toggle.js +82 -82
  74. package/components/toast.js +139 -139
  75. package/components/tooltip.js +167 -167
  76. package/components/transaction-ledger.js +138 -138
  77. package/components/ui-avatar.js +79 -79
  78. package/components/ui-badge.js +61 -61
  79. package/components/ui-button.js +149 -149
  80. package/components/ui-card.js +74 -75
  81. package/components/ui-chip.js +87 -87
  82. package/components/ui-input.js +110 -110
  83. package/components/ui-popover.js +84 -84
  84. package/components/ui-progress-ring.js +60 -60
  85. package/components/ui-select.js +85 -85
  86. package/components/ui-stat.js +75 -75
  87. package/components/ui-switch.js +85 -85
  88. package/components/ui-table.js +69 -69
  89. package/components/ui-tabs.js +99 -99
  90. package/components/ui-tag.js +64 -64
  91. package/components/ui-textarea.js +84 -84
  92. package/components/ui-tooltip.js +66 -66
  93. package/components/video-player.js +22 -22
  94. package/components/wallet-balance.js +114 -114
  95. package/core/a2ui-schema-manager.js +351 -351
  96. package/core/a2ui.js +696 -696
  97. package/core/actions.js +27 -27
  98. package/core/bun-runtime.js +396 -396
  99. package/core/cli/commands/add.js +23 -23
  100. package/core/cli/commands/audit.js +58 -58
  101. package/core/cli/commands/build.js +193 -193
  102. package/core/cli/commands/create-plugin.js +241 -241
  103. package/core/cli/commands/dev.js +248 -283
  104. package/core/cli/commands/lint.js +23 -23
  105. package/core/cli/commands/test.js +33 -34
  106. package/core/cli/migrator.js +71 -71
  107. package/core/cli/ui.js +56 -56
  108. package/core/compliance.js +823 -823
  109. package/core/config.js +265 -265
  110. package/core/db-advanced.js +478 -481
  111. package/core/db.js +282 -284
  112. package/core/enhanced-hmr.js +406 -406
  113. package/core/errors.js +222 -222
  114. package/core/file-router.js +47 -47
  115. package/core/hmr-client.js +203 -204
  116. package/core/hmr.js +205 -197
  117. package/core/html.d.ts +30 -30
  118. package/core/html.js +84 -84
  119. package/core/hydration.js +52 -52
  120. package/core/lipa-namba-journey.js +548 -605
  121. package/core/logging.js +14 -14
  122. package/core/middleware.js +145 -145
  123. package/core/motion.js +106 -106
  124. package/core/nida-cig-middleware.js +417 -460
  125. package/core/patterns.d.ts +124 -124
  126. package/core/patterns.js +947 -1001
  127. package/core/plugins/index.js +345 -345
  128. package/core/request-analytics.js +253 -253
  129. package/core/request-identity.js +93 -93
  130. package/core/router.js +386 -386
  131. package/core/sdk-browser.js +140 -140
  132. package/core/sdk-client.js +61 -61
  133. package/core/sdk.d.ts +133 -133
  134. package/core/sdk.js +148 -148
  135. package/core/seo.js +76 -76
  136. package/core/server/auth-endpoints.js +339 -339
  137. package/core/server/auth.js +180 -180
  138. package/core/server/csrf.js +200 -206
  139. package/core/server/db.js +39 -39
  140. package/core/server/middleware.js +324 -324
  141. package/core/server/rate-limit.js +238 -238
  142. package/core/server/render.js +67 -69
  143. package/core/server/router.js +23 -11
  144. package/core/session-store.js +68 -68
  145. package/core/shim.js +28 -28
  146. package/core/state.d.ts +86 -86
  147. package/core/state.js +276 -276
  148. package/core/store.d.ts +122 -122
  149. package/core/store.js +61 -61
  150. package/core/validation.d.ts +232 -232
  151. package/core/validation.js +602 -602
  152. package/core/websocket.js +656 -641
  153. package/dist/africode.js +233 -230
  154. package/dist/africode.js.map +83 -83
  155. package/dist/build-info.json +3 -3
  156. package/dist/components.js +195 -192
  157. package/dist/components.js.map +73 -73
  158. package/dist/styles/africanity.css +321 -321
  159. package/dist/styles/typography.css +140 -140
  160. package/docs/IDE-Guide.md +50 -50
  161. package/package.json +113 -113
  162. package/scripts/generate-component-schema.js +82 -79
  163. package/styles/africanity.css +321 -321
  164. package/styles/typography.css +140 -140
  165. package/templates/starter/.env.example +15 -15
  166. package/templates/starter/africode.config.js +40 -40
  167. package/templates/starter/package.json +13 -13
  168. package/templates/starter/src/index.js +18 -18
  169. package/templates/starter/src/pages/index.html +55 -55
  170. package/templates/starter/src/pages/index.js +17 -17
  171. package/templates/starter/src/styles/main.css +3 -3
  172. package/templates/starter-3d/.env.example +7 -7
  173. package/templates/starter-3d/africode.config.js +29 -29
  174. package/templates/starter-3d/components/af-model-viewer.js +125 -125
  175. package/templates/starter-3d/package.json +14 -14
  176. package/templates/starter-3d/src/pages/index.html +55 -55
  177. package/templates/starter-3d/src/pages/index.js +50 -50
  178. package/templates/starter-3d/src/styles/main.css +3 -3
  179. package/templates/starter-dashboard/.env.example +21 -21
  180. package/templates/starter-dashboard/africode.config.js +20 -20
  181. package/templates/starter-dashboard/package.json +14 -14
  182. package/templates/starter-dashboard/src/index.js +17 -17
  183. package/templates/starter-dashboard/src/pages/api/analytics.js +24 -24
  184. package/templates/starter-dashboard/src/pages/index.html +118 -118
  185. package/templates/starter-dashboard/src/pages/index.js +110 -110
  186. package/templates/starter-dashboard/src/styles/main.css +172 -172
  187. package/templates/starter-fintech/.env.example +28 -28
  188. package/templates/starter-fintech/africode.config.js +20 -20
  189. package/templates/starter-fintech/package.json +15 -15
  190. package/templates/starter-fintech/src/index.js +17 -17
  191. package/templates/starter-fintech/src/pages/api/auth.js +45 -45
  192. package/templates/starter-fintech/src/pages/api/transfer.js +65 -65
  193. package/templates/starter-fintech/src/pages/api/wallet.js +39 -39
  194. package/templates/starter-fintech/src/pages/api/webhooks/payment.js +32 -32
  195. package/templates/starter-fintech/src/pages/index.html +169 -169
  196. package/templates/starter-fintech/src/pages/index.js +161 -161
  197. package/templates/starter-fintech/src/styles/main.css +246 -246
  198. package/templates/starter-react/.env.example +15 -15
  199. package/templates/starter-react/africode.config.js +40 -40
  200. package/templates/starter-react/package.json +15 -15
  201. package/templates/starter-react/src/pages/index.html +55 -55
  202. package/templates/starter-react/src/pages/index.js +68 -68
  203. package/templates/starter-react/src/styles/main.css +3 -3
  204. package/templates/starter-tailwind/.env.example +15 -15
  205. package/templates/starter-tailwind/africode.config.js +40 -40
  206. package/templates/starter-tailwind/package.json +19 -19
  207. package/templates/starter-tailwind/src/pages/index.html +55 -55
  208. package/templates/starter-tailwind/src/pages/index.js +67 -67
  209. package/templates/starter-tailwind/src/styles/main.css +3 -3
  210. package/templates/starter-tailwind/src/styles/tailwind.css +1 -1
  211. package/templates/starter-tailwind/src/tailwind-loader.js +30 -30
  212. package/templates/starter-tailwind/tailwind.config.cjs +18 -18
  213. package/templates/starter-website/.env.example +18 -18
  214. package/templates/starter-website/africode.config.js +20 -20
  215. package/templates/starter-website/package.json +14 -14
  216. package/templates/starter-website/src/index.js +17 -17
  217. package/templates/starter-website/src/pages/index.html +124 -124
  218. package/templates/starter-website/src/pages/index.js +116 -116
  219. package/templates/starter-website/src/styles/main.css +195 -195
  220. package/bin/africode.js.1758507140 +0 -343
  221. package/core/heartbeat.js +0 -64
package/README.md CHANGED
@@ -1,476 +1,476 @@
1
- # 🌍 AfriCode v5.0.0 — The Design System of Sovereignty
2
-
3
- > **Autonomous Framework for African Digital Economy**
4
- > Bridging AI safety, fintech compliance, and cultural heritage through high-performance web architecture.
5
-
6
- ![Version: 5.0.0](https://img.shields.io/badge/Version-5.0.0-green.svg)
7
- ![Status: Cloud Ready](https://img.shields.io/badge/Status-Cloud%20Ready-brightgreen.svg)
8
- ![AMD AI Cloud: $100 Credits](https://img.shields.io/badge/AMD%20AI%20Cloud-%24100%20Credits-orange.svg)
9
- ![Alibaba Cloud: Free Tier](https://img.shields.io/badge/Alibaba%20Cloud-Free%20Tier-blue.svg)
10
- ![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
11
-
12
- ## Overview
13
-
14
- AfriCode v5.0.0 is an autonomous full-stack framework that "owns" the application lifecycle. Built on **Bun runtime** with **TypeScript-first** architecture, it provides AI-safe component generation, comprehensive fintech compliance, and zero-downtime infrastructure for the African digital economy.
15
-
16
- ### Strategic Vision: From Tanzania to the Continent
17
-
18
- Following the rollout framework, AfriCode v5.0.0 implements a phased Pan-African expansion:
19
-
20
- - **Phase 1 (Months 1-4)**: Silicon Dar foundation with TIPS integration
21
- - **Phase 2 (Months 5-9)**: East African Corridor (Kenya, Uganda, Rwanda)
22
- - **Phase 3 (Months 10-15)**: West African Hub (Nigeria, Ghana)
23
- - **Phase 4 (Months 16-24)**: Continental governance and sustainability
24
-
25
- ## ✨ Autonomous Features
26
-
27
- ### 🤖 AI-Safe Architecture (A2UI Protocol)
28
- - **Robot-First Manifest**: Machine-readable component catalog prevents hallucinations
29
- - **Ethnomathematical Patterns**: Procedural generation of Kente, Ndebele, Shuka motifs
30
- - **Schema Validation**: Pre-approved components with usage hints and constraints
31
-
32
- ### 🔐 Fintech Compliance "Hardening"
33
- - **NIDA CIG Bridge**: VPN-tunneled identity verification with Ed25519 cryptography
34
- - **TIPS Integration**: Bank of Tanzania-compliant payment flows
35
- - **AML/FIU Reporting**: Automated regulatory compliance and transaction logging
36
-
37
- ### ⚡ Zero-Downtime Infrastructure
38
- - **File-Based Routing**: Automatic `/pages` to URL mapping with dynamic routes
39
- - **Enhanced HMR**: Session preservation during hot reloads
40
- - **Bun-Native Runtime**: 5ms startup with WebSocket orchestration
41
-
42
- ### 🎨 Cultural Resonance
43
- - **33+ Web Components**: African-themed UI elements with cultural semiotics
44
- - **Procedural SVG Engine**: Fractal geometry for traditional patterns
45
- - **Mobile-First Design**: Optimized for African connectivity constraints
46
- - **Native UI Kit**: Shadcn-style Web Components like `af-ui-button`, `af-ui-card`, and `af-ui-input` for consistent app UI
47
-
48
- ## 🚀 Quick Start
49
-
50
- ### Create Autonomous Project
51
-
52
- ```bash
53
- # Install globally via NPM
54
- npm install -g @africode/core
55
-
56
- # Create new project
57
- create-africode my-app
58
- cd my-app
59
-
60
- # Install dependencies
61
- bun install
62
-
63
- # Start autonomous development server
64
- bun run dev
65
- ```
66
-
67
- ### Project Structure (Autonomous)
68
-
69
- ```
70
- my-app/
71
- ├── src/
72
- │ ├── server.ts # Autonomous server entry
73
- │ ├── pages/ # File-based routes
74
- │ │ ├── index.ts # Home page
75
- │ │ └── api/ # API routes
76
- │ ├── components/ # Custom components
77
- │ └── core/ # Framework extensions
78
- ├── public/ # Static assets
79
- ├── package.json # NPM configuration
80
- ├── tsconfig.json # TypeScript config
81
- └── catalog.json # A2UI component manifest
82
- ```
83
-
84
- ### AI-Safe Development
85
-
86
- The published package includes the agent guidance files so AI assistants can discover the framework rules when the package is installed. These files are bundled as [AGENTS.md](AGENTS.md) and [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md).
87
-
88
- ```typescript
89
- // pages/index.ts
90
- import { html } from '@africode/core';
91
-
92
- export default function Home() {
93
- return html`
94
- <af-app>
95
- <af-navbar>
96
- <h1 slot="brand">My AfriCode App</h1>
97
- </af-navbar>
98
-
99
- <main>
100
- <af-hero>
101
- <h1>AI-Safe Fintech</h1>
102
- <p>Built with cultural patterns</p>
103
- <af-kente-pattern complexity="3"></af-kente-pattern>
104
- </af-hero>
105
- </main>
106
- </af-app>
107
- `;
108
- }
109
- ```
110
-
111
- ## 🏗️ Architecture
112
-
113
- ### Core Modules
114
-
115
- | Module | Purpose | Status |
116
- |--------|---------|--------|
117
- | `src/index.ts` | Main framework entry | ✅ Complete |
118
- | `core/a2ui-schema-manager.js` | AI component catalog | ✅ Enhanced |
119
- | `core/nida-cig-middleware.js` | Identity verification | ✅ VPN + Crypto |
120
- | `core/lipa-namba-journey.js` | Payment primitives | ✅ BoT Compliant |
121
- | `core/file-router.js` | File-based routing | ✅ Dynamic routes |
122
- | `core/enhanced-hmr.js` | Zero-downtime HMR | ✅ Session preservation |
123
-
124
- ### Cloud Infrastructure
125
-
126
- #### AMD AI Cloud (Intelligence Layer)
127
- - **MI300X GPUs**: 192GB HBM3 for LLM inference
128
- - **$100 Credits**: 200 hours on RunPod community cloud
129
- - **AfriCode-Coder Model**: Fine-tuned for Tanzanian fintech law
130
-
131
- #### Alibaba Cloud (Asset Layer)
132
- - **Model Studio**: Qwen3-Max for complex reasoning
133
- - **Free Tier**: 1M tokens for initial rollout
134
- - **Batch Inference**: 50% cost reduction for production
135
-
136
- ## 🔧 CLI Commands
137
-
138
- ```bash
139
- # Development
140
- africode dev # Start dev server with HMR
141
- africode build # Production build
142
- africode lint # Code quality checks
143
-
144
- # AI Integration
145
- africode generate a2ui # Update component catalog
146
- africode generate patterns # Regenerate cultural patterns
147
-
148
- # Fintech
149
- africode migrate # Run database migrations
150
- africode audit # Security and compliance audit
151
- ```
152
-
153
- ## 🎭 Ethnomathematical Patterns
154
-
155
- AfriCode v5.0.0 incorporates traditional African geometric principles:
156
-
157
- ### Kente Weaving (Glide Reflection)
158
- ```javascript
159
- import { generateKente } from '@africode/core';
160
-
161
- const pattern = generateKente({
162
- baseColor: '#8B4513',
163
- accentColor: '#DAA520',
164
- complexity: 3
165
- });
166
- ```
167
-
168
- ### Ndebele Fractals (Recursive Geometry)
169
- ```javascript
170
- const ndebele = generateNdebele({
171
- recursionDepth: 4,
172
- symmetry: 'rotational',
173
- colors: ['#FF6B6B', '#4ECDC4', '#45B7D1']
174
- });
175
- ```
176
-
177
- ## 🔒 Fintech Compliance
178
-
179
- ### NIDA Identity Verification
180
- ```typescript
181
- import { NIDAClient } from '@africode/core';
182
-
183
- const nida = new NIDAClient({
184
- vpnEnabled: true,
185
- endpoint: 'https://api.nida.go.tz/cig'
186
- });
187
-
188
- const result = await nida.verifyNIN('12345678901234567890', 'PIN');
189
- ```
190
-
191
- ### TIPS Payment Processing
192
- ```typescript
193
- import { LipaNambaJourney } from '@africode/core';
194
-
195
- const journey = new LipaNambaJourney();
196
- const payment = await journey.executeFullJourney({
197
- merchantId: 'MERCHANT_001',
198
- customerPhone: '255712345678',
199
- amount: 50000
200
- }, customerIdentity, confirmationData);
201
- ```
202
-
203
- ## 🌐 Pan-African Expansion
204
-
205
- ### Phase 1: Tanzania Foundation
206
- - **TIPS Integration**: Real-time payment processing
207
- - **NIDA Compliance**: Identity verification for KYC
208
- - **Cultural Patterns**: Swahili language support
209
-
210
- ### Phase 2: East African Corridor
211
- - **PAPSS Bridge**: Cross-border settlement
212
- - **Regional Hubs**: Nairobi, Kampala, Kigali
213
- - **Agri-Fintech**: Supply chain integration
214
-
215
- ### Phase 3: West African Powerhouse
216
- - **NIBSS Integration**: Nigerian payment systems
217
- - **Kente Patterns**: Ghanaian cultural motifs
218
- - **Enterprise Adoption**: Large corporate clients
219
-
220
- ## 🤝 Community & Incentives
221
-
222
- ### AfriCode Pioneer Bounty Program
223
- - **Bug Fixes**: $50-200 for confirmed issues
224
- - **Features**: $300-1500 for new capabilities
225
- - **Performance**: $100-500 for optimizations
226
- - **Cultural Assets**: $50-300 for pattern designs
227
-
228
- ### Developer Hubs
229
- - **Silicon Dar**: Dar es Salaam tech district
230
- - **iHub Nairobi**: East African innovation
231
- - **CcHUB Lagos**: West African powerhouse
232
- - **GDG Network**: Google Developer Groups across Africa
233
-
234
- ## 📊 Performance Metrics
235
-
236
- - **Startup Time**: <5ms (Bun-native)
237
- - **Bundle Size**: <100KB (tree-shaken)
238
- - **Lighthouse Score**: 95+ (mobile-first)
239
- - **TIPS Transactions**: 490M+ annually supported
240
- - **NIDA Verifications**: Real-time with VPN security
241
-
242
- ## 📚 Documentation
243
-
244
- - [Framework Guide](docs/FRAMEWORK.md)
245
- - [Component Catalog](catalog.json)
246
- - [API Reference](docs/API.md)
247
- - [Fintech Integration](docs/FINTECH.md)
248
- - [Cultural Patterns](docs/PATTERNS.md)
249
-
250
- ## 🤝 Contributing
251
-
252
- We welcome contributions that align with our Pan-African vision:
253
-
254
- 1. Fork the repository
255
- 2. Create a feature branch
256
- 3. Add tests for new functionality
257
- 4. Ensure AI-safety compliance
258
- 5. Submit a pull request
259
-
260
- ## 📄 License
261
-
262
- **Dual License:**
263
- - **Open Source**: AGPL v3.0 for community projects
264
- - **Commercial**: Available for enterprise deployments
265
-
266
- ## 🌟 Acknowledgments
267
-
268
- Built for the African developer community with support from:
269
- - **Bank of Tanzania** (TIPS infrastructure)
270
- - **National Identification Authority** (NIDA systems)
271
- - **AMD AI Cloud** ($100 credits for AI development)
272
- - **Alibaba Cloud** (Model Studio free tier)
273
- - **African Export-Import Bank** (PAPSS coordination)
274
-
275
- ---
276
-
277
- **"Designed for Tanzanians by Tanzanians, Built for Africans by Africans"**
278
-
279
- 🇹🇿🇰🇪🇺🇬🇷🇼🇳🇬🇬🇭🇿🇦🇲🇦
280
-
281
- ### Local Development (Framework Contributors)
282
-
283
- If you are developing the framework itself:
284
-
285
- 1. Clone and navigate to the framework directory
286
- 2. Register the link: `bun link`
287
- 3. Use in another project: `bun link africode`
288
- 4. Run validation: `bun scripts/validate-fresh-install.js`
289
-
290
- ### Usage (SDK)
291
-
292
- Import the core SDK to generate patterns, use the state engine, or handle routing:
293
-
294
- ```javascript
295
- import { patterns, store, components } from 'africode';
296
- import { FileSystemRouter } from 'africode/core/router.js';
297
-
298
- // Generate a Maasai Shuka pattern
299
- const shukaPattern = patterns.generateShuka();
300
- document.body.style.backgroundImage = `url("${shukaPattern}")`;
301
-
302
- // Use Global State
303
- store.ui.theme = 'tanzania';
304
- store.ui.theme; // 'tanzania' - triggers effects on change
305
-
306
- // Use File-Based Routing
307
- const router = new FileSystemRouter('./pages');
308
- const route = await router.matchRoute('/users/123');
309
- // { page, params: { id: '123' }, path: '/users/[id]' }
310
- ```
311
-
312
- ### Usage (Authentication)
313
-
314
- AfriCode includes built-in session-based authentication:
315
-
316
- ```javascript
317
- // API endpoints (automatically available)
318
- POST / api / auth / register; // { email, username, password, fullname }
319
- POST / api / auth / login; // { email/username, password }
320
- POST / api / auth / logout; // Clears session
321
- GET / api / auth / me; // Current user (requires session)
322
- POST / api / auth / refresh; // Extend session expiry
323
- ```
324
-
325
- Passwords are hashed with **Argon2id** (built into Bun), sessions use **HttpOnly** cookies with **SameSite=Strict** protection.
326
-
327
- ### Usage (UI Components)
328
-
329
- Simply import the components to register them as Custom Elements:
330
-
331
- ```javascript
332
- import 'africode/components';
333
- ```
334
-
335
- Then use them in your HTML:
336
-
337
- ```html
338
- <af-navbar theme="tanzania" logo="My App"></af-navbar>
339
-
340
- <af-kanga-card proverb="Haraka haraka haina baraka.">
341
- <h3>Project Title</h3>
342
- <p>Content goes here...</p>
343
- </af-kanga-card>
344
-
345
- <af-button onclick="handleClick()">Click Me</af-button>
346
- ```
347
-
348
- ### Native AfriCode UI Kit
349
-
350
- AfriCode now includes a native UI kit with shadcn-inspired Web Components for rapid interface design. The Tailwind starter demonstrates the new UI kit using components like `af-ui-button`, `af-ui-card`, `af-ui-input`, `af-ui-badge`, and `af-ui-switch` in a Shadow DOM-friendly workflow.
351
-
352
- All `af-`, `af-ui-`, and `af-dashboard-` components are distributed together in the same `@africode/core` package, so they share theme, styles, registry, and versioning.
353
-
354
- The library is optimized for consistent spacing, elevation, and interactive states across theme-aware apps.
355
-
356
- Use the Tailwind starter template for a ready-made UI experience:
357
-
358
- ```bash
359
- create-africode my-app --template starter-tailwind
360
- cd my-app
361
- bun install
362
- bun run dev
363
- ```
364
-
365
- Example usage:
366
-
367
- ```html
368
- <af-ui-card variant="outlined" clickable>
369
- <h3>Actionable Panel</h3>
370
- <p>Build data-driven experiences with native AfriCode UI components.</p>
371
- <af-ui-badge variant="success" pill>Ready</af-ui-badge>
372
- </af-ui-card>
373
-
374
- <af-ui-input label="Email" placeholder="you@example.com"></af-ui-input>
375
- <af-ui-switch checked></af-ui-switch>
376
- <af-ui-button variant="primary">Submit</af-ui-button>
377
- ```
378
-
379
- ## ⚙️ Development
380
-
381
- ### Hot Module Replacement (HMR)
382
-
383
- During `bun run dev`, any file changes trigger automatic browser refresh. This provides **5-10x faster iteration** compared to manual reloads:
384
-
385
- ```bash
386
- bun run dev
387
- # Edit a file → browser updates instantly
388
- ```
389
-
390
- HMR is smart about what to reload:
391
-
392
- - `.js` files: Full page reload
393
- - `.css` files: Incremental style update
394
- - `.html` files: DOM refresh
395
-
396
- ### File-Based Routing
397
-
398
- Create files in `pages/` and they automatically become routes:
399
-
400
- ```
401
- pages/
402
- index.js → /
403
- about.js → /about
404
- users/
405
- [id].js → /users/123
406
- api/
407
- users.js → POST /api/users
408
- [...rest].js → Catch-all: /api/foo/bar/baz
409
- ```
410
-
411
- Route parameters are automatically extracted: `params.id`, `params.rest`, etc.
412
-
413
- ## 🏗️ Architecture
414
-
415
- ```
416
- core/
417
- ├── state.js → Proxy-based reactive state management
418
- ├── patterns.js → Cultural SVG generators (Kente, Shuka, Ndebele, Maasai)
419
- ├── html.js → XSS-safe tagged template literals
420
- ├── router.js → File-based routing with dynamic routes
421
- ├── db.js → SQLite ORM with migrations and transactions
422
- ├── auth.js → Argon2id password hashing and sessions
423
- ├── a2ui.js → Generative AI interface protocol (v5.0.0)
424
- ├── compliance.js → Tanzanian fintech regulations (v5.0.0)
425
- ├── bun-runtime.js → High-performance server engine (v5.0.0)
426
- ├── hydration.js → Component system and lifecycle
427
- └── server/
428
- ├── auth-endpoints.js → Authentication API endpoints
429
- ├── router.js → Request routing and handler delegation
430
- └── render.js → Server-side rendering with HTML injection
431
-
432
- components/
433
- ├── base.js → Web Component base class
434
- ├── 33+ UI components → African-themed elements (buttons, cards, modals)
435
- └── pattern-showcase.js → Cultural pattern gallery
436
-
437
- patterns/
438
- ├── 8 Regional Generators → Procedurally generated SVG patterns
439
- └── Cultural design system with African semiotics
440
- ```
441
-
442
- ## 📊 Test Coverage
443
-
444
- All core systems have comprehensive test coverage:
445
-
446
- - ✅ **HTML Templates** (`html.test.js`) - Nested rendering, escaping, arrays, XSS prevention
447
- - ✅ **File-Based Routing** (`router.test.js`) - Dynamic routes, catch-all, parameter extraction
448
- - ✅ **State Management** (`state.test.js`, `store.test.js`) - Reactivity, effects, signals, deep updates
449
- - ✅ **HMR System** (`hmr.test.js`) - WebSocket server, client reconnection, file watching
450
- - ✅ **Authentication** (`auth.test.js`) - Registration, login, session management, Argon2id hashing
451
- - ✅ **Validation** (`validation.test.js`) - Zod schemas, email, phone, URL, AfriFieldBuilder
452
- - ✅ **Advanced ORM** (`orm-advanced.test.js`) - QueryBuilder, transactions, migrations, WAL mode
453
- - ✅ **WebSocket** (`websocket.test.js`) - Connections, rooms, presence, message queueing, heartbeats
454
- - ✅ **Middleware** (`middleware.test.js`) - CORS, logging, rate limiting, auth, security headers
455
- - ✅ **Security** (`security.test.js`) - CSRF, injection prevention, token validation
456
- - ✅ **Plugin System** (`plugins.test.js`) - Hook execution, timeouts, isolation, safe/strict modes
457
- - ✅ **Cultural Patterns** (`patterns.test.js`) - SVG output, Kente, Ndebele, Kuba, Masai, Zulu
458
- - ✅ **Accessibility** (`a11y.test.js`) - ARIA roles, keyboard navigation, focus management
459
- - ✅ **Framework Core** (`framework.test.js`) - SDK init, config, component lifecycle
460
-
461
- **Total: 389 passing tests** with zero regressions
462
-
463
- ## 📜 Licensing
464
-
465
- AfriCode is **Dual Licensed**:
466
-
467
- 1. **AGPL v3**: For open-source projects. You must open-source your code if you use AfriCode.
468
- 2. **Commercial**: For proprietary projects. Contact us for a commercial license to build closed-source apps.
469
-
470
- ## 🤝 Contribution
471
-
472
- We welcome contributions! Please see `CONTRIBUTING.md` for details.
473
-
474
- ---
475
-
476
- _Built with ❤️ by the AfriCode Team_
1
+ # 🌍 AfriCode v5 — The Design System of Sovereignty
2
+
3
+ > **Autonomous Framework for African Digital Economy**
4
+ > Bridging AI safety, fintech compliance, and cultural heritage through high-performance web architecture.
5
+
6
+ ![Version: 5.0.13](https://img.shields.io/badge/Version-5.0.13-green.svg)
7
+ ![Status: Cloud Ready](https://img.shields.io/badge/Status-Cloud%20Ready-brightgreen.svg)
8
+ ![AMD AI Cloud: $100 Credits](https://img.shields.io/badge/AMD%20AI%20Cloud-%24100%20Credits-orange.svg)
9
+ ![Alibaba Cloud: Free Tier](https://img.shields.io/badge/Alibaba%20Cloud-Free%20Tier-blue.svg)
10
+ ![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
11
+
12
+ ## Overview
13
+
14
+ AfriCode v5 is an autonomous full-stack framework that "owns" the application lifecycle. Built on **Bun runtime** with **TypeScript-first** architecture, it provides AI-safe component generation, comprehensive fintech compliance, and zero-downtime infrastructure for the African digital economy.
15
+
16
+ ### Strategic Vision: From Tanzania to the Continent
17
+
18
+ Following the rollout framework, AfriCode v5 implements a phased Pan-African expansion:
19
+
20
+ - **Phase 1 (Months 1-4)**: Silicon Dar foundation with TIPS integration
21
+ - **Phase 2 (Months 5-9)**: East African Corridor (Kenya, Uganda, Rwanda)
22
+ - **Phase 3 (Months 10-15)**: West African Hub (Nigeria, Ghana)
23
+ - **Phase 4 (Months 16-24)**: Continental governance and sustainability
24
+
25
+ ## ✨ Autonomous Features
26
+
27
+ ### 🤖 AI-Safe Architecture (A2UI Protocol)
28
+ - **Robot-First Manifest**: Machine-readable component catalog prevents hallucinations
29
+ - **Ethnomathematical Patterns**: Procedural generation of Kente, Ndebele, Shuka motifs
30
+ - **Schema Validation**: Pre-approved components with usage hints and constraints
31
+
32
+ ### 🔐 Fintech Compliance "Hardening"
33
+ - **NIDA CIG Bridge**: VPN-tunneled identity verification with Ed25519 cryptography
34
+ - **TIPS Integration**: Bank of Tanzania-compliant payment flows
35
+ - **AML/FIU Reporting**: Automated regulatory compliance and transaction logging
36
+
37
+ ### ⚡ Zero-Downtime Infrastructure
38
+ - **File-Based Routing**: Automatic `/pages` to URL mapping with dynamic routes
39
+ - **Enhanced HMR**: Session preservation during hot reloads
40
+ - **Bun-Native Runtime**: 5ms startup with WebSocket orchestration
41
+
42
+ ### 🎨 Cultural Resonance
43
+ - **33+ Web Components**: African-themed UI elements with cultural semiotics
44
+ - **Procedural SVG Engine**: Fractal geometry for traditional patterns
45
+ - **Mobile-First Design**: Optimized for African connectivity constraints
46
+ - **Native UI Kit**: Shadcn-style Web Components like `af-ui-button`, `af-ui-card`, and `af-ui-input` for consistent app UI
47
+
48
+ ## 🚀 Quick Start
49
+
50
+ ### Create Autonomous Project
51
+
52
+ ```bash
53
+ # Install globally via NPM
54
+ npm install -g @africode/core
55
+
56
+ # Create new project
57
+ create-africode my-app
58
+ cd my-app
59
+
60
+ # Install dependencies
61
+ bun install
62
+
63
+ # Start autonomous development server
64
+ bun run dev
65
+ ```
66
+
67
+ ### Project Structure (Autonomous)
68
+
69
+ ```
70
+ my-app/
71
+ ├── src/
72
+ │ ├── server.ts # Autonomous server entry
73
+ │ ├── pages/ # File-based routes
74
+ │ │ ├── index.ts # Home page
75
+ │ │ └── api/ # API routes
76
+ │ ├── components/ # Custom components
77
+ │ └── core/ # Framework extensions
78
+ ├── public/ # Static assets
79
+ ├── package.json # NPM configuration
80
+ ├── tsconfig.json # TypeScript config
81
+ └── catalog.json # A2UI component manifest
82
+ ```
83
+
84
+ ### AI-Safe Development
85
+
86
+ The published package includes the agent guidance files so AI assistants can discover the framework rules when the package is installed. These files are bundled as [AGENTS.md](AGENTS.md) and [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md).
87
+
88
+ ```typescript
89
+ // pages/index.ts
90
+ import { html } from '@africode/core';
91
+
92
+ export default function Home() {
93
+ return html`
94
+ <af-app>
95
+ <af-navbar>
96
+ <h1 slot="brand">My AfriCode App</h1>
97
+ </af-navbar>
98
+
99
+ <main>
100
+ <af-hero>
101
+ <h1>AI-Safe Fintech</h1>
102
+ <p>Built with cultural patterns</p>
103
+ <af-kente-pattern complexity="3"></af-kente-pattern>
104
+ </af-hero>
105
+ </main>
106
+ </af-app>
107
+ `;
108
+ }
109
+ ```
110
+
111
+ ## 🏗️ Architecture
112
+
113
+ ### Core Modules
114
+
115
+ | Module | Purpose | Status |
116
+ |--------|---------|--------|
117
+ | `src/index.ts` | Main framework entry | ✅ Complete |
118
+ | `core/a2ui-schema-manager.js` | AI component catalog | ✅ Enhanced |
119
+ | `core/nida-cig-middleware.js` | Identity verification | ✅ VPN + Crypto |
120
+ | `core/lipa-namba-journey.js` | Payment primitives | ✅ BoT Compliant |
121
+ | `core/file-router.js` | File-based routing | ✅ Dynamic routes |
122
+ | `core/enhanced-hmr.js` | Zero-downtime HMR | ✅ Session preservation |
123
+
124
+ ### Cloud Infrastructure
125
+
126
+ #### AMD AI Cloud (Intelligence Layer)
127
+ - **MI300X GPUs**: 192GB HBM3 for LLM inference
128
+ - **$100 Credits**: 200 hours on RunPod community cloud
129
+ - **AfriCode-Coder Model**: Fine-tuned for Tanzanian fintech law
130
+
131
+ #### Alibaba Cloud (Asset Layer)
132
+ - **Model Studio**: Qwen3-Max for complex reasoning
133
+ - **Free Tier**: 1M tokens for initial rollout
134
+ - **Batch Inference**: 50% cost reduction for production
135
+
136
+ ## 🔧 CLI Commands
137
+
138
+ ```bash
139
+ # Development
140
+ africode dev # Start dev server with HMR
141
+ africode build # Production build
142
+ africode lint # Code quality checks
143
+
144
+ # AI Integration
145
+ africode generate a2ui # Update component catalog
146
+ africode generate patterns # Regenerate cultural patterns
147
+
148
+ # Fintech
149
+ africode migrate # Run database migrations
150
+ africode audit # Security and compliance audit
151
+ ```
152
+
153
+ ## 🎭 Ethnomathematical Patterns
154
+
155
+ AfriCode v5 incorporates traditional African geometric principles:
156
+
157
+ ### Kente Weaving (Glide Reflection)
158
+ ```javascript
159
+ import { generateKente } from '@africode/core';
160
+
161
+ const pattern = generateKente({
162
+ baseColor: '#8B4513',
163
+ accentColor: '#DAA520',
164
+ complexity: 3
165
+ });
166
+ ```
167
+
168
+ ### Ndebele Fractals (Recursive Geometry)
169
+ ```javascript
170
+ const ndebele = generateNdebele({
171
+ recursionDepth: 4,
172
+ symmetry: 'rotational',
173
+ colors: ['#FF6B6B', '#4ECDC4', '#45B7D1']
174
+ });
175
+ ```
176
+
177
+ ## 🔒 Fintech Compliance
178
+
179
+ ### NIDA Identity Verification
180
+ ```typescript
181
+ import { NIDAClient } from '@africode/core';
182
+
183
+ const nida = new NIDAClient({
184
+ vpnEnabled: true,
185
+ endpoint: 'https://api.nida.go.tz/cig'
186
+ });
187
+
188
+ const result = await nida.verifyNIN('12345678901234567890', 'PIN');
189
+ ```
190
+
191
+ ### TIPS Payment Processing
192
+ ```typescript
193
+ import { LipaNambaJourney } from '@africode/core';
194
+
195
+ const journey = new LipaNambaJourney();
196
+ const payment = await journey.executeFullJourney({
197
+ merchantId: 'MERCHANT_001',
198
+ customerPhone: '255712345678',
199
+ amount: 50000
200
+ }, customerIdentity, confirmationData);
201
+ ```
202
+
203
+ ## 🌐 Pan-African Expansion
204
+
205
+ ### Phase 1: Tanzania Foundation
206
+ - **TIPS Integration**: Real-time payment processing
207
+ - **NIDA Compliance**: Identity verification for KYC
208
+ - **Cultural Patterns**: Swahili language support
209
+
210
+ ### Phase 2: East African Corridor
211
+ - **PAPSS Bridge**: Cross-border settlement
212
+ - **Regional Hubs**: Nairobi, Kampala, Kigali
213
+ - **Agri-Fintech**: Supply chain integration
214
+
215
+ ### Phase 3: West African Powerhouse
216
+ - **NIBSS Integration**: Nigerian payment systems
217
+ - **Kente Patterns**: Ghanaian cultural motifs
218
+ - **Enterprise Adoption**: Large corporate clients
219
+
220
+ ## 🤝 Community & Incentives
221
+
222
+ ### AfriCode Pioneer Bounty Program
223
+ - **Bug Fixes**: $50-200 for confirmed issues
224
+ - **Features**: $300-1500 for new capabilities
225
+ - **Performance**: $100-500 for optimizations
226
+ - **Cultural Assets**: $50-300 for pattern designs
227
+
228
+ ### Developer Hubs
229
+ - **Silicon Dar**: Dar es Salaam tech district
230
+ - **iHub Nairobi**: East African innovation
231
+ - **CcHUB Lagos**: West African powerhouse
232
+ - **GDG Network**: Google Developer Groups across Africa
233
+
234
+ ## 📊 Performance Metrics
235
+
236
+ - **Startup Time**: <5ms (Bun-native)
237
+ - **Bundle Size**: <100KB (tree-shaken)
238
+ - **Lighthouse Score**: 95+ (mobile-first)
239
+ - **TIPS Transactions**: 490M+ annually supported
240
+ - **NIDA Verifications**: Real-time with VPN security
241
+
242
+ ## 📚 Documentation
243
+
244
+ - [Framework Guide](docs/FRAMEWORK.md)
245
+ - [Component Catalog](catalog.json)
246
+ - [API Reference](docs/API.md)
247
+ - [Fintech Integration](docs/FINTECH.md)
248
+ - [Cultural Patterns](docs/PATTERNS.md)
249
+
250
+ ## 🤝 Contributing
251
+
252
+ We welcome contributions that align with our Pan-African vision:
253
+
254
+ 1. Fork the repository
255
+ 2. Create a feature branch
256
+ 3. Add tests for new functionality
257
+ 4. Ensure AI-safety compliance
258
+ 5. Submit a pull request
259
+
260
+ ## 📄 License
261
+
262
+ **Dual License:**
263
+ - **Open Source**: AGPL v3.0 for community projects
264
+ - **Commercial**: Available for enterprise deployments
265
+
266
+ ## 🌟 Acknowledgments
267
+
268
+ Built for the African developer community with support from:
269
+ - **Bank of Tanzania** (TIPS infrastructure)
270
+ - **National Identification Authority** (NIDA systems)
271
+ - **AMD AI Cloud** ($100 credits for AI development)
272
+ - **Alibaba Cloud** (Model Studio free tier)
273
+ - **African Export-Import Bank** (PAPSS coordination)
274
+
275
+ ---
276
+
277
+ **"Designed for Tanzanians by Tanzanians, Built for Africans by Africans"**
278
+
279
+ 🇹🇿🇰🇪🇺🇬🇷🇼🇳🇬🇬🇭🇿🇦🇲🇦
280
+
281
+ ### Local Development (Framework Contributors)
282
+
283
+ If you are developing the framework itself:
284
+
285
+ 1. Clone and navigate to the framework directory
286
+ 2. Register the link: `bun link`
287
+ 3. Use in another project: `bun link africode`
288
+ 4. Run validation: `bun scripts/validate-fresh-install.js`
289
+
290
+ ### Usage (SDK)
291
+
292
+ Import the core SDK to generate patterns, use the state engine, or handle routing:
293
+
294
+ ```javascript
295
+ import { patterns, store, components } from 'africode';
296
+ import { FileSystemRouter } from 'africode/core/router.js';
297
+
298
+ // Generate a Maasai Shuka pattern
299
+ const shukaPattern = patterns.generateShuka();
300
+ document.body.style.backgroundImage = `url("${shukaPattern}")`;
301
+
302
+ // Use Global State
303
+ store.ui.theme = 'tanzania';
304
+ store.ui.theme; // 'tanzania' - triggers effects on change
305
+
306
+ // Use File-Based Routing
307
+ const router = new FileSystemRouter('./pages');
308
+ const route = await router.matchRoute('/users/123');
309
+ // { page, params: { id: '123' }, path: '/users/[id]' }
310
+ ```
311
+
312
+ ### Usage (Authentication)
313
+
314
+ AfriCode includes built-in session-based authentication:
315
+
316
+ ```javascript
317
+ // API endpoints (automatically available)
318
+ POST / api / auth / register; // { email, username, password, fullname }
319
+ POST / api / auth / login; // { email/username, password }
320
+ POST / api / auth / logout; // Clears session
321
+ GET / api / auth / me; // Current user (requires session)
322
+ POST / api / auth / refresh; // Extend session expiry
323
+ ```
324
+
325
+ Passwords are hashed with **Argon2id** (built into Bun), sessions use **HttpOnly** cookies with **SameSite=Strict** protection.
326
+
327
+ ### Usage (UI Components)
328
+
329
+ Simply import the components to register them as Custom Elements:
330
+
331
+ ```javascript
332
+ import 'africode/components';
333
+ ```
334
+
335
+ Then use them in your HTML:
336
+
337
+ ```html
338
+ <af-navbar theme="tanzania" logo="My App"></af-navbar>
339
+
340
+ <af-kanga-card proverb="Haraka haraka haina baraka.">
341
+ <h3>Project Title</h3>
342
+ <p>Content goes here...</p>
343
+ </af-kanga-card>
344
+
345
+ <af-button onclick="handleClick()">Click Me</af-button>
346
+ ```
347
+
348
+ ### Native AfriCode UI Kit
349
+
350
+ AfriCode now includes a native UI kit with shadcn-inspired Web Components for rapid interface design. The Tailwind starter demonstrates the new UI kit using components like `af-ui-button`, `af-ui-card`, `af-ui-input`, `af-ui-badge`, and `af-ui-switch` in a Shadow DOM-friendly workflow.
351
+
352
+ All `af-`, `af-ui-`, and `af-dashboard-` components are distributed together in the same `@africode/core` package, so they share theme, styles, registry, and versioning.
353
+
354
+ The library is optimized for consistent spacing, elevation, and interactive states across theme-aware apps.
355
+
356
+ Use the Tailwind starter template for a ready-made UI experience:
357
+
358
+ ```bash
359
+ create-africode my-app --template starter-tailwind
360
+ cd my-app
361
+ bun install
362
+ bun run dev
363
+ ```
364
+
365
+ Example usage:
366
+
367
+ ```html
368
+ <af-ui-card variant="outlined" clickable>
369
+ <h3>Actionable Panel</h3>
370
+ <p>Build data-driven experiences with native AfriCode UI components.</p>
371
+ <af-ui-badge variant="success" pill>Ready</af-ui-badge>
372
+ </af-ui-card>
373
+
374
+ <af-ui-input label="Email" placeholder="you@example.com"></af-ui-input>
375
+ <af-ui-switch checked></af-ui-switch>
376
+ <af-ui-button variant="primary">Submit</af-ui-button>
377
+ ```
378
+
379
+ ## ⚙️ Development
380
+
381
+ ### Hot Module Replacement (HMR)
382
+
383
+ During `bun run dev`, any file changes trigger automatic browser refresh. This provides **5-10x faster iteration** compared to manual reloads:
384
+
385
+ ```bash
386
+ bun run dev
387
+ # Edit a file → browser updates instantly
388
+ ```
389
+
390
+ HMR is smart about what to reload:
391
+
392
+ - `.js` files: Full page reload
393
+ - `.css` files: Incremental style update
394
+ - `.html` files: DOM refresh
395
+
396
+ ### File-Based Routing
397
+
398
+ Create files in `pages/` and they automatically become routes:
399
+
400
+ ```
401
+ pages/
402
+ index.js → /
403
+ about.js → /about
404
+ users/
405
+ [id].js → /users/123
406
+ api/
407
+ users.js → POST /api/users
408
+ [...rest].js → Catch-all: /api/foo/bar/baz
409
+ ```
410
+
411
+ Route parameters are automatically extracted: `params.id`, `params.rest`, etc.
412
+
413
+ ## 🏗️ Architecture
414
+
415
+ ```
416
+ core/
417
+ ├── state.js → Proxy-based reactive state management
418
+ ├── patterns.js → Cultural SVG generators (Kente, Shuka, Ndebele, Maasai)
419
+ ├── html.js → XSS-safe tagged template literals
420
+ ├── router.js → File-based routing with dynamic routes
421
+ ├── db.js → SQLite ORM with migrations and transactions
422
+ ├── auth.js → Argon2id password hashing and sessions
423
+ ├── a2ui.js → Generative AI interface protocol (v5)
424
+ ├── compliance.js → Tanzanian fintech regulations (v5)
425
+ ├── bun-runtime.js → High-performance server engine (v5)
426
+ ├── hydration.js → Component system and lifecycle
427
+ └── server/
428
+ ├── auth-endpoints.js → Authentication API endpoints
429
+ ├── router.js → Request routing and handler delegation
430
+ └── render.js → Server-side rendering with HTML injection
431
+
432
+ components/
433
+ ├── base.js → Web Component base class
434
+ ├── 33+ UI components → African-themed elements (buttons, cards, modals)
435
+ └── pattern-showcase.js → Cultural pattern gallery
436
+
437
+ patterns/
438
+ ├── 8 Regional Generators → Procedurally generated SVG patterns
439
+ └── Cultural design system with African semiotics
440
+ ```
441
+
442
+ ## 📊 Test Coverage
443
+
444
+ All core systems have comprehensive test coverage:
445
+
446
+ - ✅ **HTML Templates** (`html.test.js`) - Nested rendering, escaping, arrays, XSS prevention
447
+ - ✅ **File-Based Routing** (`router.test.js`) - Dynamic routes, catch-all, parameter extraction
448
+ - ✅ **State Management** (`state.test.js`, `store.test.js`) - Reactivity, effects, signals, deep updates
449
+ - ✅ **HMR System** (`hmr.test.js`) - WebSocket server, client reconnection, file watching
450
+ - ✅ **Authentication** (`auth.test.js`) - Registration, login, session management, Argon2id hashing
451
+ - ✅ **Validation** (`validation.test.js`) - Zod schemas, email, phone, URL, AfriFieldBuilder
452
+ - ✅ **Advanced ORM** (`orm-advanced.test.js`) - QueryBuilder, transactions, migrations, WAL mode
453
+ - ✅ **WebSocket** (`websocket.test.js`) - Connections, rooms, presence, message queueing, heartbeats
454
+ - ✅ **Middleware** (`middleware.test.js`) - CORS, logging, rate limiting, auth, security headers
455
+ - ✅ **Security** (`security.test.js`) - CSRF, injection prevention, token validation
456
+ - ✅ **Plugin System** (`plugins.test.js`) - Hook execution, timeouts, isolation, safe/strict modes
457
+ - ✅ **Cultural Patterns** (`patterns.test.js`) - SVG output, Kente, Ndebele, Kuba, Masai, Zulu
458
+ - ✅ **Accessibility** (`a11y.test.js`) - ARIA roles, keyboard navigation, focus management
459
+ - ✅ **Framework Core** (`framework.test.js`) - SDK init, config, component lifecycle
460
+
461
+ **Total: 389 passing tests** with zero regressions
462
+
463
+ ## 📜 Licensing
464
+
465
+ AfriCode is **Dual Licensed**:
466
+
467
+ 1. **AGPL v3**: For open-source projects. You must open-source your code if you use AfriCode.
468
+ 2. **Commercial**: For proprietary projects. Contact us for a commercial license to build closed-source apps.
469
+
470
+ ## 🤝 Contribution
471
+
472
+ We welcome contributions! Please see `CONTRIBUTING.md` for details.
473
+
474
+ ---
475
+
476
+ _Built with ❤️ by the AfriCode Team_