Skip to main content

​
Overview

The Convex Backend provides the data layer and real-time capabilities for GeoFlow. As a self-hosted instance of Convex, it handles authentication, data persistence, real-time subscriptions, and API endpoints.

​
Technology Stack

  • Framework: Convex (self-hosted Rust backend)
  • Database: Custom storage engine with PostgreSQL integration
  • Authentication: Better Auth integration
  • Real-time: WebSocket connections for live updates
  • API: GraphQL and REST endpoints

​
Key Features

​
Data Management

  • Real-time Sync: Automatic UI updates when data changes
  • Type Safety: End-to-end TypeScript types generated from schema
  • Migrations: Schema versioning and migration system
  • Backup/Restore: Data export and import capabilities

​
Authentication & Authorization

  • Multi-provider Auth: Support for various OAuth providers
  • Role-based Access: User permissions and access control
  • Session Management: Secure token-based authentication
  • User Profiles: User data and preferences storage

​
API Endpoints

  • Query Functions: Data fetching with automatic caching
  • Mutation Functions: Data modification with optimistic updates
  • Action Functions: Complex server-side operations
  • HTTP Endpoints: REST API for external integrations

​
Architecture

​
Project Structure

apps/backend/convex/
├── auth.config.ts        # Authentication configuration
├── schema.ts            # Database schema definition
├── queries/             # Data fetching functions
├── mutations/          # Data modification functions
├── actions/            # Complex operations
├── http.ts             # HTTP endpoints
└── workflows.ts        # Workflow-specific functions

​
Schema Design

The database schema includes:
  • Users: User accounts and authentication data
  • Workflows: Workflow definitions and metadata
  • Executions: Workflow execution records and status
  • Files: File metadata and storage references
  • Credentials: API credentials and service integrations

​
Real-time Subscriptions

Convex provides real-time updates through subscriptions: 
// Subscribe to workflow executions
const executions = useQuery(api.executions.listByWorkflow, { workflowId });

// Subscribe to user data changes
const user = useQuery(api.users.getCurrent);

​
Configuration

​
Environment Variables

# Instance configuration
INSTANCE_NAME=geoflow-dev
INSTANCE_SECRET=your-secret-key

# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/geoflow

# External services
WORKER_URL=http://geoflow-worker:3002
MCP_SERVER_URL=http://geoflow-mcp:8000
MOTIA_SERVER_URL=http://motia:4010

# Security
CONVEX_CLOUD_ORIGIN=http://localhost:3210

​
Docker Configuration

The backend runs in a Docker container with:
  • Base Image: ghcr.io/get-convex/convex-backend:latest
  • Ports: 3210 (backend), 3211 (site proxy)
  • Volumes: Persistent data storage
  • Health Checks: Automatic service monitoring

​
Development

​
Local Development


# Start development server
bun run dev

​
Database Operations

# Create migration
convex deploy --configure

# Run migrations
convex deploy

# View dashboard
convex dashboard

​
API Reference

​
Query Functions

  • workflows.list() - Get all workflows
  • executions.listByWorkflow(workflowId) - Get executions for a workflow
  • files.listByUser(userId) - Get user’s files

​
Mutation Functions

  • workflows.create(data) - Create new workflow
  • executions.start(workflowId) - Start workflow execution
  • files.upload(metadata) - Record file upload

​
HTTP Endpoints

  • POST /api/files/upload - File upload endpoint
  • GET /api/workflows/:id/export - Export workflow
  • POST /api/executions/:id/cancel - Cancel execution

​
Monitoring & Debugging

​
Dashboard

Access the Convex dashboard at http://localhost:6791 for:
  • Query Inspector: View and debug queries
  • Data Browser: Browse database contents
  • Metrics: Performance and usage statistics
  • Logs: Server logs and error tracking

​
Logging

Logs are configured with different levels:
  • Development: Debug level with detailed information
  • Production: Info level with essential information
  • Error Tracking: Automatic error reporting and alerts

​
Performance

​
Optimization Strategies

  • Query Batching: Multiple queries combined into single requests
  • Pagination: Large datasets loaded in chunks
  • Caching: Automatic query result caching
  • Indexing: Database indexes for common query patterns

​
Scaling Considerations

  • Horizontal Scaling: Multiple backend instances behind load balancer
  • Database Sharding: Data partitioning for large deployments
  • CDN Integration: Static asset delivery optimization
  • Connection Pooling: Efficient database connection management

​
Security

​
Authentication Flow

  1. Client Request: User initiates login
  2. OAuth Redirect: Redirect to identity provider
  3. Token Exchange: Receive and validate tokens
  4. Session Creation: Create authenticated session
  5. Authorization: Check permissions for operations

​
Data Protection

  • Encryption: Data encrypted at rest and in transit
  • Access Control: Row-level security policies
  • Audit Logging: All data access logged for compliance
  • Rate Limiting: API rate limiting to prevent abuse

​
Troubleshooting

​
Common Issues

Connection Refused: Check if backend service is running and ports are accessible Schema Mismatches: Run convex deploy to sync schema changes Authentication Errors: Verify OAuth provider configuration Performance Issues: Check query patterns and add appropriate indexes

​
Debug Commands

# View service logs
docker compose logs geoflow-convex-backend

# Check service health
curl http://localhost:3210/version