insforge--insforge/.github/copilot-instructions.md

Project Overview

InsForge is an open-source Backend-as-a-Service (BaaS) platform designed specifically for AI agents. It provides a comprehensive solution for managing backend services including authentication, database operations, storage, and serverless functions, all accessible through REST APIs with PostgreSQL as the primary database.

Architecture

This is a monorepo containing:

• Backend: Node.js with Express.js, providing RESTful APIs
• Frontend: React with Vite, offering an admin dashboard
• Functions: Serverless function runtime using Deno
• Shared-schemas: Common TypeScript schemas shared across modules

Folder Structure

• /backend: Node.js backend server
  • /src/api: API routes and middleware
  • /src/controllers: Business logic controllers
  • /src/core: Core services (auth, database, storage, metadata)
  • /src/types: TypeScript type definitions
  • /src/utils: Utility functions and helpers
• /frontend: React dashboard application
  • /src/components: Reusable UI components
  • /src/features: Feature-specific modules (auth, database, storage, logs)
  • /src/lib: Shared libraries, hooks, and utilities
• /functions: Serverless function runtime
• /shared-schemas: Shared TypeScript schemas
• /docker-init: Docker initialization scripts
• /openapi: API documentation in OpenAPI format
• /tests: Comprehensive test suites

Libraries and Frameworks

Backend

• Express.js for REST API framework
• PostgreSQL with pg driver for database
• Better-auth for authentication
• AWS SDK for S3-compatible storage
• Zod for schema validation
• JWT for token management
• TypeScript for type safety

Frontend

• React 19 with functional components
• Vite for build tooling
• TanStack Query for data fetching
• React Hook Form with Zod validation
• Tailwind CSS for styling
• Radix UI for accessible component primitives
• React Router for navigation
• TypeScript for type safety

Coding Standards

General

• Use TypeScript for all code files
• Prefer descriptive, unabbreviated variable and function names
• Follow consistent file naming: kebab-case for files, PascalCase for components
• Maintain clear folder structure with feature-based organization
• Use ES modules (import/export syntax)
• Implement proper error handling with try-catch blocks
• Add appropriate logging for debugging

Backend Specific

• Use async/await for asynchronous operations
• Implement proper middleware for authentication and error handling
• Follow RESTful conventions for API endpoints
• Use Zod schemas for request/response validation
• Return consistent API responses using utility functions
• Implement proper database transaction handling

Frontend Specific

• Use functional components with hooks exclusively
• Implement proper TypeScript interfaces for all props
• Use React Hook Form for form handling
• Follow component composition patterns
• Implement proper loading and error states
• Use TanStack Query for server state management
• Keep components focused and single-purpose

Naming Conventions

• Variables, parameters, properties, and functions: Use camelCase
  • Examples: userName, getUserData(), isLoading
• React components and TypeScript types/interfaces: Use PascalCase
  • Examples: UserProfileDialog, interface User, type TableSchema
• Constants and Enum members: Use UPPER_CASE
  • Examples: const API_BASE_URL, enum Status { ACTIVE, INACTIVE }
• File naming:
  • Components: PascalCase.tsx (e.g., DataGrid.tsx)
  • Hooks: use + PascalCase.ts (e.g., useAuth.ts)
  • Services: camelCase.service.ts (e.g., auth.service.ts)
  • Utils: kebab-case.ts or camelCase.ts (e.g., database-utils.ts)
• No snake_case: Avoid snake_case except in SQL queries and external APIs

Code Style

• Use single quotes for strings
• Include semicolons at the end of statements
• Use arrow functions for callbacks and inline functions
• Prefer const over let, avoid var
• Use template literals for string interpolation
• Maintain consistent indentation (2 spaces)
• Format code with Prettier configuration

UI Guidelines

• Follow a clean, modern design with consistent spacing
• Use Radix UI primitives for accessibility
• Maintain consistent color scheme using CSS variables
• Use appropriate loading skeletons for data fetching
• Display clear error messages with actionable feedback
• Implement proper form validation with inline errors
• Use consistent icon set from lucide-react

Testing Standards

• Implement integration tests for API endpoints
• Maintain test coverage above 70%
• Mock external dependencies appropriately

Security Considerations

• Never commit secrets or API keys
• Use environment variables for configuration
• Implement proper authentication and authorization
• Validate all user inputs
• Sanitize data before database operations
• Use prepared statements for SQL queries
• Implement rate limiting for API endpoints
• Follow OWASP security best practices

Performance Guidelines

• Implement proper database indexing
• Use pagination for large data sets
• Optimize React component re-renders
• Implement proper caching strategies
• Use lazy loading for code splitting
• Optimize bundle size with proper imports
• Monitor and log performance metrics

Documentation

• Document all API endpoints with clear descriptions
• Include JSDoc comments for complex functions
• Maintain up-to-date README files
• Document environment variables and configuration
• Provide clear setup instructions
• Include examples for common use cases