🏗️ InfraNotes Vendor Management & Procurement Service

A modern, cloud-native vendor management and procurement microservice built with Go 1.24+, designed for the InfraNotes enterprise financial management ecosystem.

---

📋 Overview

graph TB
    subgraph "InfraNotes Ecosystem"
        GW["🌐 API Gateway<br/>Port 8080"]
        
        subgraph "Core Services"
            VMS["🏢 Vendor Management<br/>Port 8082"]
            FIN["💰 Financial Analytics<br/>Port 8081"]
            CON["🏗️ Construction Module<br/>Port 8083"]
            CORE["⚙️ Core InfraNotes<br/>Port 8084"]
        end
        
        subgraph "Data Layer"
            PG1["🐘 PostgreSQL<br/>Vendor DB"]
            PG2["🐘 PostgreSQL<br/>Financial DB"]
            PG3["🐘 PostgreSQL<br/>Construction DB"]
            REDIS["🔴 Redis Cache"]
        end
        
        subgraph "Messaging & Events"
            KAFKA["📊 Apache Kafka<br/>Event Streaming"]
        end
        
        subgraph "Observability"
            DD["📊 Datadog<br/>Monitoring"]
            LOGS["📝 Structured Logs"]
        end
    end
    
    subgraph "External Systems"
        CLIENT["👤 Client Applications"]
        ERP["🏭 ERP Systems"]
        BANK["🏦 Banking APIs"]
    end
    
    %% Client connections
    CLIENT --> GW
    
    %% Gateway routing
    GW --> VMS
    GW --> FIN
    GW --> CON
    GW --> CORE
    
    %% Service to database connections
    VMS --> PG1
    FIN --> PG2
    CON --> PG3
    VMS --> REDIS
    FIN --> REDIS
    
    %% Event streaming
    VMS --> KAFKA
    FIN --> KAFKA
    CON --> KAFKA
    CORE --> KAFKA
    
    KAFKA --> VMS
    KAFKA --> FIN
    KAFKA --> CON
    KAFKA --> CORE
    
    %% External integrations
    VMS --> ERP
    VMS --> BANK
    FIN --> BANK
    
    %% Monitoring
    VMS --> DD
    FIN --> DD
    CON --> DD
    GW --> DD
    
    VMS --> LOGS
    FIN --> LOGS
    CON --> LOGS
    
    classDef service fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    classDef database fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    classDef messaging fill:#fff3e0,stroke:#e65100,stroke-width:2px
    classDef external fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px
    classDef monitoring fill:#fff8e1,stroke:#f57f17,stroke-width:2px
    
    class VMS,FIN,CON,CORE,GW service
    class PG1,PG2,PG3,REDIS database
    class KAFKA messaging
    class CLIENT,ERP,BANK external
    class DD,LOGS monitoring

The Vendor Management & Procurement Service is a critical microservice within the InfraNotes platform, providing comprehensive vendor lifecycle management, procurement workflows, and supplier diversity tracking. Built with 2025 industry best practices, it emphasizes security-first development, observability-driven design, and event-driven consistency.

🎯 Key Features

• 🏢 Comprehensive Vendor Management: Complete vendor lifecycle from onboarding to performance tracking
• 📊 Advanced Procurement Workflows: Rule-based approval processes with configurable thresholds
• 🔍 Supplier Diversity & Compliance: ESG tracking with automated compliance monitoring
• ⚡ Event-Driven Architecture: Real-time consistency via Apache Kafka event streaming
• 📈 Custom Analytics Engine: Rule-based cost analysis and performance optimization
• 🔒 Enterprise Security: SOC 2 Type II compliance with comprehensive audit trails
• 🚀 Cloud-Native Design: Container-first with Kubernetes-ready deployments

---

🏗️ System Architecture

High-Level Service Architecture

