insforge 1.3.0 → 1.4.8

package/docs/core-concepts/deployments/architecture.mdx

@@ -0,0 +1,152 @@
+---
+title: Deployment Architecture
+description: Zero-config web app deployments powered by Vercel
+---
+
+<Warning>
+  Deployments is an experimental feature. APIs and behavior may change.
+</Warning>
+
+## Overview
+
+InsForge Deployments enable developers to deploy web applications with a single prompt. By integrating with coding agents via InsForge MCP, developers can simply say "Deploy my app" and have their application live within a minute—no configuration required.
+
+## Technology Stack
+
+```mermaid
+graph TB
+    Agent[Coding Agent] --> MCP[InsForge MCP]
+    MCP --> API[InsForge Server]
+
+    API --> S3[AWS S3]
+    S3 --> Vercel[Vercel Edge Network]
+
+    API --> DB[(PostgreSQL)]
+    DB --> Metadata[Deployment Metadata]
+    DB --> Status[Status Tracking]
+
+    Vercel --> Live[Live Application]
+
+    style Agent fill:#1e293b,stroke:#475569,color:#e2e8f0
+    style MCP fill:#1e40af,stroke:#3b82f6,color:#dbeafe
+    style API fill:#166534,stroke:#22c55e,color:#dcfce7
+    style S3 fill:#ea580c,stroke:#f97316,color:#fed7aa
+    style Vercel fill:#000000,stroke:#ffffff,color:#ffffff
+    style DB fill:#0e7490,stroke:#06b6d4,color:#cffafe
+    style Metadata fill:#0e7490,stroke:#22d3ee,color:#cffafe
+    style Status fill:#0e7490,stroke:#22d3ee,color:#cffafe
+    style Live fill:#166534,stroke:#22c55e,color:#dcfce7
+```
+
+## Core Components
+
+| Component | Technology | Purpose |
+|-----------|------------|---------|
+| **Edge Storage** | AWS S3 | Temporary source file staging |
+| **Build Platform** | Vercel | Production builds and hosting |
+| **Status Tracking** | PostgreSQL | Deployment state and metadata |
+| **Webhook Handler** | HMAC-SHA1 | Real-time build status updates |
+
+## How It Works
+
+### Deployment Flow
+
+```mermaid
+sequenceDiagram
+    participant Agent as Coding Agent
+    participant API as InsForge Server
+    participant S3 as AWS S3
+    participant Vercel as Vercel
+
+    Agent->>API: Create deployment
+    API-->>Agent: Upload URL + deployment ID
+
+    Agent->>S3: Upload source.zip
+    S3-->>Agent: Upload complete
+
+    Agent->>API: Start deployment
+    API->>S3: Download source
+    API->>Vercel: Upload files
+    API->>Vercel: Create deployment
+    API-->>Agent: Deployment started
+
+    Vercel->>Vercel: Build application
+    Vercel->>API: Webhook: Build complete
+
+    Agent->>API: Check status
+    API-->>Agent: READY + live URL
+```
+
+### Step-by-Step Process
+
+1. **Create Deployment**: Agent requests a new deployment, receiving a presigned S3 upload URL
+2. **Upload Source**: Source files are zipped and uploaded directly to S3 via edge network
+3. **Start Build**: InsForge downloads the source, extracts files, and uploads to Vercel
+4. **Build & Deploy**: Vercel builds the application and deploys to its edge network
+5. **Go Live**: Application becomes available at `https://{app-key}.insforge.site`
+
+The entire process typically completes in about one minute.
+
+## Deployment Status
+
+| Status | Description |
+|--------|-------------|
+| `WAITING` | Deployment created, awaiting source upload |
+| `UPLOADING` | Source files being processed |
+| `QUEUED` | Build queued on Vercel |
+| `BUILDING` | Application being built |
+| `READY` | Live and accessible |
+| `ERROR` | Build failed |
+| `CANCELED` | Deployment canceled |
+
+## Environment Variables
+
+Environment variables can be passed during deployment for build-time configuration. They are encrypted at rest and in transit, and are only accessible during the build process. For auditing purposes, only variable names are logged, never values.
+
+<Warning>
+  While environment variables are encrypted, avoid storing sensitive credentials in frontend applications. Variables prefixed with `NEXT_PUBLIC_` or similar are embedded in client bundles.
+</Warning>
+
+## Current Limitations
+
+<Note>
+  This is an experimental feature with the following constraints:
+</Note>
+
+| Limitation | Details |
+|------------|---------|
+| **Environment** | Production deployments only |
+| **Custom Domains** | Coming soon |
+| **Preview Deployments** | Coming soon |
+| **Build Logs** | Limited visibility |
+
+## Performance
+
+### Edge Network Optimization
+
+Both AWS S3 and Vercel utilize global edge networks, enabling:
+
+- **Fast Uploads**: Source files uploaded to nearest S3 edge location
+- **Rapid Builds**: Vercel's distributed build infrastructure
+- **Global Distribution**: Deployed applications served from edge locations worldwide
+- **Low Latency**: Sub-100ms response times for static assets
+
+## Best Practices
+
+<CardGroup cols={2}>
+  <Card title="Keep Builds Small" icon="minimize">
+    Avoid uploading large assets. Use InsForge Storage and access via URLs.
+  </Card>
+
+  <Card title="Use Environment Variables" icon="key">
+    Configure builds via env vars, not hardcoded values
+  </Card>
+
+  <Card title="Test Locally First" icon="flask">
+    Verify builds work locally before deploying
+  </Card>
+
+  <Card title="Monitor Status" icon="chart-line">
+    Check deployment status for build errors
+  </Card>
+</CardGroup>

