Prerequisites

Capacitor Overview

AppForge uses Capacitor 8 to bridge web code with native device APIs. Features toggled in the builder are included in the generated native project.

AdMob Advertising

Monetize apps with Google AdMob. Configured via Admin → System Settings.

Database Schema

Complete list of database tables with RLS enabled on all:

Environment Variables Reference

Edge Function Secrets (database admin)

Build Architecture

AppForge converts websites into native apps by wrapping the target URL in a Capacitor WebView shell. The build pipeline works as follows:

Prerequisites

API Token Permissions

Codemagic API tokens require specific permission scopes. Restricted scopes return 403 Forbidden errors.

codemagic.yaml Configuration

The codemagic.yaml file in the project root defines build pipelines. Runs on Mac Mini M2 instances.

Key Properties

Pipeline Structure

# codemagic.yaml — simplified structure
workflows:
  android-build:
    name: Android Build
    instance_type: mac_mini_m2
    scripts:
      - npm install
      - npx cap add android
      - npx cap sync android
      - cd android && ./gradlew assembleDebug
    artifacts:
      - android/app/build/outputs/**/*.apk

  ios-build:
    name: iOS Build
    scripts:
      - npm install
      - npx cap add ios --packagemanager Cocoapods
      - npx cap sync ios
      - xcodebuild build ...
    artifacts:
      - build/ios/ipa/*.ipa

Android Build Pipeline

Generates APK files for direct installation or AAB bundles for Google Play Store.

Build Steps

1. Install dependencies — npm install
2. Generate config — Dynamically creates capacitor.config.ts with target URL, app name, package ID
3. Validate appId — Ensures Java-style package name (e.g., com.example.myapp)
4. Add Android — npx cap add android
5. Sync assets — npx cap sync android
6. Gradle build — cd android && ./gradlew assembleDebug
7. Collect artifacts — APK from android/app/build/outputs/

Output Formats

iOS Build Pipeline

Generates unsigned IPA files for testing. Code signing handled separately for App Store distribution.

Build Steps

1. Install dependencies — npm install
2. Add iOS with CocoaPods — npx cap add ios --packagemanager Cocoapods
3. Install pods — cd ios/App && pod install
4. Sync assets — npx cap sync ios
5. Xcode build — xcodebuild with archive → export
6. Collect artifacts — Unsigned IPA from build output

The default pipeline generates unsigned IPAs. To distribute via App Store or TestFlight, add your provisioning profile and signing certificate to the Codemagic workflow.

Build Troubleshooting

End-to-End Setup Guide

Complete walkthrough from zero to your first successful cloud build.

Phase 1: Codemagic Account & Token

1. Create a Codemagic account at codemagic.io/signup. GitHub OAuth is the fastest method.
2. Generate an API token: Navigate to Teams → Settings → API tokens (or your personal settings). Create a new token with Owner or Builds permission scope. Copy the token — it's only shown once.
3. Connect your GitHub repo: In Codemagic, click "Add application" → select the GitHub repository containing your AppForge project → choose codemagic.yaml as the configuration type.
4. Note your App ID: After the app is added, the App ID is visible in the URL or app settings (a 24-character hex string like 67abc1234def5678ghij9012).

Phase 2: Configure Secrets

You have two ways to provide credentials. Environment secrets take priority over database values:

CODEMAGIC_API_TOKEN=your-token-here
CODEMAGIC_APP_ID=your-app-id-here

Phase 3: Push Code to GitHub

1. Ensure codemagic.yaml is committed and pushed to the main branch.
2. The build pipeline always triggers from main — make sure your latest app configuration is merged there.
3. The cloud-build edge function polls GitHub to verify the main branch HEAD is recent (within 5 minutes) before triggering the Codemagic build, ensuring sync.

Phase 4: Trigger Your First Build

1. Go to /builder → enter a website URL → configure → preview.
2. On Step 4 (Build), select Android or iOS platform.
3. Click Build. The edge function:
   • Resolves and validates Codemagic credentials
   • Checks GitHub sync status (waits up to 60s for a fresh commit)
   • Sanitizes the package name to valid Java/iOS format
   • Triggers the Codemagic workflow with environment variables (WEBSITE_URL, APP_NAME, PACKAGE_NAME, etc.)
   • Registers a webhook callback URL for real-time status updates
4. Progress is tracked via the codemagic-webhook endpoint and cloud-build-status polling.
5. On completion, the artifact (APK/IPA) URL is stored in app_builds.download_url.

Build Environment Variables

The cloud-build function passes these variables to the Codemagic workflow:

Webhook Status Flow

The codemagic-webhook edge function provides real-time build updates, eliminating the need for aggressive polling.

Status Mapping

Failure Diagnostics

The webhook extracts step-level failure details and provides actionable hints:

• CocoaPods errors → Suggests checking --packagemanager Cocoapods flag
• Xcode build failures → Points to signing and provisioning issues
• SPM conflicts → Recommends using CocoaPods for Capacitor projects
• Missing Podfile → Indicates npx cap add ios wasn't run before pod install

Failed step name, message, and last 2000 chars of the log are stored in app_builds.config for the Build Details drawer.

Bucket Management

Managed via Admin → Settings → Storage. Local file storage provides file hosting with per-bucket access controls.

Default Buckets

RLS Policies

• Users — Upload/read/delete in own folder (user_id/)
• Admins — Full access to all buckets and folders
• Public buckets — Unauthenticated read access

Image Optimization

Configure via Admin → Settings → Storage → Optimization.

Settings Reference

Access Control & Security

const { data } = await backend.storage
  .from('project-assets')
  .createSignedUrl(path, 3600);

Storage Provider Configuration

Multiple backends supported. Configure via Admin → Settings → Storage → Provider.

Use the Test Connection button to validate credentials via test-storage-connection edge function.

Tiered Storage Quotas

Configure via Admin → Settings → Storage → Quotas.

Enforced at upload. Users warned at 80% capacity.

Storage API — Code Examples

The useStorage hook and storageApi wrapper provide full file management with validation and access control.

useStorage Hook

import { useStorage } from '@/hooks/useStorage';

const { upload, remove, getPublicUrl, getSignedUrl, listFiles, isUploading, uploadProgress } = useStorage();

// Upload a file (auto-validates type and size)
const result = await upload(file, {
  bucket: 'app-icons',     // 'avatars' | 'app-icons' | 'splash-screens' | 'apk-builds' | 'project-assets'
  path: 'icons',             // Optional subfolder within user's directory
  maxSizeMB: 10,              // Override default max size
  allowedTypes: ['image/png'] // Override default mime types
});
// result: { url: 'https://...', path: 'user-id/icons/123-abc.png', error: null }

// Get public URL (public buckets only)
const url = getPublicUrl('avatars', 'user-id/avatar.jpg');

// Get signed URL (private buckets, time-limited access)
const signedUrl = await getSignedUrl('project-assets', 'path/file.pdf', 3600); // 1 hour

// List files in a bucket folder
const files = await listFiles('app-icons', 'icons');
// [{ name: 'icon.png', url: 'https://...' }]

// Delete a file
await remove('avatars', 'user-id/old-avatar.jpg');

Default File Limits

Low-Level storageApi

Direct backend client calls without validation or toast notifications:

import { storageApi } from '@/lib/api/rest-client';

// Upload with upsert
const { data, error } = await storageApi.upload('avatars', 'user-id/avatar.jpg', file);

// Delete
await storageApi.delete('avatars', 'user-id/avatar.jpg');

// List files in folder
const files = await storageApi.list('app-icons', 'user-id');

// Get public URL
const url = storageApi.getPublicUrl('avatars', 'user-id/avatar.jpg');

Admin Storage Management

Admin operations use the storage-admin edge function:

import { backend } from '@/lib/backend-client';

// List all buckets with stats
const { data } = await backend.functions.invoke('storage-admin', {
  method: 'GET',
  headers: { 'action': 'list' }
});
// [{ name: "avatars", public: true, fileCount: 12, totalSize: 4567890 }]

// Test connection to external provider
const { data: result } = await backend.functions.invoke('test-storage-connection', {
  body: { provider: 's3', config: { s3_bucket: '...', s3_region: '...', ... } }
});

Resend (Transactional Email)

Powers all transactional emails: welcome, password reset, build completion, subscription confirmations.

Setup

1. Create an account at resend.com
2. Generate an API key (starts with re_)
3. Add RESEND_API_KEY to the server .env file
4. Verify sending domain in Resend dashboard
5. Configure sender address in Admin → Integrations → Email

Test Connection

Validates API key format (re_ prefix) rather than making an API call, because browser requests to Resend are blocked by CORS. Edge functions handle sending server-side.

Email Templates

Customize at Admin → Email Templates. Templates support HTML with {{variable}} syntax. Available: {{app_name}}, {{user_name}}, {{user_email}}, {{action_url}}, {{support_email}}.

Appetize.io (Device Preview)

Interactive device previews in the browser — test apps on virtual iOS/Android devices before downloading.

Setup

1. Create an account at appetize.io
2. Get your API token from the Appetize dashboard
3. Enter the token in Admin → Integrations → Appetize.io
4. Builds automatically upload artifacts for live preview

When a build completes, the APK/IPA is uploaded to Appetize.io via the appetize-upload edge function. The embed URL appears in the Builder's Preview step.

AI Providers

Powers website analysis (metadata, colors, branding extraction) and the AI assistant (config guidance chat).

Supported Providers

Enter keys in Admin → Integrations → AI Providers. Gemini validation uses the v1beta/models endpoint.

Codemagic Setup Wizard

Guided 6-step wizard in Admin → Integrations → Codemagic.

Stripe

Primary gateway for card payments, subscriptions, and customer portal.

Edge Functions

Required Secrets

Sandbox ↔ Live

Toggle in Admin → Payments → Stripe. Key format auto-validated (sk_test_ vs sk_live_).

Webhook Setup

# Webhook URL
https://YOUR_DOMAIN/api/functions/v1/stripe-webhook

# Required events
checkout.session.completed
customer.subscription.updated
customer.subscription.deleted
invoice.payment_succeeded
invoice.payment_failed

PayPal

One-time payments (orders) and recurring subscriptions (billing plans).

Edge Functions

Configuration

• Client ID — PayPal REST API Client ID
• Client Secret — PayPal REST API Secret
• Mode — Sandbox or Live

Dynamic Branding

Brand name in PayPal checkout is pulled dynamically from system_settings.app_name. No hardcoded brand names.

Billing Plans

Managed at Admin → Payments → PayPal → Billing Plans. Stored in subscription_plans: paypal_product_id, paypal_plan_id, paypal_yearly_plan_id.

Coinbase Commerce

Cryptocurrency payments (Bitcoin, Ethereum, USDC, etc.).

Setup

1. Create account at commerce.coinbase.com
2. Generate API key (Settings → Security)
3. Get webhook shared secret (Settings → Webhooks)
4. Configure in Admin → Payments → Coinbase
5. Add COINBASE_API_KEY and COINBASE_WEBHOOK_SECRET to the server .env file

Edge Functions

• coinbase-checkout — Creates charges for credit packs
• coinbase-webhook — Processes charge:completed, charge:failed events

Bank Transfer

Manual wire transfer with admin verification workflow.

Workflow

1. User selects Bank Transfer → receives bank details
2. User makes transfer and uploads proof of payment
3. Request enters bank_transfer_requests with pending status
4. Admin reviews at Admin → Payments → Bank Transfers
5. Approve → credits/subscription activated; Reject → user notified

Configure bank details (account name, IBAN, SWIFT, bank name) in Admin → Payments → Bank Transfer.

Step 1: Build for Production

npm run build

Creates an optimized dist/ folder with code-split chunks, minified CSS/JS, and hashed filenames.

Step 2: Upload to Hosting

Upload the contents of dist/ (not the folder itself) to your web root:

• cPanel: File Manager → public_html/ → Upload all files from dist/
• VPS: scp -r dist/* user@server:/var/www/html/
• Netlify/Vercel: Connect your Git repo; set build command to npm run build and publish directory to dist

Step 3: Configure .htaccess (Apache/cPanel)

Required for SPA routing. The repo includes a pre-configured .htaccess file:

# SPA Routing — redirect all requests to index.html
<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule ^ index.html [L]
</IfModule>

# Force HTTPS
<IfModule mod_rewrite.c>
  RewriteCond %{HTTPS} off
  RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
</IfModule>

# Gzip Compression
<IfModule mod_deflate.c>
  AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css application/javascript application/json
</IfModule>

# Security Headers
<IfModule mod_headers.c>
  Header set X-Content-Type-Options "nosniff"
  Header set X-Frame-Options "SAMEORIGIN"
  Header set X-XSS-Protection "1; mode=block"
  Header set Referrer-Policy "strict-origin-when-cross-origin"
</IfModule>

Step 4: Enable SSL

HTTPS is required for service workers, push notifications, camera, and biometrics.

• AutoSSL: cPanel → SSL/TLS Status → "Run AutoSSL"
• Let's Encrypt: cPanel → Let's Encrypt → Issue for your domain

Step 5: Configure the Database for Production

• Add your production domain to database admin → Authentication → URL Configuration → Site URL
• Add the domain to Redirect URLs as well
• Verify edge function secrets are set (Dashboard → Settings → Secrets)
• Set PUBLIC_SITE_URL secret to your production domain (used in webhook emails)

Step 6: Verify Deployment

Troubleshooting

Step 1: Pull Latest Code

# Navigate to your project directory
cd appforge

# Pull the latest changes
git pull origin main

# Install any new/updated dependencies
npm install

Step 2: Apply New Database Migrations

New versions may include database schema changes (new tables, columns, functions, or RLS policies).

# Ensure you're linked to the correct project
(set DATABASE_URL in your .env)

# Push any new migrations
npm run db:push

Step 3: Deploy Updated Edge Functions

npm run dev   (backend functions run in the Express server)

This redeploys all edge functions with the latest code. Existing secrets are preserved.

Step 4: Rebuild & Upload Frontend

# Build production bundle
npm run build

# Upload dist/ contents to your hosting
# cPanel: File Manager → public_html/ → Upload
# VPS: scp -r dist/* user@server:/var/www/html/

Step 5: Verify the Update

• Hard-refresh your browser (Ctrl+Shift+R) to clear cached assets
• Check that the app loads without console errors
• Verify login/signup still works
• Check Admin Panel → System Settings for any new options
• Test a sample build to verify edge functions are working

Quick Reference: Update Commands

# Complete update sequence (run from project root)
git pull origin main
npm install
npm run db:push
npm run dev   (backend functions run in the Express server)
npm run build
# Then upload dist/ to your hosting

Updating Edge Function Secrets

If the changelog mentions new required secrets:

# Set a new secret via CLI
(set secrets in the server .env file)

# Or via database admin → Settings → Secrets

Production Readiness Checklist

Security Best Practices

Row Level Security (RLS)

All tables use RLS. Admin access is verified via has_role(auth.uid(), 'admin') — a SECURITY DEFINER function that cannot be bypassed client-side.

-- Users access own data only
CREATE POLICY "Users access own data"
ON public.app_builds FOR SELECT
USING (auth.uid() = user_id);

-- Admin-only tables use SECURITY DEFINER functions
CREATE POLICY "Admins only"
ON public.system_settings FOR ALL
USING (has_role(auth.uid(), 'admin'));

Payment Gateway Production Setup

• Stripe: Switch sk_test_ → sk_live_ keys in the server .env file. Configure live webhook endpoint.
• PayPal: Switch from sandbox to live credentials in Admin → Payments. Configure webhook URL in PayPal Dashboard.
• Coinbase: Set live API key and webhook secret.
• Bank Transfer: Update bank details in Admin → Payments → Bank Transfer.

Backup Strategy

• Database: Schedule regular pg_dump backups (e.g. via cron) for your Postgres instance.
• Storage: Download critical files periodically. Build artifacts can be regenerated.
• Settings: settings_audit_log tracks all changes for recovery.
• Code: Keep in Git. Tag releases before deploying.

Scaling

• Edge Functions: Run inside the Express backend; scale by running more backend instances behind a load balancer.
• Database: Monitor connections and query performance. Add indexes as needed.
• Storage: Use CDN (Cloudflare) in front of your hosting for static assets.
• Builds: max_builds_per_day setting prevents abuse.
• Credits: Natural throttle. Adjust credits_per_build as needed.

Directory Layout

appforge/
├── docs/                    # Documentation (this site)
├── public/                  # Static assets (robots.txt, favicon)
├── src/
│   ├── components/
│   │   ├── admin/           # Admin panel components (20+)
│   │   ├── builder/         # App builder wizard steps
│   │   │   └── configure/   # Builder configuration sub-components
│   │   ├── subscription/    # Billing & credit pack UI
│   │   └── ui/              # Shadcn/Radix design system components
│   ├── contexts/            # React context providers (AuthContext)
│   ├── hooks/               # Custom hooks (30+)
│   ├── lib/
│   │   ├── backend-client.ts # Backend client (auth/db/storage/functions)
│   │   ├── auth-client.ts   # Better Auth browser client
│   │   └── api/             # REST API client wrappers
│   ├── pages/               # Route page components (15+)
│   ├── stores/              # Zustand state stores
│   ├── types/               # TypeScript type definitions
│   └── utils/               # Utility functions
├── server/
│   ├── src/                 # Express backend (routes, auth, functions)
│   └── db/                  # schema.sql & auth-schema.sql
├── .htaccess                # Apache SPA routing & security
├── capacitor.config.ts      # Capacitor native app config
├── codemagic.yaml           # CI/CD build pipeline
└── vite.config.ts           # Vite bundler configuration

Key Architecture Patterns

Application Routes

All routes use the ProtectedRoute, PublicRoute, or SetupRoute guard components.

Keyboard Shortcuts

Available in the App Builder. Press ? to show the shortcuts overlay.

Shortcuts are disabled when typing in input fields or textareas. ⌘ = Ctrl on Windows/Linux.

Cookie Consent Banner

Displayed on first visit via CookieConsent component. Users can accept all, reject all, or customize preferences.

Cookie Categories

Implementation

• Preferences stored in localStorage under cookie-consent key
• Custom event cookieConsentChanged dispatched on preference update
• Users can re-open settings dialog anytime from the footer

Consent Records Table

Server-side audit trail stored in consent_records table with RLS.

RLS Policies

• Users can insert records for themselves or anonymously (user_id IS NULL)
• Users can read/update only their own records
• No delete access (audit compliance)

Invoice Table Schema

Admin Workflow

1. Create invoice at Admin → Payments → Invoices
2. Select user, add line items, set due date
3. Invoice auto-calculates total from items
4. Users see invoices at /payment-history
5. Payment via any configured gateway (Stripe, PayPal, Coinbase)
6. Status transitions: draft → pending → paid (or overdue/cancelled)

Webhook Event Logs

All incoming payment webhooks are logged to webhook_event_logs for debugging and auditing.

Retry Mechanism

Failed webhooks can be retried from Admin → Payments → Webhooks. The retry-webhook edge function resends the original payload to the gateway handler with an X-Webhook-Retry: true header.

System Overview

The automation system enables per-project workflows that execute on schedules or events. Automations are stored in automation_configs with execution history in automation_logs.

Workflow Types

Automation API

Client-side API via automationApi from @/lib/api/rest-client.

import { automationApi } from '@/lib/api/rest-client';

// List automations (for current user, optionally filtered by project)
const { data } = await automationApi.list(projectId);
// data.automations: Array of automation configs

// Create a new automation
await automationApi.create(projectId, 'auto_build', {
  trigger: 'push',
  branch: 'main',
  platform: 'android'
});

// Toggle enabled/disabled
await automationApi.toggle(automationId, false);

// Update config
await automationApi.updateConfig(automationId, { cron: '0 3 * * *' });

// Get execution logs
const { data: logs } = await automationApi.getLogs(automationId);
// logs.logs: [{ status, started_at, completed_at, message, metadata }]

// Trigger manual execution
await automationApi.execute(automationId);

// Delete an automation
await automationApi.delete(automationId);

Database Schema

automation_configs

automation_logs

RLS Policies

• automation_configs — Users can CRUD their own configs. Admins can view all.
• automation_logs — Users can read their own logs. Admins can read all. Insert/update is server-side only.

Complete Nginx Server Block

server {
    listen 443 ssl http2;
    server_name yourdomain.com www.yourdomain.com;

    root /var/www/html;
    index index.html;

    # SSL (Let's Encrypt / Certbot)
    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;

    # SPA Routing — send all requests to index.html
    location / {
        try_files $uri $uri/ /index.html;
    }

    # Cache static assets (JS, CSS, images)
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2?)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
        access_log off;
    }

    # Security headers
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    # Gzip compression
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml;
    gzip_min_length 1000;
}

# HTTP → HTTPS redirect
server {
    listen 80;
    server_name yourdomain.com www.yourdomain.com;
    return 301 https://$host$request_uri;
}

Key Differences from Apache

Setup & Configuration

Building Apps

Billing & Credits

Admin & Security