The diagram above shows the complete InfraNotes ecosystem architecture, highlighting the Vendor Management Service's position and interactions within the microservices landscape.

    graph TB
        subgraph "Vendor Management Service"
            subgraph "API Layer"
                GIN["🚀 Gin HTTP Server<br/>REST API"]
                MW["🛡️ Middleware<br/>Auth, CORS, Logging"]
                ROUTES["🛣️ Route Handlers<br/>Vendors, Procurement"]
            end
            
            subgraph "Application Layer"
                VS["🏢 Vendor Service"]
                PS["📋 Procurement Service"] 
                CS["📊 Compliance Service"]
                AS["📈 Analytics Service"]
            end
            
            subgraph "Domain Layer"
                VE["🏢 Vendor Entity"]
                PE["📋 Purchase Order Entity"]
                CE["✅ Compliance Entity"]
                SE["📊 Supplier Entity"]
            end
            
            subgraph "Infrastructure Layer"
                DB["🐘 PostgreSQL<br/>Repository"]
                KAFKA_CLIENT["📊 Kafka Client<br/>Events"]
                CACHE["🔴 Redis Cache"]
                MONITOR["📊 Datadog Monitor"]
            end
            
            subgraph "External Integrations"
                ERP_CLIENT["🏭 ERP Client"]
                BANK_CLIENT["🏦 Banking Client"]
                EMAIL["📧 Email Service"]
            end
        end
        
        subgraph "Configuration"
            CONFIG["⚙️ Config Manager<br/>YAML + Env Vars"]
        end
        
        %% API Flow
        GIN --> MW
        MW --> ROUTES
        ROUTES --> VS
        ROUTES --> PS
        ROUTES --> CS
        ROUTES --> AS
        
        %% Service to Domain
        VS --> VE
        PS --> PE
        CS --> CE
        AS --> SE
        
        %% Infrastructure connections
        VS --> DB
        PS --> DB
        CS --> DB
        AS --> CACHE
        
        VS --> KAFKA_CLIENT
        PS --> KAFKA_CLIENT
        CS --> KAFKA_CLIENT
        
        %% External connections
        VS --> ERP_CLIENT
        PS --> BANK_CLIENT
        AS --> EMAIL
        
        %% Monitoring
        GIN --> MONITOR
        VS --> MONITOR
        PS --> MONITOR
        
        %% Configuration
        CONFIG --> GIN
        CONFIG --> DB
        CONFIG --> KAFKA_CLIENT
        CONFIG --> MONITOR
        
        classDef api fill:#e3f2fd,stroke:#0277bd,stroke-width:2px
        classDef app fill:#f1f8e9,stroke:#388e3c,stroke-width:2px
        classDef domain fill:#fce4ec,stroke:#c2185b,stroke-width:2px
        classDef infra fill:#fff3e0,stroke:#f57c00,stroke-width:2px
        classDef external fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
        classDef config fill:#e8eaf6,stroke:#3f51b5,stroke-width:2px
        
        class GIN,MW,ROUTES api
        class VS,PS,CS,AS app
        class VE,PE,CE,SE domain
        class DB,KAFKA_CLIENT,CACHE,MONITOR infra
        class ERP_CLIENT,BANK_CLIENT,EMAIL external
        class CONFIG config

Vendor Management Service Internal Architecture

This diagram illustrates the clean architecture pattern implemented within the service, showing clear separation of concerns across API, Application, Domain, and Infrastructure layers.

