# iyaki/simple-newsletter architecture

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

- Interactive diagram: https://gitdiagram.com/iyaki/simple-newsletter
- Repository: https://github.com/iyaki/simple-newsletter

## Overview

##### Main Components
- Web Server/Reverse Proxy: Represented by the .caddy directory with its production-specific Caddyfile. This component sits at the frontend to route incoming requests.
- PHP Application Backend:
- The core business logic is found within the libs folder. Here you see clear segmentation into:
– Adapters (e.g., FeedImporterLaminas.php, SenderPHPMailer.php, ResponderHttp.php) which interface with external services.
– Components (e.g., Auth, EmailTemplateFactory, FeedImporter, Sender) that handle specific tasks.
– Data, Models, and Templates which implement the MVC or layered design pattern for subscription management and newsletter generation.
- The bootstrap file (libs/bootstrap.php) initiates and configures the application.
- API Endpoints & Public Assets:
- The public folder organizes various entry points (index.php, v1 endpoints for subscriptions such as confirmation and cancellation, and the API spec file). This separation shows clear routing of HTTP requests.
- Database:
- The config folder (with database.php) and migrations directory (with SQL scripts for structure setup and optimizations) indicate the persistent data storage layer handling subscriptions and other relevant data.
- Cron Job for Sending Newsletters:
- A scheduled cron task (as specified in the README) uses a CURL request to an endpoint (i.e., public/send-newsletters) to trigger newsletter dispatch. Represent this as a separate periodic task that interacts with the backend.
- Deployment & Containerization:
- Dockerfile, docker-compose files, and scripts (scripts/build-push.sh, scripts/setup-containers.sh) which outline how the entire system is built, containerized, and deployed.

##### Out Relationships and Interactions
- From the Caddy proxy, route requests to the PHP application container (public directory entry points).
- Within the PHP application, illustrate layers:
- The routing layer (public/index.php and versioned endpoints v1) directs traffic to the core business logic (libs/Components, Data, Models).
- Adapter modules such as the PHPMailer adapter for email sending, and a feed importer component – these handle outbound communication to external systems if needed.

##### Architectural Patterns and Design Principles
- Layered architecture: entry point (public) → business logic (libs) → data handling (migrations, models/DAOs).
- Point out dependency inversion: using adapter classes (under libs/Adapters) to interact with external services.
- Environment-specific configurations (PHP ini files in .php directory, docker-compose files for deployment).
- If applicable, mention that the API is versioned (via the public/v1 folder) to support potential future changes.

##### Technologies, Frameworks, and Libraries
- PHP is the main programming language.
- Caddy is the reverse proxy/web server.
- Docker is used for containerization and deployment orchestration.
- PHPMailer (used in libs/Adapters/SenderPHPMailer.php) and possibly Laminas components (as seen in libs/Adapters/FeedImporterLaminas.php) are critical libraries.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        A("External Client/Browser"):::client
        B("Caddy Reverse Proxy"):::proxy
        C("API Endpoints & Public Assets"):::api
        A -->|"HTTP_Request"| B
        B -->|"Routes_to"| C
    end

    %% Application Layer
    subgraph "Application Layer"
        D("PHP Application Backend (Business Logic)"):::backend
        D1("Bootstrap & Core Logic"):::backend
        D2("Adapters (PHPMailer & Laminas)"):::backend
        D3("Components/Models/Templates"):::backend
        C -->|"Forwards_Request"| D
        D --> D1
        D --> D2
        D --> D3
    end

    %% Data Layer
    subgraph "Data Layer"
        E1("Database Config"):::database
        E2("Database Migrations"):::database
        %% Business logic interacts with database
        D ---|"Reads/Writes"| E1
        D ---|"Reads/Writes"| E2
    end

    %% Utilities
    subgraph "Utilities"
        F("Cron Job Task"):::cron
        F -->|"Invokes_newsletter_endpoint"| C
    end

    %% Deployment & Containerization
    subgraph "Deployment & Containerization"
        G1("Dockerfile"):::deployment
        G2("Docker Compose (Dev)"):::deployment
        G3("Docker Compose (Prod)"):::deployment
        G4("Build & Push Script"):::deployment
        G5("Setup Containers Script"):::deployment
    end

    %% Deployment orchestrates containerized services
    G1 --- B
    G2 --- C
    G3 --- D
    G4 --- E1
    G5 --- E2

    %% Click Events
    click B "https://github.com/iyaki/simple-newsletter/tree/main/.caddy/Caddyfile-prod"
    click D "https://github.com/iyaki/simple-newsletter/tree/main/libs/"
    click C "https://github.com/iyaki/simple-newsletter/tree/main/public/"
    click E1 "https://github.com/iyaki/simple-newsletter/blob/main/config/database.php"
    click E2 "https://github.com/iyaki/simple-newsletter/tree/main/migrations/"
    click F "https://github.com/iyaki/simple-newsletter/blob/main/public/send-newsletters/index.php"
    click G1 "https://github.com/iyaki/simple-newsletter/tree/main/Dockerfile"
    click G2 "https://github.com/iyaki/simple-newsletter/blob/main/compose.yaml"
    click G3 "https://github.com/iyaki/simple-newsletter/blob/main/compose-prod.yaml"
    click G4 "https://github.com/iyaki/simple-newsletter/blob/main/scripts/build-push.sh"
    click G5 "https://github.com/iyaki/simple-newsletter/blob/main/scripts/setup-containers.sh"

    %% Style Definitions
    classDef client fill:#a2d9ce,stroke:#2e4053,stroke-width:2px;
    classDef proxy fill:#fad7a0,stroke:#d35400,stroke-width:2px;
    classDef api fill:#f7dc6f,stroke:#f1c40f,stroke-width:2px;
    classDef backend fill:#f1948a,stroke:#cb4335,stroke-width:2px;
    classDef database fill:#aed6f1,stroke:#2980b9,stroke-width:2px;
    classDef cron fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef deployment fill:#f9e79f,stroke:#d4ac0d,stroke-width:2px;
```
