@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/AGENTS.md CHANGED
@@ -1,585 +1,585 @@
1
- # ๐Ÿค– AGENTS.md โ€” AfriCode v5.0.0 Robot-First Specification
2
-
3
- **Purpose**: This document defines the canonical technology stack, coding conventions, and framework grammar for all AI agents building on AfriCode. It ensures generated code is "native" and secure.
4
-
5
- **Last Updated**: May 2, 2026
6
- **Framework Version**: 5.0.0
7
- **Target Deployment**: Bun Runtime (v1.3.12+) on AMD AI Cloud & Alibaba Cloud Assets
8
-
9
- ---
10
-
11
- ## ๐Ÿ—๏ธ Canonical Technology Stack
12
-
13
- ### Runtime & Build
14
- - **Runtime**: Bun v1.3.12+ (native, all-in-one: runtime + bundler + test runner)
15
- - **Language**: ES2024 JavaScript (native, no transpilation needed for modern syntax)
16
- - **Module Format**: ESM (native Bun import/export)
17
- - **Build System**: Bun.build() with custom plugins for SVG optimization
18
- - **Development Server**: Bun.serve() with FileSystemRouter for automatic routing
19
-
20
- ### UI & Components
21
- - **Component Model**: Web Components (Custom Elements + Shadow DOM + Slots)
22
- - **State Management**: Proxy-based reactivity (core/state.js) โ€” zero virtual DOM
23
- - **Styling**: CSS Variables + Logical Properties (CSS Containment Level 3)
24
- - **Pattern Generation**: Procedural SVG (no asset uploads needed)
25
- - **Message Protocol**: A2UI v1.0 (core/a2ui.js) for AI-generated interfaces
26
-
27
- ### Data & Persistence
28
- - **Primary Store**: Bun.SQLite (synchronous API, ultra-fast)
29
- - **Migration System**: Bun-native SQL scripts in migrations/ folder
30
- - **Query Pattern**: Direct SQL with type-safe parameter binding
31
- - **Cache Layer**: In-memory Proxy objects with automatic expiry
32
-
33
- ### Security & Compliance
34
- - **Authentication**: Session-based (HttpOnly cookies + SameSite=Strict)
35
- - **Hashing**: Argon2id (built into Bun)
36
- - **Fintech Compliance**: NIDA CIG + TIPS + AML/FIU middleware
37
- - **Cryptography**: Ed25519 for message signing (Bun.crypto)
38
- - **CORS**: Frame-based origin isolation via Web Components
39
-
40
- ---
41
-
42
- ## ๐Ÿ“ Canonical Directory Structure
43
-
44
- ```
45
- AfriCode/
46
- โ”œโ”€โ”€ bin/ # CLI entry points
47
- โ”‚ โ”œโ”€โ”€ africode.js # Main CLI
48
- โ”‚ โ””โ”€โ”€ create-africode.js # Project scaffolder
49
- โ”œโ”€โ”€ core/ # Framework internals (do not modify)
50
- โ”‚ โ”œโ”€โ”€ sdk.js # Main export
51
- โ”‚ โ”œโ”€โ”€ state.js # Reactive state engine
52
- โ”‚ โ”œโ”€โ”€ store.js # Global store singleton
53
- โ”‚ โ”œโ”€โ”€ a2ui.js # AI message protocol
54
- โ”‚ โ”œโ”€โ”€ compliance.js # Fintech middleware
55
- โ”‚ โ”œโ”€โ”€ bun-runtime.js # Bun server initialization
56
- โ”‚ โ”œโ”€โ”€ router.js # FileSystemRouter
57
- โ”‚ โ”œโ”€โ”€ html.js # HTML template utilities
58
- โ”‚ โ”œโ”€โ”€ patterns.js # SVG procedural generation
59
- โ”‚ โ”œโ”€โ”€ validation.js # Input validation schemas
60
- โ”‚ โ”œโ”€โ”€ server/ # Server utilities
61
- โ”‚ โ”‚ โ”œโ”€โ”€ auth.js # Session management
62
- โ”‚ โ”‚ โ”œโ”€โ”€ db.js # Database layer
63
- โ”‚ โ”‚ โ”œโ”€โ”€ render.js # SSR template rendering
64
- โ”‚ โ”‚ โ””โ”€โ”€ router.js # Route handler utilities
65
- โ”‚ โ””โ”€โ”€ cli/ # CLI implementation
66
- โ”‚ โ””โ”€โ”€ commands/ # Command handlers
67
- โ”œโ”€โ”€ components/ # Web Components (pre-approved)
68
- โ”‚ โ”œโ”€โ”€ index.js # Component registry & exports
69
- โ”‚ โ”œโ”€โ”€ base.js # BaseElement class
70
- โ”‚ โ”œโ”€โ”€ button.js # Button component
71
- โ”‚ โ”œโ”€โ”€ card.js # Card component
72
- โ”‚ โ”œโ”€โ”€ cultural-card.js # Cultural card variant
73
- โ”‚ โ”œโ”€โ”€ kanga-card.js # Kanga pattern card
74
- โ”‚ โ”œโ”€โ”€ form.js # Form wrapper
75
- โ”‚ โ”œโ”€โ”€ input.js # Input control
76
- โ”‚ โ”œโ”€โ”€ select.js # Select dropdown
77
- โ”‚ โ”œโ”€โ”€ modal.js # Modal dialog
78
- โ”‚ โ”œโ”€โ”€ navbar.js # Navigation bar
79
- โ”‚ โ””โ”€โ”€ [33 total components]
80
- โ”œโ”€โ”€ patterns/ # Procedural SVG generators
81
- โ”‚ โ”œโ”€โ”€ kente.js # Kente weaving patterns
82
- โ”‚ โ”œโ”€โ”€ shuka.js # Maasai Shuka tartan
83
- โ”‚ โ”œโ”€โ”€ ndebele.js # Ndebele geometric
84
- โ”‚ โ”œโ”€โ”€ kitenge.js # Kitenge florals
85
- โ”‚ โ””โ”€โ”€ [8 regional patterns]
86
- โ”œโ”€โ”€ samples/ # ๐Ÿ†• Hand-curated LLM examples
87
- โ”‚ โ”œโ”€โ”€ README.md # Usage guide for agents
88
- โ”‚ โ”œโ”€โ”€ basic-app/ # Minimal app (5 files)
89
- โ”‚ โ”‚ โ”œโ”€โ”€ package.json
90
- โ”‚ โ”‚ โ”œโ”€โ”€ pages/index.html
91
- โ”‚ โ”‚ โ”œโ”€โ”€ styles/theme.css
92
- โ”‚ โ”‚ โ””โ”€โ”€ core/app.js
93
- โ”‚ โ”œโ”€โ”€ fintech-kiosk/ # Payment flow (Lipa Namba)
94
- โ”‚ โ”‚ โ”œโ”€โ”€ pages/
95
- โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ index.html # Entry
96
- โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ [payment-id].html # Dynamic route
97
- โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ api/payment.js
98
- โ”‚ โ”‚ โ”œโ”€โ”€ components/
99
- โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ payment-form.js
100
- โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ nida-verify.js
101
- โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ confirmation.js
102
- โ”‚ โ”‚ โ””โ”€โ”€ core/
103
- โ”‚ โ”‚ โ”œโ”€โ”€ merchant-service.js
104
- โ”‚ โ”‚ โ””โ”€โ”€ compliance-check.js
105
- โ”‚ โ”œโ”€โ”€ cultural-showcase/ # Pattern display
106
- โ”‚ โ”‚ โ”œโ”€โ”€ pages/
107
- โ”‚ โ”‚ โ”œโ”€โ”€ components/
108
- โ”‚ โ”‚ โ””โ”€โ”€ core/pattern-service.js
109
- โ”‚ โ”œโ”€โ”€ admin-dashboard/ # Multi-user app
110
- โ”‚ โ”‚ โ”œโ”€โ”€ pages/auth/login.html
111
- โ”‚ โ”‚ โ”œโ”€โ”€ pages/dashboard/
112
- โ”‚ โ”‚ โ”œโ”€โ”€ components/data-table.js
113
- โ”‚ โ”‚ โ””โ”€โ”€ middleware/auth-check.js
114
- โ”‚ โ””โ”€โ”€ [8+ regional examples]
115
- โ”œโ”€โ”€ migrations/ # SQL schema versioning
116
- โ”‚ โ””โ”€โ”€ 001_initial_schema.sql # Base schema with compliance fields
117
- โ”œโ”€โ”€ styles/ # Design tokens
118
- โ”‚ โ”œโ”€โ”€ africanity.css # Main theme
119
- โ”‚ โ””โ”€โ”€ typography.css # Type scale
120
- โ”œโ”€โ”€ tests/ # Test pyramid (70/20/10)
121
- โ”‚ โ”œโ”€โ”€ unit/ # 70% unit tests
122
- โ”‚ โ”‚ โ”œโ”€โ”€ state.test.js
123
- โ”‚ โ”‚ โ”œโ”€โ”€ patterns.test.js
124
- โ”‚ โ”‚ โ”œโ”€โ”€ validation.test.js
125
- โ”‚ โ”‚ โ””โ”€โ”€ [compliance tests]
126
- โ”‚ โ”œโ”€โ”€ integration/ # 20% integration tests
127
- โ”‚ โ”‚ โ”œโ”€โ”€ a2ui.test.js
128
- โ”‚ โ”‚ โ”œโ”€โ”€ router.test.js
129
- โ”‚ โ”‚ โ”œโ”€โ”€ nida-flow.test.js # NIDA verification
130
- โ”‚ โ”‚ โ”œโ”€โ”€ tips-payment.test.js # TIPS payment
131
- โ”‚ โ”‚ โ””โ”€โ”€ aml-screening.test.js
132
- โ”‚ โ””โ”€โ”€ e2e/ # 10% critical journeys
133
- โ”‚ โ”œโ”€โ”€ signup-nida.test.js # Register + verify
134
- โ”‚ โ”œโ”€โ”€ lipa-namba.test.js # Payment flow
135
- โ”‚ โ””โ”€โ”€ merchant-checkout.test.js
136
- โ”œโ”€โ”€ package.json # Main entry point metadata
137
- โ”œโ”€โ”€ bunfig.toml # Bun configuration
138
- โ”œโ”€โ”€ tsconfig.json # TypeScript settings (optional)
139
- โ”œโ”€โ”€ AGENTS.md # ๐Ÿ†• This file โ€” AI training spec
140
- โ”œโ”€โ”€ COMPONENT_SCHEMA.json # ๐Ÿ†• Auto-generated component manifest
141
- โ””โ”€โ”€ README.md # User documentation
142
- ```
143
-
144
- ---
145
-
146
- ## ๐ŸŽฏ Coding Conventions (AI Must Follow)
147
-
148
- ### File Naming & Structure
149
- - **Component files**: `kebab-case.js` (e.g., `payment-form.js`)
150
- - **Utility/service files**: `kebab-case.js` (e.g., `merchant-service.js`)
151
- - **Test files**: `*.test.js` (e.g., `nida-flow.test.js`)
152
- - **One component per file** (no monoliths)
153
- - **Named exports for utilities**, default export for components
154
-
155
- ### JavaScript Patterns
156
-
157
- #### โœ… CORRECT
158
- ```javascript
159
- // components/payment-form.js
160
- export class PaymentForm extends HTMLElement {
161
- constructor() {
162
- super();
163
- this.attachShadow({ mode: 'open' });
164
- }
165
-
166
- connectedCallback() {
167
- this.render();
168
- this.setupEventListeners();
169
- }
170
-
171
- render() {
172
- this.shadowRoot.innerHTML = `...`;
173
- }
174
-
175
- setupEventListeners() {
176
- this.addEventListener('submit', (e) => this.handleSubmit(e));
177
- }
178
-
179
- async handleSubmit(e) {
180
- e.preventDefault();
181
- const result = await this.validate();
182
- if (result.ok) this.dispatchEvent(new CustomEvent('success', { detail: result }));
183
- }
184
- }
185
-
186
- customElements.define('af-payment-form', PaymentForm);
187
- ```
188
-
189
- #### โŒ AVOID
190
- ```javascript
191
- // DON'T use React JSX
192
- const PaymentForm = () => <form>...</form>;
193
-
194
- // DON'T use Vue/Svelte syntax
195
- <script setup>
196
- const form = ref(null);
197
- </script>
198
-
199
- // DON'T use external state libraries (Redux, Zustand)
200
- import { store } from '@stores/payment';
201
-
202
- // DON'T use DOM selectors without scoping
203
- document.querySelector('.form'); // โŒ Global scope
204
-
205
- // DO scope to Shadow DOM
206
- this.shadowRoot.querySelector('.form'); // โœ… Encapsulated
207
- ```
208
-
209
- ### State Management Pattern
210
- ```javascript
211
- // core/app-state.js (CORRECT)
212
- import { createReactiveState } from 'africode/core/state.js';
213
-
214
- export const appState = createReactiveState({
215
- user: null,
216
- payment: { amount: 0, status: 'idle' },
217
- nida: { verified: false, nin: null }
218
- });
219
-
220
- // Subscribe to changes
221
- appState.subscribe('payment.status', (newStatus) => {
222
- console.log('Payment status changed:', newStatus);
223
- });
224
- ```
225
-
226
- ### API Route Pattern
227
- ```javascript
228
- // pages/api/payment.js (CORRECT)
229
- export async function POST(request) {
230
- const body = await request.json();
231
-
232
- // Validate input
233
- const validation = validatePayload(body, paymentSchema);
234
- if (!validation.ok) return new Response(validation.error, { status: 400 });
235
-
236
- // Check compliance
237
- const amlResult = await checkAMLScreening(body.amount);
238
- if (!amlResult.ok) return new Response('Transaction blocked', { status: 403 });
239
-
240
- // Process payment
241
- const tx = await processPayment(body);
242
- return new Response(JSON.stringify(tx), { status: 200 });
243
- }
244
- ```
245
-
246
- ### Component Composition
247
- ```javascript
248
- // pages/checkout.html (CORRECT)
249
- <af-payment-form id="form">
250
- <af-nida-verify slot="identity"></af-nida-verify>
251
- <af-card slot="summary">
252
- <h2>Order Summary</h2>
253
- <af-price amount="50000"></af-price>
254
- </af-card>
255
- </af-payment-form>
256
-
257
- <script type="module">
258
- import 'africode/components/index.js';
259
-
260
- const form = document.querySelector('af-payment-form');
261
- form.addEventListener('success', (e) => {
262
- console.log('Payment confirmed:', e.detail);
263
- });
264
- </script>
265
- ```
266
-
267
- ### Error Handling
268
- ```javascript
269
- // Middleware pattern
270
- export function complianceCheck(handler) {
271
- return async (request) => {
272
- try {
273
- const compliant = await validateCompliance(request);
274
- if (!compliant) throw new Error('Compliance failed');
275
- return await handler(request);
276
- } catch (error) {
277
- console.error('Compliance error:', error);
278
- return new Response(
279
- JSON.stringify({ error: error.message, code: 'COMPLIANCE_ERROR' }),
280
- { status: 403 }
281
- );
282
- }
283
- };
284
- }
285
- ```
286
-
287
- ---
288
-
289
- ## ๐Ÿ” Fintech Compliance Grammar
290
-
291
- ### NIDA Verification Flow
292
- ```javascript
293
- // core/server/nida-flow.js
294
- export async function verifyNIDA(nin, pin) {
295
- // Step 1: Sign request with Ed25519 private key
296
- const signature = await signRequest({ nin, timestamp: Date.now() }, privateKey);
297
-
298
- // Step 2: Call CIG endpoint over TLS 1.3
299
- const response = await fetch('https://api.nida.go.tz/cig/verify', {
300
- method: 'POST',
301
- headers: {
302
- 'Content-Type': 'application/json',
303
- 'X-Signature': signature,
304
- 'X-Client-Id': 'africode-v5'
305
- },
306
- body: JSON.stringify({ nin, pin })
307
- });
308
-
309
- // Step 3: Validate response signature
310
- const data = await response.json();
311
- const isValid = await verifySignature(data, data.signature, nidaPublicKey);
312
-
313
- if (!isValid) throw new Error('Invalid signature from NIDA');
314
- return data;
315
- }
316
- ```
317
-
318
- ### TIPS Payment Flow
319
- ```javascript
320
- // core/server/tips-flow.js
321
- export async function initiateP2PPayment(sender, receiver, amount) {
322
- // Validate both parties exist in NIDA
323
- await verifyNIDA(sender.nin);
324
- await verifyNIDA(receiver.nin);
325
-
326
- // Create TIPS transaction
327
- const tipsPayload = {
328
- transactionType: 'P2P',
329
- senderNIN: sender.nin,
330
- receiverNIN: receiver.nin,
331
- amount: amount,
332
- currency: 'TZS',
333
- reference: generateReference(),
334
- timestamp: new Date().toISOString()
335
- };
336
-
337
- // Sign and send to TIPS
338
- const tipsResponse = await callTIPS('/p2p/initiate', tipsPayload);
339
-
340
- // Log for AML/FIU reporting
341
- await logAMLTransaction(tipsResponse.transactionId, tipsPayload);
342
-
343
- return tipsResponse;
344
- }
345
- ```
346
-
347
- ### AML Screening
348
- ```javascript
349
- // core/server/aml-check.js
350
- export async function screenTransaction(amount, nin) {
351
- // Query FIU's AML database
352
- const suspicious = await queryFIUList(nin);
353
- if (suspicious) return { ok: false, reason: 'SUSPICIOUS_PARTY' };
354
-
355
- // Check transaction limits
356
- const dailyTotal = await getDailyTransactionTotal(nin);
357
- if (dailyTotal + amount > 50_000_000) { // 50M TZS daily limit
358
- return { ok: false, reason: 'AMOUNT_EXCEEDS_LIMIT' };
359
- }
360
-
361
- // Queue for AML reporting (24-hour window)
362
- await queueAMLReport({
363
- transactionId: generateId(),
364
- amount,
365
- nin,
366
- timestamp: new Date()
367
- });
368
-
369
- return { ok: true };
370
- }
371
- ```
372
-
373
- ---
374
-
375
- ## ๐Ÿ“ฆ Component Manifest (COMPONENT_SCHEMA.json)
376
-
377
- **Purpose**: Auto-generated JSON schema that whitelists safe components for AI generation. Prevents hallucinated HTML and enforces A2UI compliance.
378
-
379
- **Package note**: `af-`, `af-ui-`, and `af-dashboard-` components are all part of the same unified `@africode/core` package, sharing theme, styles, registry, and versioning.
380
-
381
- **Generated by**: `scripts/generate-component-schema.js`
382
-
383
- ```json
384
- {
385
- "version": "5.0.0",
386
- "timestamp": "2026-05-02T00:00:00Z",
387
- "components": [
388
- {
389
- "tagName": "af-button",
390
- "filePath": "components/button.js",
391
- "slots": ["default"],
392
- "attributes": {
393
- "variant": { "type": "string", "enum": ["primary", "secondary", "ghost"], "default": "primary" },
394
- "size": { "type": "string", "enum": ["sm", "md", "lg"], "default": "md" },
395
- "disabled": { "type": "boolean", "default": false }
396
- },
397
- "events": [
398
- { "name": "click", "detail": { "type": "object" } }
399
- ],
400
- "cssCustomProperties": [
401
- "--af-button-bg",
402
- "--af-button-text",
403
- "--af-button-border"
404
- ],
405
- "example": "<af-button variant=\"primary\" size=\"lg\">Click Me</af-button>",
406
- "securityNotes": "Sanitizes slot content"
407
- },
408
- {
409
- "tagName": "af-nida-verify",
410
- "filePath": "components/nida-verify.js",
411
- "slots": [],
412
- "attributes": {
413
- "nin": { "type": "string", "required": true, "pattern": "^[0-9]{20}$" },
414
- "pin": { "type": "string", "required": true }
415
- },
416
- "events": [
417
- { "name": "verified", "detail": { "verified": true, "user": {} } }
418
- ],
419
- "complianceNotes": "NIDA CIG v2.1 compliant, Ed25519 signed requests"
420
- },
421
- {
422
- "tagName": "af-payment-form",
423
- "filePath": "components/payment-form.js",
424
- "slots": ["identity", "summary"],
425
- "attributes": {
426
- "merchant-id": { "type": "string", "required": true },
427
- "amount": { "type": "number", "required": true }
428
- },
429
- "events": [
430
- { "name": "success", "detail": { "transactionId": "", "status": "" } },
431
- { "name": "error", "detail": { "error": "", "code": "" } }
432
- ],
433
- "complianceNotes": "Auto-screens AML, enforces TIPS standards"
434
- }
435
- ],
436
- "forbiddenPatterns": [
437
- "eval()",
438
- "innerHTML = userInput",
439
- "fetch without CORS headers",
440
- "localStorage for sensitive data"
441
- ]
442
- }
443
- ```
444
-
445
- ---
446
-
447
- ## โšก Bun-Native Optimization Rules
448
-
449
- ### ๐ŸŽฏ Inversion of Control
450
- ```javascript
451
- // โŒ OLD: Library pattern (user calls your code)
452
- import { PaymentForm } from 'africode/components';
453
- const form = new PaymentForm();
454
-
455
- // โœ… NEW: Framework pattern (framework owns lifecycle)
456
- // Just add file: pages/checkout.html
457
- // Bun.serve + FileSystemRouter auto-discovers and serves it
458
- ```
459
-
460
- ### ๐ŸŽฏ Asset Optimization (Bun Plugins)
461
- ```javascript
462
- // bunfig.toml - Bun configuration
463
- [build]
464
- plugins = ["./build-plugins/svg-optimizer.js"]
465
-
466
- // build-plugins/svg-optimizer.js
467
- export default {
468
- name: 'svg-optimizer',
469
- setup(build) {
470
- build.onLoad({ filter: /\.svg$/ }, async (args) => {
471
- const svg = await Bun.file(args.path).text();
472
- const minified = minifySVG(svg);
473
- return {
474
- contents: `export default "${minified}"`,
475
- loader: 'js'
476
- };
477
- });
478
- }
479
- };
480
- ```
481
-
482
- ### ๐ŸŽฏ 5ms Startup Target
483
- - No lazy imports in critical paths
484
- - Bun.SQLite ready before route handling
485
- - All validators pre-compiled at startup
486
- - Compliance certificates pre-loaded in memory
487
-
488
- ---
489
-
490
- ## ๐Ÿงช Test Pyramid (70/20/10)
491
-
492
- ### Unit Tests (70%) โ€” core/*/
493
- ```bash
494
- bun test tests/unit/*.test.js
495
- # Focus: individual functions, validators, pattern generators
496
- # Example: patterns.test.js โ€” verify Kente weave algorithm
497
- ```
498
-
499
- ### Integration Tests (20%) โ€” pages/api/*/
500
- ```bash
501
- bun test tests/integration/*.test.js
502
- # Focus: A2UI rendering, router matching, compliance middleware
503
- # Example: nida-flow.test.js โ€” full verification ceremony
504
- ```
505
-
506
- ### E2E Tests (10%) โ€” critical user journeys
507
- ```bash
508
- bun test tests/e2e/*.test.js
509
- # Focus: signup-nida, lipa-namba payment, merchant-checkout
510
- # Example: lipa-namba.test.js โ€” real TIPS transaction simulation
511
- ```
512
-
513
- ---
514
-
515
- ## ๐Ÿ”ฅ Hot-Reload Middleware
516
-
517
- ```javascript
518
- // core/hmr.js (CORRECT)
519
- export function createHMRServer() {
520
- return new WebSocket('ws://localhost:3001/hmr');
521
- }
522
-
523
- // In Bun.serve, call with --hot flag:
524
- // bun run bin/africode.js dev --hot
525
- // This enables:
526
- // - File watching via Bun.watch()
527
- // - Soft reloads (no session loss)
528
- // - Database connection persistence
529
- // - In-memory state retained
530
- ```
531
-
532
- ---
533
-
534
- ## ๐Ÿ“‹ AI Agent Constraints
535
-
536
- When building apps with this spec, AI agents MUST:
537
-
538
- 1. **Only use pre-approved components** from COMPONENT_SCHEMA.json
539
- 2. **Never generate raw HTML** โ€” use af-* Web Components
540
- 3. **Prefer AfriCode-native patterns first**; use external libraries only when they provide a clear, justified enhancement and are already supported by the project
541
- 4. **Always validate inputs** with schemas in core/validation.js
542
- 5. **Always call compliance middleware** before processing payments
543
- 6. **Always sign NIDA requests** with Ed25519 keys
544
- 7. **Always log transactions** for AML/FIU reporting
545
- 8. **Always use Bun-native APIs** (no Node.js polyfills)
546
-
547
- ---
548
-
549
- ## ๐Ÿš€ Quick Verification
550
-
551
- To verify an AI-generated app is "native" to AfriCode:
552
-
553
- ```bash
554
- # Check component usage
555
- grep -r "<af-" pages/ components/ | wc -l # Should be > 0
556
-
557
- # Check for forbidden patterns
558
- grep -r "eval(" pages/ components/ # Should be empty
559
- grep -r "innerHTML =" pages/ components/ # Should only be in Shadow DOM
560
-
561
- # Check Bun-native compliance
562
- grep -r "fetch(" pages/ | grep -v "CORS" # Should all have headers
563
-
564
- # Run test pyramid
565
- bun test tests/unit/ # 70% should pass instantly
566
- bun test tests/integration/ # 20% should pass in < 5s
567
- bun test tests/e2e/ # 10% critical journeys
568
- ```
569
-
570
- ---
571
-
572
- ## ๐Ÿ“š Resources
573
-
574
- - **Framework API**: https://github.com/africode/framework
575
- - **Bun Docs**: https://bun.sh/docs
576
- - **Web Components**: https://developer.mozilla.org/en-US/docs/Web/Web_Components
577
- - **NIDA CIG v2.1**: https://nida.go.tz/cig/docs
578
- - **TIPS Standards**: https://tips.go.tz/standards
579
- - **AML/FIU**: https://fiu.go.tz/reporting
580
-
581
- ---
582
-
583
- **Last Reviewed**: May 2, 2026
584
- **Next Review**: August 2, 2026 (quarterly)
585
- **Contact**: framework@africode.dev
1
+ # ๐Ÿค– AGENTS.md โ€” AfriCode v5.0.0 Robot-First Specification
2
+
3
+ **Purpose**: This document defines the canonical technology stack, coding conventions, and framework grammar for all AI agents building on AfriCode. It ensures generated code is "native" and secure.
4
+
5
+ **Last Updated**: May 2, 2026
6
+ **Framework Version**: 5.0.0
7
+ **Target Deployment**: Bun Runtime (v1.3.12+) on AMD AI Cloud & Alibaba Cloud Assets
8
+
9
+ ---
10
+
11
+ ## ๐Ÿ—๏ธ Canonical Technology Stack
12
+
13
+ ### Runtime & Build
14
+ - **Runtime**: Bun v1.3.12+ (native, all-in-one: runtime + bundler + test runner)
15
+ - **Language**: ES2024 JavaScript (native, no transpilation needed for modern syntax)
16
+ - **Module Format**: ESM (native Bun import/export)
17
+ - **Build System**: Bun.build() with custom plugins for SVG optimization
18
+ - **Development Server**: Bun.serve() with FileSystemRouter for automatic routing
19
+
20
+ ### UI & Components
21
+ - **Component Model**: Web Components (Custom Elements + Shadow DOM + Slots)
22
+ - **State Management**: Proxy-based reactivity (core/state.js) โ€” zero virtual DOM
23
+ - **Styling**: CSS Variables + Logical Properties (CSS Containment Level 3)
24
+ - **Pattern Generation**: Procedural SVG (no asset uploads needed)
25
+ - **Message Protocol**: A2UI v1.0 (core/a2ui.js) for AI-generated interfaces
26
+
27
+ ### Data & Persistence
28
+ - **Primary Store**: Bun.SQLite (synchronous API, ultra-fast)
29
+ - **Migration System**: Bun-native SQL scripts in migrations/ folder
30
+ - **Query Pattern**: Direct SQL with type-safe parameter binding
31
+ - **Cache Layer**: In-memory Proxy objects with automatic expiry
32
+
33
+ ### Security & Compliance
34
+ - **Authentication**: Session-based (HttpOnly cookies + SameSite=Strict)
35
+ - **Hashing**: Argon2id (built into Bun)
36
+ - **Fintech Compliance**: NIDA CIG + TIPS + AML/FIU middleware
37
+ - **Cryptography**: Ed25519 for message signing (Bun.crypto)
38
+ - **CORS**: Frame-based origin isolation via Web Components
39
+
40
+ ---
41
+
42
+ ## ๐Ÿ“ Canonical Directory Structure
43
+
44
+ ```
45
+ AfriCode/
46
+ โ”œโ”€โ”€ bin/ # CLI entry points
47
+ โ”‚ โ”œโ”€โ”€ africode.js # Main CLI
48
+ โ”‚ โ””โ”€โ”€ create-africode.js # Project scaffolder
49
+ โ”œโ”€โ”€ core/ # Framework internals (do not modify)
50
+ โ”‚ โ”œโ”€โ”€ sdk.js # Main export
51
+ โ”‚ โ”œโ”€โ”€ state.js # Reactive state engine
52
+ โ”‚ โ”œโ”€โ”€ store.js # Global store singleton
53
+ โ”‚ โ”œโ”€โ”€ a2ui.js # AI message protocol
54
+ โ”‚ โ”œโ”€โ”€ compliance.js # Fintech middleware
55
+ โ”‚ โ”œโ”€โ”€ bun-runtime.js # Bun server initialization
56
+ โ”‚ โ”œโ”€โ”€ router.js # FileSystemRouter
57
+ โ”‚ โ”œโ”€โ”€ html.js # HTML template utilities
58
+ โ”‚ โ”œโ”€โ”€ patterns.js # SVG procedural generation
59
+ โ”‚ โ”œโ”€โ”€ validation.js # Input validation schemas
60
+ โ”‚ โ”œโ”€โ”€ server/ # Server utilities
61
+ โ”‚ โ”‚ โ”œโ”€โ”€ auth.js # Session management
62
+ โ”‚ โ”‚ โ”œโ”€โ”€ db.js # Database layer
63
+ โ”‚ โ”‚ โ”œโ”€โ”€ render.js # SSR template rendering
64
+ โ”‚ โ”‚ โ””โ”€โ”€ router.js # Route handler utilities
65
+ โ”‚ โ””โ”€โ”€ cli/ # CLI implementation
66
+ โ”‚ โ””โ”€โ”€ commands/ # Command handlers
67
+ โ”œโ”€โ”€ components/ # Web Components (pre-approved)
68
+ โ”‚ โ”œโ”€โ”€ index.js # Component registry & exports
69
+ โ”‚ โ”œโ”€โ”€ base.js # BaseElement class
70
+ โ”‚ โ”œโ”€โ”€ button.js # Button component
71
+ โ”‚ โ”œโ”€โ”€ card.js # Card component
72
+ โ”‚ โ”œโ”€โ”€ cultural-card.js # Cultural card variant
73
+ โ”‚ โ”œโ”€โ”€ kanga-card.js # Kanga pattern card
74
+ โ”‚ โ”œโ”€โ”€ form.js # Form wrapper
75
+ โ”‚ โ”œโ”€โ”€ input.js # Input control
76
+ โ”‚ โ”œโ”€โ”€ select.js # Select dropdown
77
+ โ”‚ โ”œโ”€โ”€ modal.js # Modal dialog
78
+ โ”‚ โ”œโ”€โ”€ navbar.js # Navigation bar
79
+ โ”‚ โ””โ”€โ”€ [33 total components]
80
+ โ”œโ”€โ”€ patterns/ # Procedural SVG generators
81
+ โ”‚ โ”œโ”€โ”€ kente.js # Kente weaving patterns
82
+ โ”‚ โ”œโ”€โ”€ shuka.js # Maasai Shuka tartan
83
+ โ”‚ โ”œโ”€โ”€ ndebele.js # Ndebele geometric
84
+ โ”‚ โ”œโ”€โ”€ kitenge.js # Kitenge florals
85
+ โ”‚ โ””โ”€โ”€ [8 regional patterns]
86
+ โ”œโ”€โ”€ samples/ # ๐Ÿ†• Hand-curated LLM examples
87
+ โ”‚ โ”œโ”€โ”€ README.md # Usage guide for agents
88
+ โ”‚ โ”œโ”€โ”€ basic-app/ # Minimal app (5 files)
89
+ โ”‚ โ”‚ โ”œโ”€โ”€ package.json
90
+ โ”‚ โ”‚ โ”œโ”€โ”€ pages/index.html
91
+ โ”‚ โ”‚ โ”œโ”€โ”€ styles/theme.css
92
+ โ”‚ โ”‚ โ””โ”€โ”€ core/app.js
93
+ โ”‚ โ”œโ”€โ”€ fintech-kiosk/ # Payment flow (Lipa Namba)
94
+ โ”‚ โ”‚ โ”œโ”€โ”€ pages/
95
+ โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ index.html # Entry
96
+ โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ [payment-id].html # Dynamic route
97
+ โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ api/payment.js
98
+ โ”‚ โ”‚ โ”œโ”€โ”€ components/
99
+ โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ payment-form.js
100
+ โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ nida-verify.js
101
+ โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ confirmation.js
102
+ โ”‚ โ”‚ โ””โ”€โ”€ core/
103
+ โ”‚ โ”‚ โ”œโ”€โ”€ merchant-service.js
104
+ โ”‚ โ”‚ โ””โ”€โ”€ compliance-check.js
105
+ โ”‚ โ”œโ”€โ”€ cultural-showcase/ # Pattern display
106
+ โ”‚ โ”‚ โ”œโ”€โ”€ pages/
107
+ โ”‚ โ”‚ โ”œโ”€โ”€ components/
108
+ โ”‚ โ”‚ โ””โ”€โ”€ core/pattern-service.js
109
+ โ”‚ โ”œโ”€โ”€ admin-dashboard/ # Multi-user app
110
+ โ”‚ โ”‚ โ”œโ”€โ”€ pages/auth/login.html
111
+ โ”‚ โ”‚ โ”œโ”€โ”€ pages/dashboard/
112
+ โ”‚ โ”‚ โ”œโ”€โ”€ components/data-table.js
113
+ โ”‚ โ”‚ โ””โ”€โ”€ middleware/auth-check.js
114
+ โ”‚ โ””โ”€โ”€ [8+ regional examples]
115
+ โ”œโ”€โ”€ migrations/ # SQL schema versioning
116
+ โ”‚ โ””โ”€โ”€ 001_initial_schema.sql # Base schema with compliance fields
117
+ โ”œโ”€โ”€ styles/ # Design tokens
118
+ โ”‚ โ”œโ”€โ”€ africanity.css # Main theme
119
+ โ”‚ โ””โ”€โ”€ typography.css # Type scale
120
+ โ”œโ”€โ”€ tests/ # Test pyramid (70/20/10)
121
+ โ”‚ โ”œโ”€โ”€ unit/ # 70% unit tests
122
+ โ”‚ โ”‚ โ”œโ”€โ”€ state.test.js
123
+ โ”‚ โ”‚ โ”œโ”€โ”€ patterns.test.js
124
+ โ”‚ โ”‚ โ”œโ”€โ”€ validation.test.js
125
+ โ”‚ โ”‚ โ””โ”€โ”€ [compliance tests]
126
+ โ”‚ โ”œโ”€โ”€ integration/ # 20% integration tests
127
+ โ”‚ โ”‚ โ”œโ”€โ”€ a2ui.test.js
128
+ โ”‚ โ”‚ โ”œโ”€โ”€ router.test.js
129
+ โ”‚ โ”‚ โ”œโ”€โ”€ nida-flow.test.js # NIDA verification
130
+ โ”‚ โ”‚ โ”œโ”€โ”€ tips-payment.test.js # TIPS payment
131
+ โ”‚ โ”‚ โ””โ”€โ”€ aml-screening.test.js
132
+ โ”‚ โ””โ”€โ”€ e2e/ # 10% critical journeys
133
+ โ”‚ โ”œโ”€โ”€ signup-nida.test.js # Register + verify
134
+ โ”‚ โ”œโ”€โ”€ lipa-namba.test.js # Payment flow
135
+ โ”‚ โ””โ”€โ”€ merchant-checkout.test.js
136
+ โ”œโ”€โ”€ package.json # Main entry point metadata
137
+ โ”œโ”€โ”€ bunfig.toml # Bun configuration
138
+ โ”œโ”€โ”€ tsconfig.json # TypeScript settings (optional)
139
+ โ”œโ”€โ”€ AGENTS.md # ๐Ÿ†• This file โ€” AI training spec
140
+ โ”œโ”€โ”€ COMPONENT_SCHEMA.json # ๐Ÿ†• Auto-generated component manifest
141
+ โ””โ”€โ”€ README.md # User documentation
142
+ ```
143
+
144
+ ---
145
+
146
+ ## ๐ŸŽฏ Coding Conventions (AI Must Follow)
147
+
148
+ ### File Naming & Structure
149
+ - **Component files**: `kebab-case.js` (e.g., `payment-form.js`)
150
+ - **Utility/service files**: `kebab-case.js` (e.g., `merchant-service.js`)
151
+ - **Test files**: `*.test.js` (e.g., `nida-flow.test.js`)
152
+ - **One component per file** (no monoliths)
153
+ - **Named exports for utilities**, default export for components
154
+
155
+ ### JavaScript Patterns
156
+
157
+ #### โœ… CORRECT
158
+ ```javascript
159
+ // components/payment-form.js
160
+ export class PaymentForm extends HTMLElement {
161
+ constructor() {
162
+ super();
163
+ this.attachShadow({ mode: 'open' });
164
+ }
165
+
166
+ connectedCallback() {
167
+ this.render();
168
+ this.setupEventListeners();
169
+ }
170
+
171
+ render() {
172
+ this.shadowRoot.innerHTML = `...`;
173
+ }
174
+
175
+ setupEventListeners() {
176
+ this.addEventListener('submit', (e) => this.handleSubmit(e));
177
+ }
178
+
179
+ async handleSubmit(e) {
180
+ e.preventDefault();
181
+ const result = await this.validate();
182
+ if (result.ok) this.dispatchEvent(new CustomEvent('success', { detail: result }));
183
+ }
184
+ }
185
+
186
+ customElements.define('af-payment-form', PaymentForm);
187
+ ```
188
+
189
+ #### โŒ AVOID
190
+ ```javascript
191
+ // DON'T use React JSX
192
+ const PaymentForm = () => <form>...</form>;
193
+
194
+ // DON'T use Vue/Svelte syntax
195
+ <script setup>
196
+ const form = ref(null);
197
+ </script>
198
+
199
+ // DON'T use external state libraries (Redux, Zustand)
200
+ import { store } from '@stores/payment';
201
+
202
+ // DON'T use DOM selectors without scoping
203
+ document.querySelector('.form'); // โŒ Global scope
204
+
205
+ // DO scope to Shadow DOM
206
+ this.shadowRoot.querySelector('.form'); // โœ… Encapsulated
207
+ ```
208
+
209
+ ### State Management Pattern
210
+ ```javascript
211
+ // core/app-state.js (CORRECT)
212
+ import { createReactiveState } from 'africode/core/state.js';
213
+
214
+ export const appState = createReactiveState({
215
+ user: null,
216
+ payment: { amount: 0, status: 'idle' },
217
+ nida: { verified: false, nin: null }
218
+ });
219
+
220
+ // Subscribe to changes
221
+ appState.subscribe('payment.status', (newStatus) => {
222
+ console.log('Payment status changed:', newStatus);
223
+ });
224
+ ```
225
+
226
+ ### API Route Pattern
227
+ ```javascript
228
+ // pages/api/payment.js (CORRECT)
229
+ export async function POST(request) {
230
+ const body = await request.json();
231
+
232
+ // Validate input
233
+ const validation = validatePayload(body, paymentSchema);
234
+ if (!validation.ok) return new Response(validation.error, { status: 400 });
235
+
236
+ // Check compliance
237
+ const amlResult = await checkAMLScreening(body.amount);
238
+ if (!amlResult.ok) return new Response('Transaction blocked', { status: 403 });
239
+
240
+ // Process payment
241
+ const tx = await processPayment(body);
242
+ return new Response(JSON.stringify(tx), { status: 200 });
243
+ }
244
+ ```
245
+
246
+ ### Component Composition
247
+ ```javascript
248
+ // pages/checkout.html (CORRECT)
249
+ <af-payment-form id="form">
250
+ <af-nida-verify slot="identity"></af-nida-verify>
251
+ <af-card slot="summary">
252
+ <h2>Order Summary</h2>
253
+ <af-price amount="50000"></af-price>
254
+ </af-card>
255
+ </af-payment-form>
256
+
257
+ <script type="module">
258
+ import 'africode/components/index.js';
259
+
260
+ const form = document.querySelector('af-payment-form');
261
+ form.addEventListener('success', (e) => {
262
+ console.log('Payment confirmed:', e.detail);
263
+ });
264
+ </script>
265
+ ```
266
+
267
+ ### Error Handling
268
+ ```javascript
269
+ // Middleware pattern
270
+ export function complianceCheck(handler) {
271
+ return async (request) => {
272
+ try {
273
+ const compliant = await validateCompliance(request);
274
+ if (!compliant) throw new Error('Compliance failed');
275
+ return await handler(request);
276
+ } catch (error) {
277
+ console.error('Compliance error:', error);
278
+ return new Response(
279
+ JSON.stringify({ error: error.message, code: 'COMPLIANCE_ERROR' }),
280
+ { status: 403 }
281
+ );
282
+ }
283
+ };
284
+ }
285
+ ```
286
+
287
+ ---
288
+
289
+ ## ๐Ÿ” Fintech Compliance Grammar
290
+
291
+ ### NIDA Verification Flow
292
+ ```javascript
293
+ // core/server/nida-flow.js
294
+ export async function verifyNIDA(nin, pin) {
295
+ // Step 1: Sign request with Ed25519 private key
296
+ const signature = await signRequest({ nin, timestamp: Date.now() }, privateKey);
297
+
298
+ // Step 2: Call CIG endpoint over TLS 1.3
299
+ const response = await fetch('https://api.nida.go.tz/cig/verify', {
300
+ method: 'POST',
301
+ headers: {
302
+ 'Content-Type': 'application/json',
303
+ 'X-Signature': signature,
304
+ 'X-Client-Id': 'africode-v5'
305
+ },
306
+ body: JSON.stringify({ nin, pin })
307
+ });
308
+
309
+ // Step 3: Validate response signature
310
+ const data = await response.json();
311
+ const isValid = await verifySignature(data, data.signature, nidaPublicKey);
312
+
313
+ if (!isValid) throw new Error('Invalid signature from NIDA');
314
+ return data;
315
+ }
316
+ ```
317
+
318
+ ### TIPS Payment Flow
319
+ ```javascript
320
+ // core/server/tips-flow.js
321
+ export async function initiateP2PPayment(sender, receiver, amount) {
322
+ // Validate both parties exist in NIDA
323
+ await verifyNIDA(sender.nin);
324
+ await verifyNIDA(receiver.nin);
325
+
326
+ // Create TIPS transaction
327
+ const tipsPayload = {
328
+ transactionType: 'P2P',
329
+ senderNIN: sender.nin,
330
+ receiverNIN: receiver.nin,
331
+ amount: amount,
332
+ currency: 'TZS',
333
+ reference: generateReference(),
334
+ timestamp: new Date().toISOString()
335
+ };
336
+
337
+ // Sign and send to TIPS
338
+ const tipsResponse = await callTIPS('/p2p/initiate', tipsPayload);
339
+
340
+ // Log for AML/FIU reporting
341
+ await logAMLTransaction(tipsResponse.transactionId, tipsPayload);
342
+
343
+ return tipsResponse;
344
+ }
345
+ ```
346
+
347
+ ### AML Screening
348
+ ```javascript
349
+ // core/server/aml-check.js
350
+ export async function screenTransaction(amount, nin) {
351
+ // Query FIU's AML database
352
+ const suspicious = await queryFIUList(nin);
353
+ if (suspicious) return { ok: false, reason: 'SUSPICIOUS_PARTY' };
354
+
355
+ // Check transaction limits
356
+ const dailyTotal = await getDailyTransactionTotal(nin);
357
+ if (dailyTotal + amount > 50_000_000) { // 50M TZS daily limit
358
+ return { ok: false, reason: 'AMOUNT_EXCEEDS_LIMIT' };
359
+ }
360
+
361
+ // Queue for AML reporting (24-hour window)
362
+ await queueAMLReport({
363
+ transactionId: generateId(),
364
+ amount,
365
+ nin,
366
+ timestamp: new Date()
367
+ });
368
+
369
+ return { ok: true };
370
+ }
371
+ ```
372
+
373
+ ---
374
+
375
+ ## ๐Ÿ“ฆ Component Manifest (COMPONENT_SCHEMA.json)
376
+
377
+ **Purpose**: Auto-generated JSON schema that whitelists safe components for AI generation. Prevents hallucinated HTML and enforces A2UI compliance.
378
+
379
+ **Package note**: `af-`, `af-ui-`, and `af-dashboard-` components are all part of the same unified `@africode/core` package, sharing theme, styles, registry, and versioning.
380
+
381
+ **Generated by**: `scripts/generate-component-schema.js`
382
+
383
+ ```json
384
+ {
385
+ "version": "5.0.0",
386
+ "timestamp": "2026-05-02T00:00:00Z",
387
+ "components": [
388
+ {
389
+ "tagName": "af-button",
390
+ "filePath": "components/button.js",
391
+ "slots": ["default"],
392
+ "attributes": {
393
+ "variant": { "type": "string", "enum": ["primary", "secondary", "ghost"], "default": "primary" },
394
+ "size": { "type": "string", "enum": ["sm", "md", "lg"], "default": "md" },
395
+ "disabled": { "type": "boolean", "default": false }
396
+ },
397
+ "events": [
398
+ { "name": "click", "detail": { "type": "object" } }
399
+ ],
400
+ "cssCustomProperties": [
401
+ "--af-button-bg",
402
+ "--af-button-text",
403
+ "--af-button-border"
404
+ ],
405
+ "example": "<af-button variant=\"primary\" size=\"lg\">Click Me</af-button>",
406
+ "securityNotes": "Sanitizes slot content"
407
+ },
408
+ {
409
+ "tagName": "af-nida-verify",
410
+ "filePath": "components/nida-verify.js",
411
+ "slots": [],
412
+ "attributes": {
413
+ "nin": { "type": "string", "required": true, "pattern": "^[0-9]{20}$" },
414
+ "pin": { "type": "string", "required": true }
415
+ },
416
+ "events": [
417
+ { "name": "verified", "detail": { "verified": true, "user": {} } }
418
+ ],
419
+ "complianceNotes": "NIDA CIG v2.1 compliant, Ed25519 signed requests"
420
+ },
421
+ {
422
+ "tagName": "af-payment-form",
423
+ "filePath": "components/payment-form.js",
424
+ "slots": ["identity", "summary"],
425
+ "attributes": {
426
+ "merchant-id": { "type": "string", "required": true },
427
+ "amount": { "type": "number", "required": true }
428
+ },
429
+ "events": [
430
+ { "name": "success", "detail": { "transactionId": "", "status": "" } },
431
+ { "name": "error", "detail": { "error": "", "code": "" } }
432
+ ],
433
+ "complianceNotes": "Auto-screens AML, enforces TIPS standards"
434
+ }
435
+ ],
436
+ "forbiddenPatterns": [
437
+ "eval()",
438
+ "innerHTML = userInput",
439
+ "fetch without CORS headers",
440
+ "localStorage for sensitive data"
441
+ ]
442
+ }
443
+ ```
444
+
445
+ ---
446
+
447
+ ## โšก Bun-Native Optimization Rules
448
+
449
+ ### ๐ŸŽฏ Inversion of Control
450
+ ```javascript
451
+ // โŒ OLD: Library pattern (user calls your code)
452
+ import { PaymentForm } from 'africode/components';
453
+ const form = new PaymentForm();
454
+
455
+ // โœ… NEW: Framework pattern (framework owns lifecycle)
456
+ // Just add file: pages/checkout.html
457
+ // Bun.serve + FileSystemRouter auto-discovers and serves it
458
+ ```
459
+
460
+ ### ๐ŸŽฏ Asset Optimization (Bun Plugins)
461
+ ```javascript
462
+ // bunfig.toml - Bun configuration
463
+ [build]
464
+ plugins = ["./build-plugins/svg-optimizer.js"]
465
+
466
+ // build-plugins/svg-optimizer.js
467
+ export default {
468
+ name: 'svg-optimizer',
469
+ setup(build) {
470
+ build.onLoad({ filter: /\.svg$/ }, async (args) => {
471
+ const svg = await Bun.file(args.path).text();
472
+ const minified = minifySVG(svg);
473
+ return {
474
+ contents: `export default "${minified}"`,
475
+ loader: 'js'
476
+ };
477
+ });
478
+ }
479
+ };
480
+ ```
481
+
482
+ ### ๐ŸŽฏ 5ms Startup Target
483
+ - No lazy imports in critical paths
484
+ - Bun.SQLite ready before route handling
485
+ - All validators pre-compiled at startup
486
+ - Compliance certificates pre-loaded in memory
487
+
488
+ ---
489
+
490
+ ## ๐Ÿงช Test Pyramid (70/20/10)
491
+
492
+ ### Unit Tests (70%) โ€” core/*/
493
+ ```bash
494
+ bun test tests/unit/*.test.js
495
+ # Focus: individual functions, validators, pattern generators
496
+ # Example: patterns.test.js โ€” verify Kente weave algorithm
497
+ ```
498
+
499
+ ### Integration Tests (20%) โ€” pages/api/*/
500
+ ```bash
501
+ bun test tests/integration/*.test.js
502
+ # Focus: A2UI rendering, router matching, compliance middleware
503
+ # Example: nida-flow.test.js โ€” full verification ceremony
504
+ ```
505
+
506
+ ### E2E Tests (10%) โ€” critical user journeys
507
+ ```bash
508
+ bun test tests/e2e/*.test.js
509
+ # Focus: signup-nida, lipa-namba payment, merchant-checkout
510
+ # Example: lipa-namba.test.js โ€” real TIPS transaction simulation
511
+ ```
512
+
513
+ ---
514
+
515
+ ## ๐Ÿ”ฅ Hot-Reload Middleware
516
+
517
+ ```javascript
518
+ // core/hmr.js (CORRECT)
519
+ export function createHMRServer() {
520
+ return new WebSocket('ws://localhost:3001/hmr');
521
+ }
522
+
523
+ // In Bun.serve, call with --hot flag:
524
+ // bun run bin/africode.js dev --hot
525
+ // This enables:
526
+ // - File watching via Bun.watch()
527
+ // - Soft reloads (no session loss)
528
+ // - Database connection persistence
529
+ // - In-memory state retained
530
+ ```
531
+
532
+ ---
533
+
534
+ ## ๐Ÿ“‹ AI Agent Constraints
535
+
536
+ When building apps with this spec, AI agents MUST:
537
+
538
+ 1. **Only use pre-approved components** from COMPONENT_SCHEMA.json
539
+ 2. **Never generate raw HTML** โ€” use af-* Web Components
540
+ 3. **Prefer AfriCode-native patterns first**; use external libraries only when they provide a clear, justified enhancement and are already supported by the project
541
+ 4. **Always validate inputs** with schemas in core/validation.js
542
+ 5. **Always call compliance middleware** before processing payments
543
+ 6. **Always sign NIDA requests** with Ed25519 keys
544
+ 7. **Always log transactions** for AML/FIU reporting
545
+ 8. **Always use Bun-native APIs** (no Node.js polyfills)
546
+
547
+ ---
548
+
549
+ ## ๐Ÿš€ Quick Verification
550
+
551
+ To verify an AI-generated app is "native" to AfriCode:
552
+
553
+ ```bash
554
+ # Check component usage
555
+ grep -r "<af-" pages/ components/ | wc -l # Should be > 0
556
+
557
+ # Check for forbidden patterns
558
+ grep -r "eval(" pages/ components/ # Should be empty
559
+ grep -r "innerHTML =" pages/ components/ # Should only be in Shadow DOM
560
+
561
+ # Check Bun-native compliance
562
+ grep -r "fetch(" pages/ | grep -v "CORS" # Should all have headers
563
+
564
+ # Run test pyramid
565
+ bun test tests/unit/ # 70% should pass instantly
566
+ bun test tests/integration/ # 20% should pass in < 5s
567
+ bun test tests/e2e/ # 10% critical journeys
568
+ ```
569
+
570
+ ---
571
+
572
+ ## ๐Ÿ“š Resources
573
+
574
+ - **Framework API**: https://github.com/africode/framework
575
+ - **Bun Docs**: https://bun.sh/docs
576
+ - **Web Components**: https://developer.mozilla.org/en-US/docs/Web/Web_Components
577
+ - **NIDA CIG v2.1**: https://nida.go.tz/cig/docs
578
+ - **TIPS Standards**: https://tips.go.tz/standards
579
+ - **AML/FIU**: https://fiu.go.tz/reporting
580
+
581
+ ---
582
+
583
+ **Last Reviewed**: May 2, 2026
584
+ **Next Review**: August 2, 2026 (quarterly)
585
+ **Contact**: framework@africode.dev