package/docs/core-concepts/email/architecture.mdx

@@ -1,9 +1,11 @@
 ---
-title: Architecture
+title: Email Architecture
 description: Transactional email delivery powered by AWS SES
 ---
 
-<Note>**Private Preview** - This feature is currently in private preview.</Note>
+<Warning>
+  Email is an experimental feature. APIs and behavior may change.
+</Warning>
 
 ## Overview
 

package/docs/core-concepts/functions/architecture.mdx

@@ -1,5 +1,5 @@
 ---
-title: Architecture
+title: Functions Architecture
 description: Serverless JavaScript functions running in isolated Deno runtime
 ---
 

package/docs/core-concepts/functions/sdk.mdx

@@ -68,7 +68,6 @@ console.log(data)
 ```json
 {
   "data": {
-    "users": 100,
     "posts": 500,
     "comments": 1200
   },

package/docs/core-concepts/realtime/architecture.mdx

@@ -1,5 +1,5 @@
 ---
-title: Architecture
+title: Realtime Architecture
 description: Real-time messaging with PostgreSQL triggers, WebSockets, and webhooks
 ---
 

package/docs/core-concepts/storage/architecture.mdx

@@ -1,5 +1,5 @@
 ---
-title: Architecture  
+title: Storage Architecture
 description: Enterprise-grade storage system powered by AWS S3
 ---
 

package/docs/core-concepts/storage/sdk.mdx

@@ -24,7 +24,7 @@ StorageBucket // Instance with upload, uploadAuto, download, remove methods
 ### Example
 
 ```javascript
-const bucket = insforge.storage.from('avatars')
+const bucket = insforge.storage.from('images')
 ```
 
 ---
@@ -62,17 +62,17 @@ If a file with the same key exists, backend auto-renames it. Always use the retu
 
 ```javascript
 const { data, error } = await insforge.storage
-  .from('avatars')
-  .upload('user-123/avatar.jpg', fileObject)
+  .from('images')
+  .upload('posts/post-123/cover.jpg', fileObject)
 
 // Save BOTH url and key to database
 await insforge.database
-  .from('users')
+  .from('posts')
   .update({
-    avatar_url: data.url,
-    avatar_key: data.key  // Save key for download/delete operations
+    image_url: data.url,
+    image_key: data.key  // Save key for download/delete operations
   })
-  .eq('id', 'user-123')
+  .eq('id', 'post-123')
 ```
 
 ### Output
@@ -80,12 +80,12 @@ await insforge.database
 ```json
 {
   "data": {
-    "bucket": "avatars",
-    "key": "user-123/avatar.jpg",
+    "bucket": "images",
+    "key": "posts/post-123/cover.jpg",
     "size": 45678,
     "mimeType": "image/jpeg",
     "uploadedAt": "2024-01-15T10:30:00Z",
-    "url": "https://your-app.region.insforge.app/api/storage/buckets/avatars/objects/user-123%2Favatar.jpg"
+    "url": "https://your-app.region.insforge.app/api/storage/buckets/images/objects/posts%2Fpost-123%2Fcover.jpg"
   },
   "error": null
 }
@@ -173,16 +173,16 @@ Download a file as Blob.
 
 ```javascript
 // 1. Get the file key from your database
-const { data: user, error: dbError } = await insforge.database
-  .from('users')
-  .select('avatar_key')
-  .eq('id', 'user-123')
+const { data: post, error: dbError } = await insforge.database
+  .from('posts')
+  .select('image_key')
+  .eq('id', 'post-123')
   .single()
 
 // 2. Download the file using the key
 const { data: blob, error } = await insforge.storage
-  .from('avatars')
-  .download(user.avatar_key)
+  .from('images')
+  .download(post.image_key)
 
 // 3. Create download link or display image
 const url = URL.createObjectURL(blob)
@@ -222,22 +222,22 @@ Delete a file from storage.
 
 ```javascript
 // 1. Get the file key from your database