Event-Driven Data Flow

    sequenceDiagram
        participant Client as 👤 Client
        participant API as 🚀 API Gateway
        participant VMS as 🏢 Vendor Service
        participant KAFKA as 📊 Kafka
        participant FIN as 💰 Financial Service
        participant CON as 🏗️ Construction Service
        participant DB as 🐘 PostgreSQL

        Note over Client,DB: Vendor Registration Flow

        Client->>API: POST /api/v1/vendors
        API->>VMS: Create Vendor Request
        VMS->>DB: Persist Vendor Data
        DB-->>VMS: Vendor Created
        
        VMS->>KAFKA: Publish VendorCreated Event
        Note over KAFKA: Topic: vendor.events
        
        KAFKA-->>FIN: VendorCreated Event
        KAFKA-->>CON: VendorCreated Event
        
        FIN->>FIN: Setup Financial Profile
        CON->>CON: Register for Construction Projects
        
        VMS-->>API: Vendor Registration Response
        API-->>Client: 201 Created

        Note over Client,DB: Purchase Order Flow

        Client->>API: POST /api/v1/procurement/orders
        API->>VMS: Create Purchase Order
        VMS->>DB: Persist Order Data
        
        VMS->>KAFKA: Publish PurchaseOrderCreated Event
        Note over KAFKA: Topic: procurement.events
        
        KAFKA-->>FIN: PurchaseOrderCreated Event
        FIN->>FIN: Update Budget Allocation
        FIN->>KAFKA: Publish BudgetUpdated Event
        
        KAFKA-->>VMS: BudgetUpdated Event
        VMS->>VMS: Update Order Status
        
        VMS-->>API: Order Created Response
        API-->>Client: 201 Created

        Note over Client,DB: Real-time Compliance Monitoring

        VMS->>KAFKA: Publish ComplianceCheck Event
        Note over KAFKA: Topic: compliance.events
        
        KAFKA-->>CON: ComplianceCheck Event
        CON->>CON: Validate Construction Compliance
        CON->>KAFKA: Publish ComplianceResult Event
        
        KAFKA-->>VMS: ComplianceResult Event
        VMS->>VMS: Update Vendor Status
        VMS->>DB: Persist Compliance Data

        Note over VMS,DB: All events are monitored<br/>by Datadog for observability

This sequence diagram demonstrates how the service participates in event-driven workflows, ensuring data consistency across the InfraNotes ecosystem through Apache Kafka event streaming.

---

🚀 Quick Start

Prerequisites

• Go 1.24+ - Download
• Docker & Docker Compose - Install Docker
• PostgreSQL 16+ - For local development
• Apache Kafka 3.0+ - Message broker
• Redis 7+ - Caching layer

Installation

1. Clone the repository

   git clone https://github.com/Infra-Forge/infra-vendor.git
   cd infra-vendor
   

2. Install dependencies

   go mod tidy
   

3. Set up configuration

   cp configs/development/config.yaml.example configs/development/config.yaml
   # Edit configuration as needed
   

4. Start infrastructure services

   docker-compose up -d postgres kafka redis
   

5. Run database migrations

   go run cmd/migrate/main.go up
   

6. Start the service

   go run cmd/server/main.go
   

Docker Development Setup

# Build and run the complete stack
docker-compose up --build -d

# Check service health
curl http://localhost:8082/health

# View logs
docker-compose logs -f infra-vendor

---

📚 API Documentation

Base URL

http://localhost:8082/api/v1

Authentication

All endpoints require JWT authentication via the InfraNotes API Gateway.

Core Endpoints

Vendor Management

Method	Endpoint	Description
GET	/vendors	List all vendors with pagination
POST	/vendors	Create a new vendor
GET	/vendors/{id}	Get vendor by ID
PUT	/vendors/{id}	Update vendor information
DELETE	/vendors/{id}	Soft delete vendor
GET	/vendors/{id}/performance	Get vendor performance metrics

Procurement Management

Method	Endpoint	Description
GET	/procurement/orders	List purchase orders
POST	/procurement/orders	Create purchase order
GET	/procurement/orders/{id}	Get order details
PUT	/procurement/orders/{id}/approve	Approve purchase order
PUT	/procurement/orders/{id}/reject	Reject purchase order

Supplier Diversity

Method	Endpoint	Description
GET	/supplier-diversity/metrics	Get diversity metrics
POST	/supplier-diversity/certifications	Add certification
GET	/supplier-diversity/reports	Generate compliance reports

Event Topics

The service publishes and consumes events via Kafka:

Topic	Events Published	Events Consumed
vendor.events	VendorCreated, VendorUpdated, VendorDeactivated	-
procurement.events	PurchaseOrderCreated, OrderApproved, OrderRejected	BudgetUpdated
compliance.events	ComplianceCheck, CertificationExpiring	ComplianceResult

