/.archive/docs/deprecated/insforge-instructions.md

Insforge OSS Instructions

What Insforge OSS Does

Backend-as-a-service with database, authentication, and file storage.

Key Concept: InsForge replaces your traditional backend - implement business logic by calling database operations directly. Instead of building API endpoints, use our database API as your application's backend.

🚨 Project Setup

Create your app in a NEW directory, not inside insforge/

The insforge/ directory is the BaaS platform. Your app should live elsewhere:

~/projects/
├── insforge/      # ← BaaS platform (don't work here)
└── my-app/        # ← Your new app (work here)

When to Use Tools

MUST DO FIRST → Download project rules: download-project-rules Start here → get-backend-metadata (shows current database state) Need docs → get-db-api, get-auth-api, or get-storage-api Create table → create-table with explicit schema Work with data → Use database API endpoints directly

Critical Rule:

MUST DO FIRST → Calldownload-project-rules to download project rules

Critical Rule: Check Metadata First

Before ANY database operation, call get-backend-metadata to get the current database state.

Standard Workflow

1. Always call get-backend-metadata first
2. Check get-instructions if unfamiliar with the system
3. Create tables with create-table if needed
4. Use database API to insert/query/update/delete records
5. Call get-backend-metadata again to verify changes

Key Rules

• Frequently check get-instructions and get-backend-metadata
• Always define explicit table schemas (no assumptions)
• Every table gets auto ID, created_at, updated_at fields
• Database operations require: JWT token (Authorization: Bearer header)
• API keys are for MCP testing (use tokens for production)
• File uploads work automatically with multipart/form-data

Authentication Requirements

Database Operations Need Authentication Token:

1. JWT Token: Authorization: Bearer your-jwt-token - Authenticates the user

Important Note about API Keys:

• The x-api-key header is ONLY used for MCP (Model Context Protocol) testing
• Production applications should NEVER use API keys
• Always use JWT tokens from user/admin authentication for real applications

Without the Bearer token, you'll get "permission denied" errors when trying to insert, update, or delete records.

Getting Authentication:

# Works on both Windows and Unix (Windows PowerShell: use curl.exe)
# 1. First login to get JWT token
curl -X POST http://localhost:7130/api/auth/admin/sessions \
  -H "Content-Type: application/json" \
  -d "{\"username\":\"admin\",\"password\":\"your-password\"}"

# Response includes token: {"accessToken": "eyJ...", "projectAdmin": {...}}

# Works on both Windows and Unix (Windows PowerShell: use curl.exe)
# 2. Use the auth token for database operations
curl -X POST http://localhost:7130/api/database/records/products \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d "[{\"name\": \"Product\", \"price\": 99.99}]"

Example: Comment Upvoting Feature

• Check current tables: get-backend-metadata
• Create comment_votes table: create-table with user_id, comment_id, vote_type fields
• Frontend upvote action: POST /api/database/records/comment_votes with vote data
• Frontend display scores: GET /api/database/records/comment_votes?comment_id=eq.123 to count votes
• No separate backend needed - frontend calls InsForge database API directly

Critical Rule: Test API Endpoints with curl

After creating or modifying any API endpoint, always test it with curl to verify it works correctly.

Note: Avoid special characters (!,$,`,) in curl command data - they can cause bash interpretation issues. Use simple text for testing:

# Works on both Windows and Unix (Windows PowerShell: use curl.exe)
# Example: Test creating a record (requires JWT token)
curl -X POST http://localhost:7130/api/database/records/posts \
  -H "x-api-key: your-api-key" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '[{\"title\": \"Test Post\", \"content\": \"Test content\"}]'

# Works on both Windows and Unix (Windows PowerShell: use curl.exe)
# Example: Test querying records (requires both API key and JWT token)
curl http://localhost:7130/api/database/records/posts?id=eq.123 \
  -H "x-api-key: your-api-key" \
  -H "Authorization: Bearer your-jwt-token"

# Works on both Windows and Unix (Windows PowerShell: use curl.exe)
# Example: Test authentication
curl -X POST http://localhost:7130/api/auth/users \
  -H "Content-Type: application/json" \
  -d '{\"email\": \"test@example.com\", \"password\": \"testpass123\"}'

Always include:

• Both headers for database operations: x-api-key AND Authorization: Bearer token
• Correct HTTP method (GET, POST, PATCH, DELETE)
• Valid JSON payload for POST/PATCH requests (remember: POST requires array format [{...}])
• Query parameters for filtering GET requests
• Prefer: return=representation header if you want to see the created/updated records