SyncBridge - Data Synchronization Platform

A full-stack web application for synchronizing customer and organization data between Zendesk (Helpdesk) and ConnectWise (CRM) systems.

🏗️ Architecture

Backend (NestJS + TypeScript)

• SyncModule: Orchestrates sync logic, triggers, and status
• MappingModule: Stores ID relationships between systems
• AdaptersModule: Contains ZendeskAdapter and ConnectWiseAdapter
• FuzzyMatchService: Compares records using name, email, phone, org with scoring
• ConflictResolverService: Handles user overrides vs. default source-of-truth logic
• FieldMappingService: Manages field-level logic and applies conversion rules
• AuthModule: JWT-based login/authentication

Frontend (React + Vite + Tailwind)

• Dashboard: Last sync time, active jobs, manual sync trigger
• Conflicts View: Shows record mismatches and lets user select the winning system
• Fuzzy Match Review: Suggests possible matches for unmapped records
• Field Mapping Editor: Shows CRM + Helpdesk fields side-by-side with conversion rules
• Mapping Overview: Displays existing Customer & Org mappings

Database (PostgreSQL)

• CustomerMapping, OrganizationMapping
• FieldDefinition, FieldMapping
• LookupTable, LookupValue
• User, SyncLog

🚀 Quick Start

Prerequisites

• Node.js 18+
• Docker & Docker Compose
• PostgreSQL (if running locally)

Development Setup

1. Clone and install dependencies

git clone <repository-url>
cd syncbridge
npm install

2. Set up environment variables

cp .env.example .env
# Edit .env with your configuration

3. Start with Docker Compose

npm run docker:up

4. Or run locally

# Start database
docker run -d --name postgres -e POSTGRES_PASSWORD=password -p 5432:5432 postgres:15

# Install backend dependencies
cd backend && npm install

# Install frontend dependencies  
cd ../frontend && npm install

# Start both services
cd .. && npm run dev

Access the Application

• Frontend: http://localhost:5173
• Backend API: http://localhost:3000
• Database: localhost:5432

🔧 Configuration

Environment Variables

Database

• DB_HOST: PostgreSQL host (default: localhost)
• DB_PORT: PostgreSQL port (default: 5432)
• DB_USERNAME: Database username
• DB_PASSWORD: Database password
• DB_NAME: Database name

Authentication

• JWT_SECRET: Secret key for JWT tokens

ConnectWise CRM

• CONNECTWISE_API_URL: ConnectWise API endpoint
• CONNECTWISE_COMPANY_ID: Your company identifier
• CONNECTWISE_PUBLIC_KEY: API public key
• CONNECTWISE_PRIVATE_KEY: API private key

Zendesk Helpdesk

• ZENDESK_SUBDOMAIN: Your Zendesk subdomain
• ZENDESK_EMAIL: Admin email for API access
• ZENDESK_API_TOKEN: API token for authentication

📊 Key Features

Sync Behavior

• Fuzzy Matching: Automatically matches records using name, email, phone, organization
• Conflict Resolution: User can override which system wins for specific fields
• Persistent Mappings: Stores relationships between CRM and Helpdesk IDs
• Field Transformation: Supports conversion rules (toUpperCase, trim, dateFormat, etc.)
• Lookup Tables: Value mapping for different field formats between systems

Security

• JWT-based authentication with bcrypt password hashing
• Protected API endpoints with middleware
• Environment-based configuration
• Docker secrets support

Monitoring

• Comprehensive sync logging
• Real-time status dashboard
• Conflict detection and resolution tracking
• Manual sync triggers

🛠️ Development

Project Structure

syncbridge/
├── backend/                 # NestJS API
│   ├── src/
│   │   ├── auth/           # Authentication module
│   │   ├── sync/           # Sync orchestration
│   │   ├── mapping/        # ID relationship management
│   │   ├── adapters/       # External system adapters
│   │   ├── field-mapping/  # Field transformation logic
│   │   └── database/       # Entities and database config
│   └── Dockerfile
├── frontend/               # React application
│   ├── src/
│   │   ├── components/     # Reusable UI components
│   │   ├── pages/          # Application pages
│   │   ├── stores/         # State management
│   │   └── lib/            # Utilities and API client
│   └── Dockerfile
├── docker-compose.yml      # Multi-container setup
└── README.md

Available Scripts

Root Level

• npm run dev: Start both backend and frontend in development
• npm run build: Build both applications
• npm run test: Run all tests
• npm run docker:up: Start with Docker Compose
• npm run docker:down: Stop Docker containers

Backend

• npm run start:dev: Start in development mode with hot reload
• npm run build: Build for production
• npm run test: Run unit tests
• npm run migration:generate: Generate database migration
• npm run migration:run: Run pending migrations

Frontend

• npm run dev: Start development server
• npm run build: Build for production
• npm run preview: Preview production build

🔄 API Endpoints

Authentication

• POST /auth/login: User login

Sync Management

• POST /sync/manual: Trigger manual sync
• GET /sync/status: Get sync status and recent logs

Mappings

• GET /mappings/customers: Get customer mappings
• GET /mappings/organizations: Get organization mappings
• POST /mappings/customers: Create customer mapping
• PUT /mappings/customers/:id: Update customer mapping

Field Mappings

• GET /field-mappings: Get field mappings
• POST /field-mappings: Create field mapping
• GET /field-mappings/definitions: Get field definitions
• GET /field-mappings/lookup-tables: Get lookup tables

📝 Notes

This is a scaffold implementation with:

• ✅ Complete architecture and folder structure
• ✅ Database models and relationships
• ✅ REST API endpoints
• ✅ Admin UI with all required views
• ✅ Authentication and security
• ✅ Docker deployment setup

TODO for production:

• Implement actual API calls in adapters (currently stubbed)
• Add comprehensive error handling
• Implement real-time sync status updates
• Add data validation and sanitization
• Set up monitoring and logging
• Add comprehensive test coverage

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

This project is licensed under the MIT License.