feat: build an iapp (#13)

Author: akugone

.vitepress/sidebar.ts

@@ -348,15 +348,14 @@ export function getSidebar() {
           { text: '❓ What Is an iApp?', link: '/build-iapp/what-is-iapp' },
           {
             text: '📖 Guides',
-            link: '/build-iapp/guides',
             items: [
               {
-                text: 'Manage Your iApps',
-                link: '/build-iapp/guides/manage-iapps',
+                text: 'Build and Deploy your iApps',
+                link: '/build-iapp/guides/build-&-deploy-iapp',
               },
               {
-                text: 'Orders (how they work, how to manage them)',
-                link: '/build-iapp/guides/orders',
+                text: 'Manage your iApps',
+                link: '/build-iapp/guides/manage-iapp',
               },
               {
                 text: 'Inputs and Outputs (types, differences, formats)',
@@ -374,20 +373,11 @@ export function getSidebar() {
                 text: 'How to Get and Decrypt Results',
                 link: '/build-iapp/guides/how-to-get-and-decrypt-results',
               },
-              {
-                text: 'AI Frameworks',
-                link: '/build-iapp/guides/ai-frameworks',
-              },
-              {
-                text: 'Other Emerging Trends',
-                link: '/build-iapp/guides/other-emerging-trends',
-              },
             ],
           },
           {
             text: '🤖 iApp Generator',
             link: '/build-iapp/iapp-generator',
-            collapsed: true,
             items: [
               {
                 text: 'Getting Started',
@@ -397,20 +387,8 @@ export function getSidebar() {
                 text: 'Building Your iApp',
                 link: '/build-iapp/iapp-generator/building-your-iexec-app',
               },
-              {
-                text: 'References',
-                link: '/build-iapp/iapp-generator/references',
-              },
-              {
-                text: 'Advanced Creation',
-                link: '/build-iapp/iapp-generator/advanced-creation',
-              },
             ],
           },
-          {
-            text: '🔧 Protocol-Level Guides',
-            link: '/build-iapp/iapp-generator/protocol-level-guides',
-          },
         ],
       },
     ],

src/build-iapp/guides/ai-frameworks.md

@@ -0,0 +1,115 @@
+---
+title: Build and Deploy an iApp?
+description:
+  How to build an confidential iexec application and deploy it on iexec protocol
+---
+
+## iApp Generator: Your Development Tool
+
+Bootstrap TEE-compatible applications in minutes without any hardcoding skills,
+iApp Generator handles all the low-level complexity for you.
+
+- **Access to TEEs easily** - No need to dive into low-level requirements, build
+  iApps that connect to TEEs in minutes.
+- **Check and deploy iApps quickly** - iApp Generator checks that your iApp
+  complies with the iExec Framework and streamlines its deployment.
+- **Select your project mode & language** - Get started with either a basic or
+  advanced setup, depending on your experience with the iExec framework. You can
+  use Python or JavaScript—whichever you prefer!
+
+```bash
+# Create your iApp (Python or Node.js supported)
+iapp init my-privacy-app
+cd my-privacy-app
+
+# Develop and test locally (simulates TEE environment)
+iapp test
+# Deploy to the network
+iapp deploy
+```
+
+<div class="bg-gradient-to-r from-blue-400/10 to-blue-400/5 rounded-[6px] p-4 border-l-4 border-blue-600 mb-6">
+  <p class="m-0! text-sm"><strong>Note:</strong> iApp Generator currently supports Python and Node.js, but iApps can be built in any language that runs in Docker.</p>
+</div>
+
+## Real Examples
+
+Here are some real-world examples of iApps to help you understand how they work
+in practice.
+
+**Email Notification iApp**
+
+This iApp lets you send updates to your contacts without ever seeing their email
+addresses, privacy is preserved by design.
+
+::: code-group
+
+```python [Python]
+# User runs: "Send updates to my contacts about my project"
+contacts = load_protecteddata()  # User's protected contact list
+for contact in contacts:
+   send_email(contact, project_update_message)
+# → Emails sent directly, you never see the addresses
+```
+
+```js [Node.js]
+/* User runs: "Send updates to my contacts about my project" */
+const contacts = loadProtectedData(); // User's protected contact list
+contacts.forEach((contact) => {
+  sendEmail(contact, projectUpdateMessage);
+});
+// → Emails sent directly, you never see the addresses
+```
+
+:::
+
+**Oracle Update iApp**
+
+This iApp securely updates a price oracle using private trading data, ensuring
+sensitive information stays confidential.
+
+::: code-group
+
+```python [Python]
+# User runs: "Update price oracle with my private trading data"
+trading_data = load_protecteddata()  # User's protected trading history
+average_price = calculate_weighted_average(trading_data)
+update_oracle_contract(average_price)
+# → Oracle updated with real data, trading history stays private
+```
+
+```js [Node.js]
+/* User runs: "Update price oracle with my private trading data" */
+const tradingData = loadProtectedData(); // User's protected trading history
+const averagePrice = calculateWeightedAverage(tradingData);
+updateOracleContract(averagePrice);
+// → Oracle updated with real data, trading history stays private
+```
+
+:::
+
+**Automated Transactions iApp**
+
+This iApp automates monthly payments using protected payment details, so
+financial information remains private.
+
+::: code-group
+
+```python [Python]
+# User runs: "Automate payments every month"
+payment_info = load_protecteddata()  # User's payment details
+for month in range(12):
+   process_payment(payment_info)
+# → Payments processed, payment details stay private
+```
+
+```js [Node.js]
+/* User runs: "Automate payments every month" */
+const paymentInfo = loadProtectedData(); // User's payment details
+for (let month = 0; month < 12; month++) {
+  processPayment(paymentInfo);
+}
+// → Payments processed, payment details stay private
+```
+
+:::

src/build-iapp/guides/build-&-deploy-iapp.md

@@ -1,10 +1,175 @@
 ---
 title: Debugging Your iApp
-description: Debugging Your iApp
+description:
+  Troubleshoot and optimize your iApp execution in the TEE environment
 ---
 
-# Debugging Your iApp
+# 🐛 Debugging Your iApp
 
-This page is under development.
+**When your iApp doesn't work as expected, debugging in the TEE environment
+requires specific techniques.** This guide helps you identify issues and
+optimize your iApp's performance.
 
-<!-- TODO: Add the debugging guide -->
+## Task Execution Lifecycle
+
+Understanding how your task progresses through the iExec network:
+
+### Key Stages
+
+1. **Deal Creation** - Orders matched, funds locked
+2. **Task Initialization** - Workers selected for execution
+3. **iApp Execution** - Your code runs inside TEE
+4. **Result Processing** - Results encrypted and uploaded
+5. **Task Completion** - Results available for download
+
+**Most failures happen during stages 2-4**
+
+## Monitoring Your Tasks
+
+### iExec Explorer
+
+Track your tasks at [explorer.iex.ec](https://explorer.iex.ec):
+
+- Search by `taskId` or deal ID
+- Check status: `PENDING` → `ACTIVE` → `COMPLETED/FAILED`
+- View error messages if execution fails
+
+### Status in Code
+
+```ts twoslash
+import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector';
+
+const web3Provider = getWeb3Provider('PRIVATE_KEY');
+const dataProtectorCore = new IExecDataProtectorCore(web3Provider);
+// ---cut---
+const response = await dataProtectorCore.processProtectedData({
+  protectedData: '0x123abc...',
+  app: '0x456def...',
+  onStatusUpdate: ({ title, isDone }) => {
+    console.log(`Status: ${title} - Done: ${isDone}`);
+  },
+});
+```
+
+## Debug Commands
+
+### Local Testing
+
+```bash
+# Test your iApp locally
+iapp test --args "model=bert threshold=0.8"
+iapp test --secrets "key1=value1,key2=value2"
+
+# Mock protected data for testing
+iapp mock protectedData
+iapp test --protectedData "mock_name"
+```
+
+### Remote Debugging
+
+```bash
+# Deploy and run
+iapp deploy
+iapp run <iapp-address>
+
+# Debug failed executions
+iapp debug <taskId>
+```
+
+### Task Information
+
+```bash
+# View task details
+iexec task show <taskId>
+
+# Download results (if completed)
+iexec task show <taskId> --download
+```
+
+## Common Issues
+
+### ⏱️ **Task Timeout**
+
+- **Cause**: Code takes too long to execute
+- **Solution**: Optimize algorithms, reduce input sizes, use appropriate task
+  category
+
+### 💾 **Memory Issues**
+
+- **Cause**: Loading large files, memory leaks, TEE constraints
+- **Solution**: Process data in chunks, use streaming, optimize memory usage
+
+### 📁 **Input/Output Problems**
+
+- **Cause**: Wrong file paths, missing `computed.json`
+- **Solution**: Always create `computed.json`, verify environment variables
+
+```python
+# Always create computed.json
+import json, os
+computed = {"deterministic-output-path": f"{os.environ['IEXEC_OUT']}/result.json"}
+with open(f"{os.environ['IEXEC_OUT']}/computed.json", 'w') as f:
+    json.dump(computed, f)
+```
+
+### ⚠️ **Dataset type unmatching**
+
+- **Cause**: The dataset type specified in the frontend (protectData) does not
+  match with the dataset type specified in the iApp
+- **Solution**: Check both dataset types
+
+## Best Practices
+
+### 🔍 **Input Validation**
+
+```python
+import os, sys
+
+# Check required environment variables
+if not os.environ.get('IEXEC_IN') or not os.environ.get('IEXEC_OUT'):
+    print("ERROR: Missing IEXEC_IN or IEXEC_OUT")
+    sys.exit(1)
+
+# Validate arguments
+if len(sys.argv) < 2:
+    print("ERROR: Missing required arguments")
+    sys.exit(1)
+```
+
+### 📝 **Clear Error Messages**
+
+```python
+try:
+    # Your processing logic
+    result = process_data(data)
+except Exception as e:
+    print(f"ERROR: Processing failed: {str(e)}")
+    sys.exit(1)
+```
+
+### 🔒 **Safe File Operations**
+
+```python
+import os, json
+
+# Always ensure output directory exists
+iexec_out = os.environ['IEXEC_OUT']
+os.makedirs(iexec_out, exist_ok=True)
+
+# Write results safely
+try:
+    with open(f"{iexec_out}/result.json", 'w') as f:
+        json.dump(result_data, f)
+except Exception as e:
+    print(f"ERROR: Failed to write results: {e}")
+    sys.exit(1)
+```
+
+## What's Next?
+
+Continue improving your iApps:
+
+- **[Inputs and Outputs](/build_iapp/guides/inputs-and-outputs)** - Handle data
+  in TEE
+- **[How to Get and Decrypt Results](/build_iapp/guides/how-to-get-and-decrypt-results)** -
+  Retrieve results