This is a secure web application that enables users to connect to their self-hosted ERPNext instances, verify user IDs, and retrieve user-specific data through a modern, elegant interface. The application prioritizes security, usability, and reliability.
- Encrypted Credential Storage: API keys and secrets are encrypted using AES-256-GCM before storage in the database
- Connection Verification: Tests the connection before saving to ensure credentials are valid
- Connection Status Display: Shows the current connection status and last tested timestamp
- Update Capability: Users can update their connection credentials at any time
- Real-time Verification: Verifies user IDs against the ERPNext instance
- User Information Display: Shows verified user details including name, email, type, and status
- Error Handling: Clear error messages for non-existent users or connection issues
- Dynamic DocType Selection: Fetches available document types from ERPNext
- Flexible Data Retrieval: Supports querying various ERPNext document types (Users, Employees, Customers, etc.)
- Structured Table Display: Presents data in a clean, organized table format
- Data Caching: Implements 1-hour caching to reduce API calls and improve performance
- Responsive Design: Works seamlessly on desktop, tablet, and mobile devices
- Token-Based Authentication: Uses ERPNext's token-based authentication (API Key + API Secret)
- Encrypted Storage: All credentials are encrypted at rest using AES-256-GCM
- HTTPS Only: All API calls to ERPNext use HTTPS
- User Authentication: OAuth integration ensures only authenticated users can access the application
- Role-Based Access: User roles are managed through the database
- Frontend: React 19 with TypeScript, Tailwind CSS 4, shadcn/ui components
- Backend: Express 4 with tRPC 11 for type-safe API procedures
- Database: MySQL with Drizzle ORM for type-safe queries
- Authentication: OAuth for user authentication
- Encryption: Node.js crypto module (AES-256-GCM)
erpnext-integration/
├── client/
│ └── src/
│ ├── pages/
│ │ ├── Home.tsx # Landing and main navigation
│ │ ├── ERPNextConfig.tsx # Connection configuration form
│ │ └── DataRetrieval.tsx # User verification and data retrieval
│ ├── components/ # Reusable UI components
│ ├── lib/trpc.ts # tRPC client setup
│ └── App.tsx # Main app router
├── server/
│ ├── routers.ts # tRPC procedure definitions
│ ├── db.ts # Database query helpers
│ ├── erpnext.ts # ERPNext API client
│ ├── crypto.ts # Encryption utilities
│ └── _core/ # Framework core (OAuth, context, etc.)
├── drizzle/
│ └── schema.ts # Database schema definitions
└── package.json
Stores authenticated user information from OAuth.
Stores ERPNext connection credentials per user:
userId: Reference to authenticated usererpnextUrl: Base URL of ERPNext instanceapiKey: Encrypted API KeyapiSecret: Encrypted API SecretisActive: Connection status flaglastTestedAt: Timestamp of last successful connection test
Caches retrieved ERPNext data to reduce API calls:
connectionId: Reference to ERPNext connectionuserId: Reference to authenticated userverifiedUserId: The ERPNext user ID that was verifieddoctype: Document type (e.g., "User", "Employee")data: JSON-encoded retrieved dataexpiresAt: Cache expiration timestamp (1 hour)
Type: Mutation
Input: { erpnextUrl: string, apiKey: string, apiSecret: string }
Output: { success: boolean, message: string }
Description: Configures a new ERPNext connection with automatic verification
Type: Query
Output: { configured: boolean, erpnextUrl?: string, lastTestedAt?: Date }
Description: Retrieves current connection status (without exposing credentials)
Type: Mutation
Input: { userId: string }
Output: { success: boolean, user?: ERPNextUser }
Description: Verifies a user ID exists in ERPNext and returns user details
Type: Query
Input: { userId: string, doctype: string }
Output: { success: boolean, data?: unknown, cached?: boolean }
Description: Retrieves user-specific data from ERPNext (with caching)
Type: Query
Output: string[]
Description: Returns list of available document types for data retrieval
Credentials are encrypted using AES-256-GCM:
- Algorithm: AES-256-GCM (authenticated encryption)
- Key Management: Uses
ENCRYPTION_KEYenvironment variable (must be 64 hex characters) - Format:
IV:AuthTag:EncryptedData(all hex-encoded) - Decryption: Only performed server-side when making API calls to ERPNext
- Never expose credentials to frontend: Credentials are stored server-side only
- HTTPS enforcement: All external API calls use HTTPS
- Token-based auth: Uses ERPNext's built-in token authentication
- Input validation: All user inputs are validated with Zod schemas
- Error handling: Sensitive error details are not exposed to frontend
- Session management: OAuth handles user session security
- Node.js 22.13.0 or later
- MySQL database
- Self-hosted ERPNext instance with API access enabled
-
Configure Environment Variables
# Required for encryption ENCRYPTION_KEY=<64-character-hex-string> # Database connection DATABASE_URL=mysql://user:password@localhost:3306/erpnext_integration # OAuth configuration VITE_APP_ID=<your-app-id> OAUTH_SERVER_URL=<oauth-url> JWT_SECRET=<jwt-secret>
-
Install Dependencies
pnpm install
-
Run Database Migrations
pnpm drizzle-kit migrate
-
Start Development Server
pnpm dev
-
Build for Production
pnpm build pnpm start
- Sign in with your account
- Click "Configure Connection"
- Enter your ERPNext instance URL (e.g.,
https://erpnext.example.com) - Enter your API Key and API Secret (generated in ERPNext User settings)
- Click "Configure Connection" - the system will verify the credentials
- Click "Retrieve Data"
- Enter the ERPNext user ID (email or username)
- Click "Verify User"
- The system will display the verified user's information
- Select a document type from the dropdown (User, Employee, Customer, etc.)
- The system will fetch and display the user's associated data
- Data is cached for 1 hour to improve performance
pnpm test- Encryption: Verify encrypt/decrypt functionality with various inputs
- Authentication: Test connection verification with valid/invalid credentials
- Error Handling: Verify proper error messages for edge cases
- Verify ERPNext URL is accessible from your network
- Check API Key and API Secret are correct
- Ensure the user has API access enabled in ERPNext
- Verify HTTPS certificate is valid (if using self-signed, may need configuration)
- Verify the user ID is correct (case-sensitive in ERPNext)
- Ensure the user exists in ERPNext
- Check user permissions in ERPNext
- Verify the user has access to the selected document type in ERPNext
- Check if the document type is available in your ERPNext instance
- Try clearing browser cache and refreshing
- Retrieved data is cached for 1 hour
- Cache is stored in the database for persistence across sessions
- Cache is automatically invalidated after expiration
- Consider implementing rate limiting for ERPNext API calls
- Monitor API usage to avoid hitting ERPNext rate limits
- Advanced Filtering: Add custom filters for data retrieval
- Export Functionality: Export retrieved data to CSV/Excel
- Audit Logging: Log all data access for compliance
- Multi-Instance Support: Support multiple ERPNext instances per user
- Webhooks: Real-time data synchronization with ERPNext
- API Documentation: Auto-generated API documentation
- Monitor database performance, especially the cache table
- Track API response times to ERPNext
- Monitor encryption/decryption performance
- Keep dependencies updated regularly
- Monitor ERPNext API changes
- Review security advisories