Skip to content

NAMING_RECOMMENDATION.md

Latest commit

 

History

History
140 lines (105 loc) · 4.67 KB

NAMING_RECOMMENDATION.md

File metadata and controls

140 lines (105 loc) · 4.67 KB

Repository Naming Recommendation: Agent Services vs Connector Services

Current Situation

Currently, external integration services are named as {provider}-agent-service:

  • darian-agent-service
  • sepidar-agent-service
  • baran-agent-service
  • msnav-agent-service (Microsoft Navision)
  • dolibarr-agent-service (Dolibarr ERP)
  • etc.

Note: These services integrate with various external systems including:

  • POS (Point of Sale) systems
  • ERP (Enterprise Resource Planning) platforms
  • Large multi-purpose enterprise platforms (e.g., Microsoft Navision, SAP)

Analysis

Pros of "agent"

  • ✅ Technically accurate (they are agents deployed on store servers)
  • ✅ Short and concise
  • ✅ Already in use

Cons of "agent"

  • ❌ Confusing with CDC Agents (cdc-*-agent)
  • ❌ Doesn't clearly indicate integration purpose (POS/ERP/Enterprise systems)
  • ❌ "Agent" is commonly used for monitoring/automation tools in industry
  • ❌ Less descriptive of the actual function (integration/connection)

Recommended Options

Option 1: *-connector-service (Recommended ⭐)

Pattern: {provider}-connector-service

Examples:

  • darian-connector-service
  • sepidar-connector-service
  • baran-connector-service
  • kyansoft-connector-service

Pros:

  • ✅ Clearly indicates connection/integration purpose
  • ✅ Industry standard term for integration services
  • ✅ No confusion with CDC Agents
  • ✅ Self-documenting (connects external systems - POS/ERP/Enterprise - to platform)
  • ✅ Consistent with common microservices naming patterns
  • ✅ Generic enough to cover all types of integrations (POS, ERP, Enterprise platforms)

Cons:

  • ⚠️ Requires renaming existing repositories
  • ⚠️ Slightly longer than "agent"

Option 2: *-integration-service

Pattern: {provider}-integration-service

Examples:

  • darian-integration-service
  • sepidar-integration-service
  • baran-integration-service

Pros:

  • ✅ Very clear about purpose (integration)
  • ✅ Industry standard term
  • ✅ No confusion with other services

Cons:

  • ⚠️ Longer than "connector"
  • ⚠️ Less specific (could be any type of integration)

Option 3: *-pos-connector-service (Not Recommended)

Pattern: {provider}-pos-connector-service

Examples:

  • darian-pos-connector-service
  • sepidar-pos-connector-service

Pros:

  • ✅ Very explicit about POS integration

Cons:

  • ❌ Too long
  • ❌ Too limiting - doesn't cover ERP systems (e.g., Microsoft Navision, SAP) or other enterprise platforms
  • ❌ Misleading for non-POS integrations (e.g., msnav-pos-connector-service would be incorrect for Microsoft Navision ERP)
  • ❌ Redundant (provider name usually indicates the system type)

Option 4: Keep *-agent-service but add clarification

Pattern: {provider}-agent-service (no change)

Pros:

  • ✅ No migration needed
  • ✅ Already established

Cons:

  • ❌ Still confusing with CDC Agents
  • ❌ Less clear about purpose

Recommendation

Recommended: Option 1 - *-connector-service

Rationale:

  1. Clarity: "Connector" clearly indicates the service connects two systems
  2. Industry Standard: Common term in microservices architecture for integration services
  3. No Confusion: Completely different from CDC Agents
  4. Self-Documenting: The name itself explains the purpose
  5. Appropriate Length: Not too long, not too short
  6. Flexible: Generic enough to cover all types of integrations (POS, ERP, Enterprise platforms like Microsoft Navision, SAP)
  7. Future-Proof: Can accommodate new integration types without renaming

Migration Path:

If you decide to rename:

  1. Update repositories.json with new names
  2. Update NAMING_STANDARD.md documentation
  3. Create migration script if needed
  4. Update any references in code/documentation

Comparison Table

Option Clarity Industry Standard Length Flexibility Migration Cost
*-agent-service ⭐⭐ ⭐⭐ ⭐⭐⭐ ⭐⭐⭐ ✅ None
*-connector-service ⭐⭐⭐ ⭐⭐⭐ ⭐⭐⭐ ⭐⭐⭐ ⚠️ Medium
*-integration-service ⭐⭐⭐ ⭐⭐⭐ ⭐⭐ ⭐⭐⭐ ⚠️ Medium
*-pos-connector-service ⭐⭐⭐ ⭐⭐ ⭐ ⭐ ⚠️ Medium

Final Recommendation

Use *-connector-service because:

  • It's the clearest and most industry-standard option
  • It eliminates confusion with CDC Agents
  • It's self-documenting
  • It's flexible enough to cover all integration types (POS, ERP, Enterprise platforms)
  • It's future-proof for new integration types
  • The migration cost is acceptable for the long-term benefit