# ssaavedraa/phoenix architecture

> Architecture diagram of the GitHub repository ssaavedraa/phoenix, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ssaavedraa/phoenix
- Repository: https://github.com/ssaavedraa/phoenix

## Overview

##### Project type and purpose
- Phoenix is a single‐purpose microservice written in Go. It acts as a Kafka consumer that transforms incoming messages into email sends using templating and localization.
- Its primary goal is reliable, high‐throughput email delivery by reading from a Kafka topic, formatting content, and handing it off to an email‐sending implementation.

##### File structure
- cmd/main.go: application entrypoint that boots the service.
- config/config.go: centralizes Kafka and environment configuration.
- consumer/kafka_consumer.go: logic to connect to Kafka, subscribe, and consume messages.
- factories/email_factory.go & _Impl.go: abstract factory + implementation that builds and sends emails.
- i18n/: JSON files for localization (English, Spanish) per template.
- templates/: HTML templates keyed by use case (user_invite_mvp).
- .air.toml, Dockerfile, .env.example: dev tooling, containerization, environment variable management.

##### README for additional insights
- Emphasis on Golang’s concurrency for throughput.
- Mentions an API, but code shows a Kafka‐based consumer pattern—no HTTP server here.
- Aims for security, reliability, and scalability.

a. Main components
- Kafka Cluster (external service)
- Phoenix Service (containerized microservice)
– Configuration Loader
– Kafka Consumer
– Message Handler / Business Logic
– Email Factory (interface + implementation)
– Template Engine + i18n Loader
- External Email Provider (SMTP or third‐party API)
- Optional: Metrics & Logging system
b. Relationships & interactions
1. Phoenix startup reads config (config module) from environment or .env.
2. Kafka Consumer connects to Kafka cluster and subscribes to topic(s).
3. On message receive, Consumer passes raw payload to Message Handler.
4. Handler invokes Email Factory; factory loads appropriate template from templates/, merges i18n JSON, builds email content.
5. Email Factory Impl calls External Email Provider over SMTP/HTTP.
6. Success/failure is logged; metrics emitted to monitoring.
c. Architectural patterns & principles
– Single‐responsibility: each package (config, consumer, factories) handles one concern.
– Factory pattern for pluggable email implementations.
– Concurrency: consumer poll loop with worker pools (implied by Go’s goroutines).
– Containerizable: Dockerfile for immutable deployments.
d. Key technologies & libraries
– Golang runtime & standard library
– Segmentio/kafka-go (or similar) for Kafka client
– html/template for rendering
– JSON for i18n
– Docker for containerization

##### Detail without over‐partitioning
- Every submodule shown in the file tree for clarity.
- Don’t stop at “backend” vs. “frontend”—instead, break backend into config, consumer, handler, factory, i18n, templates.

## Diagram (Mermaid)

```mermaid
flowchart TD
  KafkaCluster["Kafka Cluster"]:::external
  subgraph "Phoenix Service (Containerized Go Microservice)"
    direction TB
    Entrypoint["Main (cmd/main.go)"]:::internal
    Config["Configuration Loader"]:::internal
    Consumer["Kafka Consumer"]:::internal
    Handler["Message Handler"]:::internal
    FactoryInt["Email Factory Interface"]:::internal
    FactoryImpl["Email Factory Implementation"]:::internal
    Template["Template Engine"]:::data
    I18nEn["i18n: en.json"]:::data
    I18nEs["i18n: es.json"]:::data
    DevTools[".air.toml"]:::devtools
    Docker["Dockerfile"]:::devtools
    Env[".env.example"]:::devtools
    GoMod["go.mod"]:::devtools
    GoSum["go.sum"]:::devtools
  end
  EmailProvider["External Email Provider"]:::external
  Metrics["Logging & Monitoring"]:::external

  KafkaCluster -->|"consume messages"| Consumer
  Entrypoint -->|"load config"| Config
  Config --> Consumer
  Consumer --> Handler
  Handler --> FactoryInt
  FactoryInt --> FactoryImpl
  FactoryImpl -->|send email| EmailProvider
  Handler -->|emit metrics| Metrics
  Template --> FactoryImpl
  I18nEn --> FactoryImpl
  I18nEs --> FactoryImpl

  click Entrypoint "https://github.com/ssaavedraa/phoenix/blob/main/cmd/main.go"
  click Config "https://github.com/ssaavedraa/phoenix/blob/main/config/config.go"
  click Consumer "https://github.com/ssaavedraa/phoenix/blob/main/consumer/kafka_consumer.go"
  click FactoryInt "https://github.com/ssaavedraa/phoenix/blob/main/factories/email_factory.go"
  click FactoryImpl "https://github.com/ssaavedraa/phoenix/blob/main/factories/email_factory_Impl.go"
  click Template "https://github.com/ssaavedraa/phoenix/blob/main/templates/user_invite_mvp/index.html"
  click I18nEn "https://github.com/ssaavedraa/phoenix/blob/main/i18n/user_invite_mvp/en.json"
  click I18nEs "https://github.com/ssaavedraa/phoenix/blob/main/i18n/user_invite_mvp/es.json"
  click Docker "https://github.com/ssaavedraa/phoenix/tree/main/Dockerfile"
  click Env "https://github.com/ssaavedraa/phoenix/blob/main/.env.example"
  click DevTools "https://github.com/ssaavedraa/phoenix/blob/main/.air.toml"
  click GoMod "https://github.com/ssaavedraa/phoenix/blob/main/go.mod"
  click GoSum "https://github.com/ssaavedraa/phoenix/blob/main/go.sum"

  classDef external fill:#CCE5FF,stroke:#3399FF
  classDef internal fill:#E6FFE6,stroke:#33CC33
  classDef data fill:#FFF2CC,stroke:#FFCC00
  classDef devtools fill:#F2F2F2,stroke:#999999
```
