agmission/Development/server/docs/ARCHITECTURE_SUMMARY.md

Partner Integration Architecture Summary

Overview

This document summarizes the simplified partner integration architecture that uses a dual-user approach with environment-based configuration, eliminating the complexity of separate partner management systems.

Architecture Benefits

1. Simplified User Management

• Partners as Users: Partner organizations are User entities with discriminator pattern
• Partner System Users: Customer accounts within partner systems, also as User entities
• Unified Auth: Leverage existing User authentication and authorization
• No Separate Models: No complex partner management UI or separate database collections

2. Environment-Based Configuration

• Partner Settings: API endpoints, credentials, timeouts via environment variables
• Easy Deployment: Configuration changes without code deployment
• Secure Credentials: Environment-based credential management
• Partner-Specific: Each partner can have different configuration

3. Customer Isolation

• Individual Accounts: Each customer has their own partner system account
• Separate Credentials: Customer-specific API keys and authentication
• Scalable: Easy to add new customers to partner systems
• Secure: Customer data isolation within partner systems

Data Model

User Entity with Discriminators

// Base User model with discriminator support
const User = mongoose.model('User', userSchema);

// Partner Organization (e.g., SatLoc company)
const Partner = User.discriminator('PARTNER', {
  partnerCode: String,      // 'SATLOC', 'AGIDRONEX'
  partnerName: String,      // 'SatLoc Cloud'
  configuration: Mixed      // Partner-specific settings
});

// Customer account in partner system
const PartnerSystemUser = User.discriminator('PARTNER_SYSTEM_USER', {
  partner: ObjectId,        // Reference to Partner
  customer: ObjectId,       // AgMission customer
  partnerUserId: String,    // Customer's ID in partner system
  companyId: String,        // Customer's company ID in partner system
  apiKey: String,           // Customer's API key
  apiSecret: String         // Customer's API secret
});

Job Assignment References

// JobAssign model references User directly
const JobAssign = mongoose.model('JobAssign', {
  job: { type: Number, ref: 'Job' },
  user: { type: Schema.Types.ObjectId, ref: 'User' }, // Can be Partner or PartnerSystemUser
  status: { type: Number, enum: AssignStatus }
});

API Structure

Partner Management Endpoints

GET    /api/partners                    # List partner organizations
POST   /api/partners                    # Create partner organization
GET    /api/partners/:id                # Get partner details
PUT    /api/partners/:id                # Update partner
DELETE /api/partners/:id                # Delete partner (soft delete)

GET    /api/partners/systemUsers        # List all partner system users
POST   /api/partners/systemUsers        # Create partner system user
GET    /api/partners/systemUsers/:id    # Get partner system user by ID
PUT    /api/partners/systemUsers/:id    # Update partner system user
DELETE /api/partners/systemUsers/:id    # Delete partner system user (soft delete)

POST   /api/partners/syncData           # Sync data from partner system
POST   /api/partners/uploadJob          # Upload job to partner system

Job Assignment Flow

1. Create JobAssign with user: partnerSystemUserId
2. SatlocService.getCustomerCredentials(customerId) -> finds PartnerSystemUser
3. API calls use customer-specific credentials (companyId, apiKey, partnerUserId)
4. All operations are isolated to customer's partner account

Environment Configuration

Partner System Configuration

# Global Settings
PARTNER_SYNC_INTERVAL=300000
PARTNER_HEALTH_CHECK_INTERVAL=60000
PARTNER_MAX_CONCURRENT_JOBS=10
PARTNER_ENCRYPT_CREDENTIALS=true

# SatLoc Configuration
SATLOC_API_ENDPOINT=https://www.satloccloud.com/api/Satloc
SATLOC_API_KEY=default_api_key
SATLOC_API_SECRET=default_api_secret
SATLOC_API_TIMEOUT=30000
SATLOC_RETRY_ATTEMPTS=3
SATLOC_RATE_LIMIT=60

# AgIDronex Configuration  
AGIDRONEX_API_ENDPOINT=https://api.agidronex.com/v1
AGIDRONEX_API_KEY=default_api_key
AGIDRONEX_API_SECRET=default_api_secret
AGIDRONEX_API_TIMEOUT=25000

Implementation Files

Core Files Created/Modified

1. helpers/constants.js: Added UserTypes.PARTNER and UserTypes.PARTNER_SYSTEM_USER
2. model/partner.js: Partner and PartnerSystemUser discriminator models
3. controllers/partner.js: Partner and partner system user CRUD operations
4. routes/partner.js: RESTful routes for partner management
5. helpers/partner_config.js: Environment-based partner configuration
6. services/satloc_service.js: SatLoc API integration using customer credentials

Documentation Updated

1. docs/SATLOC_API_SPECIFICATION.md: Updated with dual-user architecture
2. docs/IMPLEMENTATION_GUIDE.md: Step-by-step implementation with new approach
3. docs/MONITORING_GUIDE.md: Simplified monitoring without complex infrastructure

Monitoring Strategy

Simplified Approach

• Basic Health Checks: Database, partner users, application health
• Essential Logging: Partner operations, sync activities, critical errors
• Simple Alerting: Email notifications for critical issues
• HTML Dashboard: Basic web interface for system status

No Complex Infrastructure

• ❌ No Grafana dashboards
• ❌ No Prometheus metrics
• ❌ No complex queue monitoring
• ✅ Simple health endpoints
• ✅ File-based logging
• ✅ Environment-based configuration

Benefits Summary

For Development

• Faster Implementation: Reuse existing User infrastructure
• Less Code: No separate partner models or complex management
• Easier Testing: Standard User entity patterns
• Better Maintainability: Fewer moving parts

For Operations

• Simple Deployment: Environment variables for configuration
• Easy Scaling: Add customers to partner systems easily
• Secure: Customer isolation and environment-based credentials
• Monitoring: Basic health checks without infrastructure overhead

For Business

• Customer Isolation: Each customer has own partner account
• Partner Flexibility: Easy to add new partners with environment config
• Cost Effective: No complex monitoring infrastructure required
• Scalable: Handles multiple customers per partner efficiently

This architecture provides all the benefits of partner integration while maintaining simplicity and avoiding the complexity of separate partner management systems.