wehub-resource-sync
147 lines
5.5 KiB
Markdown
147 lines
5.5 KiB
Markdown
# 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 |