# roy-hc310/pyre-promotion architecture

> Architecture diagram of the GitHub repository roy-hc310/pyre-promotion, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/roy-hc310/pyre-promotion
- Repository: https://github.com/roy-hc310/pyre-promotion

## Overview

##### Main Components
- API & Routing Layer:
- This is evident from files such as core/application.go, core/route.go, and the feature-specific route files under feature-discount/v1/route.go and feature-health/v1/route.go.
- This layer as the entry point for HTTP API requests.
- Feature Modules:
- Each of the major features is separated into its own module:
- Discount Feature (feature-discount): Handles CRUD operations for promotions.
- Health Feature (feature-health): Provides system health endpoints.
- Core Internal Services:
- Under the core-internal directory, you have internal shared components such as configuration (conf), infrastructure integrations, domain models, protobuf definitions, and utilities.
- This layer encapsulates external system integrations (Postgres, Redis, Kafka, OpenTelemetry) and migration scripts (for setting up the database schema).
- Messaging Modules:
- Separate micro-components for Kafka interactions: the kafka-consume and kafka-produce directories.
- These likely manage background processing for consuming and producing Kafka messages, decoupling them from the synchronous HTTP flow.
- SQL Layer:
- Under directories like sqlc and core-internal/sqlc, SQL queries are defined which interface directly with the Postgres database.
- External Systems (Dependencies):
- Database: PostgreSQL.
- Message Broker: Kafka.
- Cache: Redis.
- Telemetry: OpenTelemetry.
- Additionally, Protobuf definitions and gRPC stubs indicate RPC or external service integration (e.g., product-proto-client).

##### Relationships and Interactions
- The API layer (with routing defined in core and the feature-specific subdirectories) receives HTTP requests (as shown in the README with example CURL commands).
- Requests are routed to their respective controllers and services in the discount and health modules.
- Within these services, core-internal infrastructure components are called to:
- Interact with the PostgreSQL database (using raw queries configured via sqlc).
- Cache or fetch data via Redis.
- Publish events or messages via Kafka.
- Trace and monitor operations via OpenTelemetry.
- The separate Kafka producer and consumer components illustrate how asynchronous messaging is managed:
- The kafka-produce component likely sends messages (possibly after certain discount actions).
- The kafka-consume component listens for specific topics/messages and processes them accordingly.

##### Architectural Patterns and Design Principles
- Layered Architecture: There is a clear separation between the API, business logic (services/controllers in feature directories), and data/infrastructure layers, exemplified by core-internal.
- Modularity: Each feature (discount, health) resides in its own module, keeping the codebase organized and promoting independent evolution.
- Concurrency: The README emphasizes the use of Go routines for concurrent processing. This is likely interwoven in the service implementations.
- Integration with External Services: The project is built to integrate with external partners and systems (Postgres, Kafka, Redis), and uses connection pooling and raw query optimizations for performance.
- Microservice-Like Structure: Although it runs as a single Go monolith in some respects, the existence of separate directories (kafka-consume, kafka-produce) hints at decoupled components that could be deployed as independent services.