---

🛠️ Development

Project Structure

infra-vendor/
├── cmd/server/              # Application entry point
│   ├── main.go             # Main application
│   └── app.go              # Application lifecycle
├── internal/               # Private application code
│   ├── api/                # HTTP API layer
│   │   ├── handlers/       # Request handlers
│   │   ├── middleware/     # HTTP middleware
│   │   └── routes/         # Route definitions
│   ├── application/        # Application services
│   │   ├── services/       # Business logic services
│   │   └── usecases/       # Use case implementations
│   ├── domain/             # Business domain
│   │   ├── vendor/         # Vendor domain entities
│   │   ├── procurement/    # Procurement domain entities
│   │   └── compliance/     # Compliance domain entities
│   └── infrastructure/     # External concerns
│       ├── database/       # Database implementations
│       ├── kafka/          # Kafka client
│       ├── cache/          # Redis cache
│       └── config/         # Configuration management
├── pkg/                    # Public packages
│   ├── auth/              # Authentication utilities
│   ├── events/            # Event definitions
│   ├── monitoring/        # Observability tools
│   └── errors/            # Error handling
├── configs/               # Configuration files
├── deployments/           # Deployment manifests
└── docs/                  # Documentation

Development Guidelines

Code Standards

• Go 1.24+ Features: Leverage modern Go idioms and patterns
• Clean Architecture: Maintain strict layer separation
• Domain-Driven Design: Business logic in domain layer
• SOLID Principles: Single responsibility, dependency inversion
• Test-Driven Development: Minimum 80% test coverage

Commit Conventions

feat: add vendor performance analytics endpoint
fix: resolve kafka connection timeout issue
docs: update API documentation for procurement endpoints
test: add unit tests for vendor validation logic

Development Workflow

1. Create feature branch from develop
2. Implement feature with comprehensive tests
3. Run full test suite and linting
4. Create pull request with detailed description
5. Code review and approval required
6. Merge to develop branch

Continuous Integration (CI)

CI runs automatically on pushes and pull requests:

# Locally replicate CI steps
go mod tidy
golangci-lint run --timeout=5m
staticcheck ./...
go test -race -covermode=atomic -coverprofile=coverage.out ./...
govulncheck ./...

Artifacts:

• Coverage file: coverage.out (uploaded by CI)
• Lint rules: .golangci.yml

---

🔧 Configuration

Environment Variables

Variable	Description	Default
SERVER_PORT	HTTP server port	8082
DB_HOST	PostgreSQL host	localhost
DB_PORT	PostgreSQL port	5432
KAFKA_BROKERS	Kafka broker addresses	localhost:9092
REDIS_HOST	Redis host	localhost
DATADOG_HOST	Datadog agent host	localhost
DD_ENV	Datadog environment	development
LOG_LEVEL	Logging level	info

Configuration Files

Configuration is managed through YAML files with environment-specific overrides:

• configs/development/config.yaml - Development settings
• configs/staging/config.yaml - Staging environment
• configs/production/config.yaml - Production settings

---

📊 Monitoring & Observability

Datadog Integration

• Metrics: Custom business metrics and system metrics
• Traces: Distributed tracing across the service call chain
• Logs: Structured JSON logging with correlation IDs
• Dashboards: Pre-built dashboards for vendor management KPIs

Health Checks

• /health - Basic health check
• /readiness - Bounded Kubernetes readiness probe for database connectivity
• /liveness - Liveness probe for Kubernetes

Key Metrics

• vendor.registration.rate - Vendor registration rate
• procurement.order.processing_time - Order processing duration
• compliance.check.success_rate - Compliance check success rate
• kafka.consumer.lag - Event processing lag

---

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Getting Help

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

Built with ❤️ using:

• Gin - HTTP web framework
• PostgreSQL - Primary database
• Apache Kafka - Event streaming
• Datadog - Observability platform
• Docker - Containerization