-const { data: user, error: dbError } = await insforge.database
-  .from('users')
-  .select('avatar_key')
-  .eq('id', 'user-123')
+const { data: post, error: dbError } = await insforge.database
+  .from('posts')
+  .select('image_key')
+  .eq('id', 'post-123')
   .single()
 
 // 2. Delete the file from storage
 const { data, error } = await insforge.storage
-  .from('avatars')
-  .remove(user.avatar_key)
+  .from('images')
+  .remove(post.image_key)
 
 // 3. Clear the database reference
 await insforge.database
-  .from('users')
-  .update({ avatar_url: null, avatar_key: null })
-  .eq('id', 'user-123')
+  .from('posts')
+  .update({ image_url: null, image_key: null })
+  .eq('id', 'post-123')
 ```
 
 ### Output

package/docs/docs.json

@@ -15,14 +15,15 @@
   },
   "seo": {
     "metatags": {
-      "og:site_name": "InsForge Docs"
+      "og:site_name": "InsForge Docs",
+      "google-site-verification": "2dSsr0kxw61j9-qSOR0a1dq1PT6U1-2o3kiZMdsIf9g"
     },
     "indexing": "navigable"
   },
   "search": {
     "prompt": "Search InsForge docs..."
   },
-  "favicon": "/favicon.svg",
+  "favicon": "/favicon.png",
   "navigation": {
     "tabs": [
       {
@@ -30,7 +31,7 @@
         "groups": [
           {
             "group": "Getting Started",
-            "pages": ["introduction", "quickstart", "partnership"]
+            "pages": ["introduction", "quickstart", "mcp-setup", "vscode-extension", "partnership", "oauth-server"]
           },
           {
             "group": "Core Concepts",
@@ -39,7 +40,8 @@
                 "group": "Database",
                 "pages": [
                   "core-concepts/database/architecture",
-                  "core-concepts/database/sdk"
+                  "core-concepts/database/sdk",
+                  "core-concepts/database/pgvector"
                 ]
               },
               {
@@ -50,8 +52,8 @@
                   {
                     "group": "UI Components",
                     "pages": [
-                      "core-concepts/authentication/ui-components/nextjs",
                       "core-concepts/authentication/ui-components/react",
+                      "core-concepts/authentication/ui-components/nextjs",
                       "core-concepts/authentication/ui-components/react-router",
                       "core-concepts/authentication/ui-components/customization"
                     ]
@@ -87,11 +89,17 @@
                 ]
               },
               {
-                "group": "Email (Private Preview)",
+                "group": "Email (Experimental)",
                 "pages": [
                   "core-concepts/email/architecture",
                   "core-concepts/email/sdk"
                 ]
+              },
+              {
+                "group": "Deployments (Experimental)",
+                "pages": [
+                  "core-concepts/deployments/architecture"
+                ]
               }
             ]
           },

package/docs/favicon.svg

@@ -1,19 +1,4 @@
-<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
-<path d="M9.06145 23.1079C5.26816 22.3769 -3.39077 20.6274 1.4173 5.06384C9.6344 6.09939 16.9728 14.0644 9.06145 23.1079Z" fill="url(#paint0_linear_17557_2021)"/>
-<path d="M8.91928 23.0939C5.27642 21.2223 0.78371 4.20891 17.0071 0C20.7569 7.19341 19.6212 16.5452 8.91928 23.0939Z" fill="url(#paint1_linear_17557_2021)"/>
-<path d="M8.91388 23.0788C8.73534 19.8817 10.1585 9.08525 23.5699 13.1107C23.1812 20.1229 18.984 26.4182 8.91388 23.0788Z" fill="url(#paint2_linear_17557_2021)"/>
-<defs>
-<linearGradient id="paint0_linear_17557_2021" x1="3.77557" y1="5.91571" x2="5.23185" y2="21.5589" gradientUnits="userSpaceOnUse">
-<stop stop-color="#18E299"/>
-<stop offset="1" stop-color="#15803D"/>
-</linearGradient>
-<linearGradient id="paint1_linear_17557_2021" x1="12.1711" y1="-0.718425" x2="10.1897" y2="22.9832" gradientUnits="userSpaceOnUse">
-<stop stop-color="#16A34A"/>
-<stop offset="1" stop-color="#4ADE80"/>
-</linearGradient>
-<linearGradient id="paint2_linear_17557_2021" x1="23.1327" y1="15.353" x2="9.33841" y2="18.5196" gradientUnits="userSpaceOnUse">
-<stop stop-color="#4ADE80"/>
-<stop offset="1" stop-color="#0D9373"/>
-</linearGradient>
-</defs>
+<svg width="32" height="32" viewBox="0 0 100 100" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M11.56 41.33C10.29 40.06 10.29 38.01 11.56 36.74L43.83 4.61H89.92L34.61 59.69C33.34 60.96 31.27 60.96 30 59.69L11.56 41.33Z" fill="#1a1a1a"/>
+<path d="M69.76 30.43L89.92 50.51V96.42L46.71 53.38L69.76 30.43Z" fill="#4a4a4a"/>
 </svg>

package/docs/insforge-instructions-sdk.md

@@ -53,12 +53,15 @@ Available documentation types:
 - `"instructions"` - Essential backend setup (START HERE)
 - `"db-sdk"` - Database operations with SDK
 - **Authentication** - Choose based on implementation:
-  - `"auth-components-react"` - Frontend auth for React+Vite (singlepage App)
-  - `"auth-components-react-router"` - Frontend auth for React(Vite+React Router) (Multipage App)
+  - `"auth-sdk"` - Direct SDK methods for custom auth flows
+  - `"auth-components-react"` - Pre-built auth UI for React+Vite (singlepage App)
+  - `"auth-components-react-router"` - Pre-built auth UI for React(Vite+React Router) (Multipage App)
+  - `"auth-components-nextjs"` - Pre-built auth UI for Nextjs (SSR App)
 - `"storage-sdk"` - File storage operations
 - `"functions-sdk"` - Serverless functions invocation
 - `"ai-integration-sdk"` - AI chat and image generation
 - `"real-time"` - Real-time pub/sub (database + client events) via WebSockets
+- `"deployment"` - Deploy frontend applications via MCP tool
 
 ## When to Use SDK vs MCP Tools
 
@@ -77,10 +80,11 @@ Available documentation types:
 - Database schema management (`run-raw-sql`, `get-table-schema`)
 - Storage bucket creation (`create-bucket`, `list-buckets`, `delete-bucket`)
 - Serverless function deployment (`create-function`, `update-function`, `delete-function`)
+- Frontend deployment (`create-deployment`) - Deploy frontend apps to InsForge hosting
 
 ## Important Notes
 
-- Use the right framework-specific component package for production-ready auth
+- For auth: use `auth-sdk` for custom UI, or framework-specific components for pre-built UI
 - SDK returns `{data, error}` structure for all operations
 - Database inserts require array format: `[{...}]`
 - Serverless functions have single endpoint (no subpaths)

package/docs/introduction.mdx

@@ -1,5 +1,6 @@
 ---
-title: Introduction
+title: "Introduction"
+description: "Backend built for AI-assisted development."
 ---
 
 InsForge is an AI-optimized Backend-as-a-Service platform for modern applications. It provides a comprehensive backend out of the box with PostgreSQL, JWT-based authentication, and S3-compatible storage. Every endpoint, from initial configuration to database operations to file uploads, is designed to be agent-friendly with consistent patterns and predictable responses.
@@ -19,27 +20,27 @@ Ready to start building? Check out our [framework examples](/examples/overview)
 Everything you need to build real applications, designed for AI agents:
 
 <CardGroup cols={2}>
-  <Card title="PostgreSQL Database" icon="database">
+  <Card title="PostgreSQL Database" icon="database" href="/core-concepts/database/architecture">
     Tables become APIs instantly. No code. Just schema.
   </Card>
 
-  <Card title="Authentication" icon="shield">
+  <Card title="Authentication" icon="shield" href="/core-concepts/authentication/architecture">
     User signup, login, sessions, OAuth. Zero configuration.
   </Card>
 
-  <Card title="File Storage" icon="folder">
+  <Card title="File Storage" icon="folder" href="/core-concepts/storage/architecture">
     Upload, download, serve files. Works like any other API.
   </Card>
 
-  <Card title="Edge Functions" icon="bolt">
+  <Card title="Edge Functions" icon="bolt" href="/core-concepts/functions/architecture">
     Deploy serverless functions that run on the edge. Zero infrastructure.
   </Card>
 
-  <Card title="AI Integration" icon="sparkles">
+  <Card title="AI Integration" icon="sparkles" href="/core-concepts/ai/architecture">
     Built-in AI capabilities with streaming support. Ready to use.
   </Card>
 
-  <Card title="No Backend Knowledge Needed" icon="brain">
-    AI agents handle the backend. You don't need to understand infrastructure.
+  <Card title="Realtime" icon="bolt" href="/core-concepts/realtime/architecture">
+    Pub/sub messaging with WebSockets. Build collaborative apps.
   </Card>
 </CardGroup>