##### Summary of Elements to Incorporate
- API Gateway/Router: Representing core application routing.
- Feature Modules: Highlight discount operations and system health.
- Core Internal Layer: Display shared configurations, service integrations (for Redis, Postgres, Kafka, OpenTelemetry), and migrations.
- Kafka Producer and Kafka Consumer modules: Indicate how the system manages asynchronous messaging.
- External Systems: Show Postgres (database), Redis (caching), Kafka (messaging), and any telemetry systems.
- Use of Go routines: Note concurrency in operations (this might be annotated next to the relevant components).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% API & Routing Layer
    subgraph "API & Routing Layer"
        API_Gateway["API Gateway/Router"]:::api
    end

    %% Feature Modules
    subgraph "Feature Modules"
        subgraph "Discount Module"
            Discount_Controller["Discount Controller"]:::feature
            Discount_Service["Discount Service"]:::feature
            Discount_Model["Discount Model"]:::feature
        end
        subgraph "Health Module"
            Health_Controller["Health Controller"]:::feature
            Health_Service["Health Service"]:::feature
            Health_Model["Health Model"]:::feature
        end
    end

    %% Core Internal Services
    subgraph "Core Internal Services"
        Config["Configuration"]:::internal
        Infrastructure["Infrastructure Integrations"]:::internal
        Domain_Models["Domain Models"]:::internal
        Protobuf["Protobuf & gRPC"]:::internal
        Utilities["Utilities"]:::internal
        Migrations["Migrations"]:::internal
    end

    %% Messaging Modules
    subgraph "Messaging Modules"
        Kafka_Consumer["Kafka Consumer"]:::messaging
        Kafka_Producer["Kafka Producer"]:::messaging
    end

    %% SQL Layer
    subgraph "SQL Layer"
        SQL_Queries["SQL Queries"]:::sql
    end

    %% External Systems
    subgraph "External Systems"
        PostgreSQL["PostgreSQL"]:::external
        Redis["Redis Cache"]:::external
        Kafka_External["Kafka Broker"]:::external
        OTEL["OpenTelemetry"]:::external
    end

    %% Connections - API to Feature Modules
    API_Gateway -->|"routes to"| Discount_Controller
    API_Gateway -->|"routes to"| Health_Controller

    %% Discount Module internal flow
    Discount_Controller -->|"calls"| Discount_Service
    Discount_Service -->|"uses"| Discount_Model

    %% Health Module internal flow
    Health_Controller -->|"calls"| Health_Service
    Health_Service -->|"uses"| Health_Model

    %% Feature Modules call Core Internal Services
    Discount_Service -->|"integrates with"| Infrastructure
    Health_Service -->|"integrates with"| Infrastructure

    %% Core Internal Services interactions
    Infrastructure -->|"executes queries"| SQL_Queries
    Infrastructure -->|"accesses"| PostgreSQL
    Infrastructure -->|"caches in"| Redis
    Infrastructure -->|"publishes to"| Kafka_External
    Infrastructure -->|"traces via"| OTEL

    %% Messaging interactions
    Discount_Service -->|"sends events"| Kafka_Producer
    Kafka_Producer -->|"publishes to"| Kafka_External
    Kafka_Consumer -->|"consumes from"| Kafka_External

    %% SQL Layer to External System
    SQL_Queries -->|"queries"| PostgreSQL

    %% Class definitions for colours
    classDef api fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef feature fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef internal fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef messaging fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef sql fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:2px;

    %% Click Events for API & Routing Layer
    click API_Gateway "https://github.com/roy-hc310/pyre-promotion/blob/master/core/application.go"
    click API_Gateway "https://github.com/roy-hc310/pyre-promotion/blob/master/core/route.go"
    click API_Gateway "https://github.com/roy-hc310/pyre-promotion/blob/master/feature-discount/v1/route.go"
    click API_Gateway "https://github.com/roy-hc310/pyre-promotion/blob/master/feature-health/v1/route.go"

    %% Click Events for Discount Feature Module
    click Discount_Controller "https://github.com/roy-hc310/pyre-promotion/blob/master/feature-discount/v1/controller/discount-controller.go"
    click Discount_Model "https://github.com/roy-hc310/pyre-promotion/blob/master/feature-discount/v1/model/discount-request.go"
    click Discount_Model "https://github.com/roy-hc310/pyre-promotion/blob/master/feature-discount/v1/model/discount-query.go"
    click Discount_Model "https://github.com/roy-hc310/pyre-promotion/blob/master/feature-discount/v1/model/discount-response.go"
    click Discount_Service "https://github.com/roy-hc310/pyre-promotion/blob/master/feature-discount/v1/service/discount-service.go"

    %% Click Events for Health Feature Module
    click Health_Controller "https://github.com/roy-hc310/pyre-promotion/blob/master/feature-health/v1/controller/discount-controller.go"
    click Health_Controller "https://github.com/roy-hc310/pyre-promotion/blob/master/feature-health/v1/route.go"
    click Health_Model "https://github.com/roy-hc310/pyre-promotion/blob/master/feature-health/v1/model/health-response.go"
    click Health_Service "https://github.com/roy-hc310/pyre-promotion/blob/master/feature-health/v1/service/health-service.go"

    %% Click Events for Core Internal Services
    click Config "https://github.com/roy-hc310/pyre-promotion/blob/master/core-internal/conf/env.go"
    click Infrastructure "https://github.com/roy-hc310/pyre-promotion/blob/master/core-internal/infrastructure/kafka.go"
    click Infrastructure "https://github.com/roy-hc310/pyre-promotion/blob/master/core-internal/infrastructure/middleware.go"
    click Infrastructure "https://github.com/roy-hc310/pyre-promotion/blob/master/core-internal/infrastructure/opentelemetry.go"
    click Infrastructure "https://github.com/roy-hc310/pyre-promotion/blob/master/core-internal/infrastructure/postgres.go"
    click Infrastructure "https://github.com/roy-hc310/pyre-promotion/blob/master/core-internal/infrastructure/redis.go"
    click Infrastructure "https://github.com/roy-hc310/pyre-promotion/blob/master/core-internal/infrastructure/product-proto-client.go"
    click Domain_Models "https://github.com/roy-hc310/pyre-promotion/blob/master/core-internal/model/core-model.go"
    click Domain_Models "https://github.com/roy-hc310/pyre-promotion/blob/master/core-internal/model/promotion-request.go"
    click Domain_Models "https://github.com/roy-hc310/pyre-promotion/blob/master/core-internal/model/promotion-response.go"
    click Protobuf "https://github.com/roy-hc310/pyre-promotion/blob/master/core-internal/proto/product.pb.go"
    click Protobuf "https://github.com/roy-hc310/pyre-promotion/blob/master/core-internal/proto/product_grpc.pb.go"
    click Utilities "https://github.com/roy-hc310/pyre-promotion/blob/master/core-internal/utils/common.go"
    click Utilities "https://github.com/roy-hc310/pyre-promotion/blob/master/core-internal/utils/constant.go"
    click Utilities "https://github.com/roy-hc310/pyre-promotion/blob/master/core-internal/utils/env.go"
    click Migrations "https://github.com/roy-hc310/pyre-promotion/tree/master/core-internal/migrations/"

    %% Click Events for Messaging Modules
    click Kafka_Consumer "https://github.com/roy-hc310/pyre-promotion/blob/master/kafka-consume/service/kafka-consume-service.go"
    click Kafka_Producer "https://github.com/roy-hc310/pyre-promotion/blob/master/kafka-produce/controller/kafka-producer-controller.go"
    click Kafka_Producer "https://github.com/roy-hc310/pyre-promotion/blob/master/kafka-produce/route.go"
    click Kafka_Producer "https://github.com/roy-hc310/pyre-promotion/blob/master/kafka-produce/service/kafka-produce-service.go"
    click Kafka_Producer "https://github.com/roy-hc310/pyre-promotion/blob/master/kafka-produce/model/kafka-producer-model.go"

    %% Click Events for SQL Layer
    click SQL_Queries "https://github.com/roy-hc310/pyre-promotion/blob/master/core-internal/sqlc/queries/promotions.sql"
    click SQL_Queries "https://github.com/roy-hc310/pyre-promotion/blob/master/sqlc/db.go"
    click SQL_Queries "https://github.com/roy-hc310/pyre-promotion/blob/master/sqlc/models.go"
    click SQL_Queries "https://github.com/roy-hc310/pyre-promotion/blob/master/sqlc/promotions.sql.go"
```
