# lukemathwalker/zero-to-production architecture

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

- Interactive diagram: https://gitdiagram.com/lukemathwalker/zero-to-production
- Repository: https://github.com/lukemathwalker/zero-to-production

## Overview

##### Main Components
- Web Server & HTTP Endpoints: Located in src/main.rs and the various route modules (e.g., src/routes/admin, src/routes/login, src/routes/subscriptions, etc.). This handles incoming HTTP requests.
- Application Layer (Domain Logic): With modules under src/domain (like new_subscriber, subscriber_email, subscriber_name) that encapsulate business rules.
- Authentication & Session Management: Found in src/authentication and src/session_state.rs for handling login, password validation, and session middleware.
- Idempotency Handling: Modules under src/idempotency (with key management and persistence) to ensure safe, repeatable actions during concurrent operations.
- Email Client: Under src/email_client.rs that abstracts sending emails.
- Background Worker: Specifically, the src/issue_delivery_worker.rs is responsible for asynchronously processing and sending out newsletters.
- Persistence/Data Access Layer: While the interactions with the database aren’t abstracted into a separate “repository” folder, the migrations directory (with multiple SQL scripts) and usage of SQLx (indicated by files in .sqlx) show that database operations are a key part of the system.
- Configuration: The configuration folder (with base.yaml, local.yaml, production.yaml) and src/configuration.rs that drive the environment-specific settings.
- External Services: Postgres (for persistent storage, as shown by the migrations and usage of sqlx) and Redis (initialized by scripts/init_redis.sh) for caching or session management.
- Deployment & CI/CD: Visible from Dockerfile, Docker and GitHub Actions workflows (.github/workflows/) which define the deployment and testing pipelines.

##### Relationships between Components
- The Web Server accepts HTTP requests (from clients, admin users, or subscribers) and routes them to the appropriate handler in the Routes modules.
- Middleware (from the Authentication module) intercepts requests for session handling and secure credential processing.
- Each request typically reaches the Application Layer where the Domain (business logic) is applied, which in turn interacts with the Database (persisted state via SQL migrations) and Redis (for caching/session storage).
- The Email Client is invoked from the business logic when sending newsletters.
- The Issue Delivery Worker processes queued newsletter issues, likely interacting with the Database for status and using the Email Client to dispatch emails.
- Configuration and environment files ensure that various parts (database settings, email client configuration, etc.) are loosely coupled and can adapt between local and production.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Notice how the code differentiates between routing, authentication, domain logic, and I/O (database, email).
- Layered Architecture: Web handling, middleware/authentication, domain processing, and persistent storage are clearly separate.
- Idempotency: There’s explicit handling for idempotent operations to prevent repeated transactions.
- Dependency Injection (Implicit): The way configurations (via YAML files) are loaded and passed through modules encourages loosely coupled components.

- Main components with clear, descriptive labels.
- Be detailed enough to cover authentication, newsletter issue delivery, routing, and configuration management, but keep the core focus on how these pieces interact in the overall architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    EC["External Client"]:::external
    HTTP["HTTP/Web Server"]:::frontend
    ROUTE["Routing Module"]:::frontend
    AUTH["Middleware & Authentication"]:::frontend
    DOMAIN["Domain/Business Logic"]:::backend
    IDEMP["Idempotency Module"]:::backend
    EMAIL["Email Client & Worker"]:::backend
    DB["Postgres Database"]:::database
    REDIS["Redis"]:::database
    CONFIG["Configuration"]:::config
    CICD["CI/CD & Deployment"]:::deployment

    EC -->|"HTTP_Request"| HTTP
    HTTP -->|"Routes"| ROUTE
    ROUTE -->|"auth_check"| AUTH
    AUTH -->|"process_request"| DOMAIN
    DOMAIN -->|"use_idempotency"| IDEMP
    DOMAIN -->|"DB_Query"| DB
    DOMAIN -->|"Cache_Session"| REDIS
    DOMAIN -->|"send_newsletter"| EMAIL

    CONFIG -. "configures" .-> HTTP
    CONFIG -. "configures" .-> AUTH
    CONFIG -. "configures" .-> DOMAIN
    CONFIG -. "configures" .-> EMAIL

    %% Click Events
    click HTTP "https://github.com/lukemathwalker/zero-to-production/blob/main/src/main.rs"
    click HTTP "https://github.com/lukemathwalker/zero-to-production/blob/main/src/startup.rs"
    click ROUTE "https://github.com/lukemathwalker/zero-to-production/tree/main/src/routes"
    click AUTH "https://github.com/lukemathwalker/zero-to-production/tree/main/src/authentication"
    click AUTH "https://github.com/lukemathwalker/zero-to-production/blob/main/src/session_state.rs"
    click DOMAIN "https://github.com/lukemathwalker/zero-to-production/tree/main/src/domain"
    click IDEMP "https://github.com/lukemathwalker/zero-to-production/tree/main/src/idempotency"
    click EMAIL "https://github.com/lukemathwalker/zero-to-production/blob/main/src/email_client.rs"
    click EMAIL "https://github.com/lukemathwalker/zero-to-production/blob/main/src/issue_delivery_worker.rs"
    click DB "https://github.com/lukemathwalker/zero-to-production/tree/main/migrations"
    click DB "https://github.com/lukemathwalker/zero-to-production/blob/main/.sqlx"
    click CONFIG "https://github.com/lukemathwalker/zero-to-production/tree/main/configuration"
    click CONFIG "https://github.com/lukemathwalker/zero-to-production/blob/main/src/configuration.rs"
    click CICD "https://github.com/lukemathwalker/zero-to-production/tree/main/Dockerfile"
    click CICD "https://github.com/lukemathwalker/zero-to-production/tree/main/.github/workflows"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef database fill:#F4A460,stroke:#000,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef config fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef deployment fill:#FFB6C1,stroke:#000,stroke-width:2px;
```
