How roy-hc310/pyre-promotion works
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).