# abufarhad/go-email-client architecture

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

- Interactive diagram: https://gitdiagram.com/abufarhad/go-email-client
- Repository: https://github.com/abufarhad/go-email-client

## Overview

1. **Architecture style**
   - This repo follows a clean-architecture split: **domain logic** in the center, **adapters/interfaces** around it, and **infrastructure** concerns isolated.
   - The code is organized so the business rules for email operations do not depend on the terminal UI, web UI, file storage, or IMAP/SMTP specifics.

2. **Entry points / runtime modes**
   - There are two distinct ways to run the product:
     - `cmd/main.go` for the **terminal/TUI app**
     - `web/main.go` for the **browser-based terminal** experience
   - The web mode serves `web/static/index.html` and acts as a bridge between a browser terminal frontend and the Go process.

3. **Core domain**
   - `internal/domain/model/email.go` contains the central email entity used throughout the app.
   - `internal/domain/service/email_service.go` is the business layer for actions like listing inbox mail, composing/sending, and deleting.
   - Tests and mocks in `internal/domain/service` indicate this layer is designed to be unit-tested independently of storage and UI.

4. **Application/service boundary**
   - `internal/interface/controller/handler.go` is the application-facing orchestration layer.
   - It sits between the UI and the domain service, translating user actions into service calls and formatting results back for presentation.
   - This is the main seam where UI-specific concerns are kept out of business logic.

5. **User interface layer**
   - `internal/interface/ui/app.go` contains the terminal UI built with `tview`.
   - The UI is form-driven and supports navigation/back behavior, inbox views, compose screens, and delete actions.
   - In web mode, the browser page uses a terminal-emulation front end, while the Go backend remains the same application logic.

6. **Persistence adapters**
   - `internal/interface/persistence/file_store.go` provides a **local file-backed mailbox**, with `emails.json` acting as the sample datastore.
   - `internal/interface/persistence/imap_smtp_store.go` provides the **real email backend**, using IMAP for reading and SMTP for sending.
   - The README indicates the file store is also the deletion-capable path, while the real backend is for live mailbox access and sending.

7. **Data flow**
   - Typical flow is: **user input in UI → handler → email service → persistence adapter → response back to UI**.
   - For inbox reads, the service pulls from either local JSON or IMAP depending on configuration.
   - For sending, the service routes through SMTP when real email mode is enabled.
   - For delete, the file store path is supported; the real provider path is more limited by mail-server semantics.

8. **Configuration and mode selection**
   - `.env.example` and README show the main runtime switch: `USE_REAL_EMAIL`.
   - SMTP/IMAP host, port, user, password, and fetch count are configured via environment variables.
   - This config determines whether the app behaves like a simulated local email client or connects to a real provider such as Gmail/Outlook.

9. **Cross-cutting infrastructure**
   - `internal/infra/logger/logger.go` centralizes logging, and runtime logs are written to `logs.txt`.
   - The README notes logs reset on each run, which makes logging part of the app’s operational behavior rather than a persistent audit store.

10. **Shared helpers and support files**
   - `utils/utils.go` likely holds small reusable helpers that do not belong to the domain or adapters.
   - `Makefile`, `Dockerfile`, and `go.mod` define build/run packaging for local development and containerized execution.
   - `email_service_test.go` and persistence tests show the repo has coverage around the domain and storage adapters, which reinforces the layered design.

11. **External dependencies and boundaries**
   - The real backend depends on external email infrastructure: **IMAP and SMTP servers** exposed by providers like Gmail.
   - The browser mode depends on a **web terminal transport** in `web/main.go` plus static browser assets.
   - The terminal mode depends on the Go TUI stack, specifically `tview`, but the architectural boundary remains the same across runtimes.

12. **What to draw in an architecture diagram**
   - Show two front doors: **CLI/TUI** and **Web terminal**.
   - Both should converge on the **controller/handler**, then the **email service**, then one of two **persistence adapters**.
   - Place `domain` at the center, `logger` as a cross-cutting side concern, and mark `emails.json`/`logs.txt` as local runtime artifacts.

Main entry points: [`internal/domain/service/email_service.go`](https://github.com/abufarhad/go-email-client/blob/main/internal/domain/service/email_service.go) (Email service), [`internal/infra/logger/logger.go`](https://github.com/abufarhad/go-email-client/blob/main/internal/infra/logger/logger.go) (Logger), [`web/main.go`](https://github.com/abufarhad/go-email-client/blob/main/web/main.go) (Web app), [`internal/interface/controller/handler.go`](https://github.com/abufarhad/go-email-client/blob/main/internal/interface/controller/handler.go) (Handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_runtimes["Runtimes"]
  node_node_cmd_main["CLI app<br/>entrypoint<br/>[main.go]"]
  node_node_web_main["Web app<br/>entrypoint<br/>[main.go]"]
end

subgraph group_grp_interface["Interface layer"]
  node_node_handler["Handler<br/>orchestrator<br/>[handler.go]"]
  node_node_tui_app["TUI app<br/>tview UI<br/>[app.go]"]
  node_node_file_store[("File store<br/>mailbox adapter<br/>[file_store.go]")]
  node_node_imap_smtp[("IMAP/SMTP<br/>email adapter<br/>[imap_smtp_store.go]")]
end

subgraph group_grp_domain["Domain"]
  node_node_email_model["Email<br/>domain model<br/>[email.go]"]
  node_node_email_service["Email service<br/>domain service<br/>[email_service.go]"]
end

subgraph group_grp_infra["Infrastructure"]
  node_node_logger["Logger<br/>[logger.go]"]
  node_node_utils["Helpers<br/>shared utils<br/>[utils.go]"]
end

subgraph group_grp_artifacts["Artifacts"]
  node_node_web_index["Browser UI<br/>static asset<br/>[index.html]"]
  node_node_emails_json["emails.json<br/>local data<br/>[emails.json]"]
  node_node_logs_txt["logs.txt<br/>runtime log<br/>[logs.txt]"]
  node_node_env["Config<br/>[.env.example]"]
end

node_node_external_mail(("Mail provider<br/>external IMAP/SMTP"))

node_node_cmd_main -->|"starts"| node_node_tui_app
node_node_web_main -->|"serves"| node_node_web_index
node_node_web_main -->|"runs"| node_node_handler
node_node_tui_app -->|"calls"| node_node_handler
node_node_handler -->|"orchestrates"| node_node_email_service
node_node_email_service -->|"uses"| node_node_email_model
node_node_email_service -->|"reads/writes"| node_node_file_store
node_node_email_service -->|"reads/sends"| node_node_imap_smtp
node_node_file_store -->|"stores"| node_node_emails_json
node_node_imap_smtp -->|"connects to"| node_node_external_mail
node_node_handler -->|"logs"| node_node_logger
node_node_email_service -->|"logs"| node_node_logger
node_node_web_main -->|"logs"| node_node_logger
node_node_cmd_main -->|"logs"| node_node_logger
node_node_email_service -->|"uses"| node_node_utils
node_node_cmd_main -->|"reads config"| node_node_env
node_node_web_main -->|"reads config"| node_node_env
node_node_logger -->|"writes"| node_node_logs_txt

click node_node_cmd_main "https://github.com/abufarhad/go-email-client/blob/main/cmd/main.go"
click node_node_web_main "https://github.com/abufarhad/go-email-client/blob/main/web/main.go"
click node_node_web_index "https://github.com/abufarhad/go-email-client/blob/main/web/static/index.html"
click node_node_handler "https://github.com/abufarhad/go-email-client/blob/main/internal/interface/controller/handler.go"
click node_node_tui_app "https://github.com/abufarhad/go-email-client/blob/main/internal/interface/ui/app.go"
click node_node_email_model "https://github.com/abufarhad/go-email-client/blob/main/internal/domain/model/email.go"
click node_node_email_service "https://github.com/abufarhad/go-email-client/blob/main/internal/domain/service/email_service.go"
click node_node_file_store "https://github.com/abufarhad/go-email-client/blob/main/internal/interface/persistence/file_store.go"
click node_node_imap_smtp "https://github.com/abufarhad/go-email-client/blob/main/internal/interface/persistence/imap_smtp_store.go"
click node_node_logger "https://github.com/abufarhad/go-email-client/blob/main/internal/infra/logger/logger.go"
click node_node_utils "https://github.com/abufarhad/go-email-client/blob/main/utils/utils.go"
click node_node_emails_json "https://github.com/abufarhad/go-email-client/blob/main/emails.json"
click node_node_logs_txt "https://github.com/abufarhad/go-email-client/blob/main/logs.txt"
click node_node_env "https://github.com/abufarhad/go-email-client/blob/main/.env.example"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_cmd_main,node_node_web_main toneBlue
class node_node_handler,node_node_tui_app,node_node_file_store,node_node_imap_smtp toneAmber
class node_node_email_model,node_node_email_service toneMint
class node_node_logger,node_node_utils toneRose
class node_node_web_index,node_node_emails_json,node_node_logs_txt,node_node_env toneIndigo
class node_node_external_mail toneNeutral
```

## Components

### Runtimes

Two entry points into the same application core.

- [CLI app](https://github.com/abufarhad/go-email-client/blob/main/cmd/main.go): entrypoint · Terminal/TUI runtime entry point. · `cmd/main.go`
- [Web app](https://github.com/abufarhad/go-email-client/blob/main/web/main.go): entrypoint · Browser-terminal runtime entry point. · `web/main.go`

### Interface layer

UI and request orchestration around the domain.

- [Handler](https://github.com/abufarhad/go-email-client/blob/main/internal/interface/controller/handler.go): orchestrator · Application-facing seam between UI and domain. · `internal/interface/controller/handler.go`
- [TUI app](https://github.com/abufarhad/go-email-client/blob/main/internal/interface/ui/app.go): tview UI · Terminal interface for inbox, compose, delete, and navigation. · `internal/interface/ui/app.go`
- [File store](https://github.com/abufarhad/go-email-client/blob/main/internal/interface/persistence/file_store.go): mailbox adapter · Local JSON-backed mailbox and deletion-capable storage path. · `internal/interface/persistence/file_store.go`
- [IMAP/SMTP](https://github.com/abufarhad/go-email-client/blob/main/internal/interface/persistence/imap_smtp_store.go): email adapter · Live mailbox read and send adapter for external providers. · `internal/interface/persistence/imap_smtp_store.go`

### Domain

Core email model and business rules.

- [Email](https://github.com/abufarhad/go-email-client/blob/main/internal/domain/model/email.go): domain model · Central email entity used across the app. · `internal/domain/model/email.go`
- [Email service](https://github.com/abufarhad/go-email-client/blob/main/internal/domain/service/email_service.go): domain service · Business logic for listing, sending, and deleting mail. · `internal/domain/service/email_service.go`

### Infrastructure

Cross-cutting and storage backends.

- [Logger](https://github.com/abufarhad/go-email-client/blob/main/internal/infra/logger/logger.go): infra logger · Central logging for runtime behavior. · `internal/infra/logger/logger.go`
- [Helpers](https://github.com/abufarhad/go-email-client/blob/main/utils/utils.go): shared utils · Small reusable helpers outside domain and adapters. · `utils/utils.go`

### Artifacts

Local runtime files and bundled frontend assets.

- [Browser UI](https://github.com/abufarhad/go-email-client/blob/main/web/static/index.html): static asset · Static page served by the web runtime. · `web/static/index.html`
- [emails.json](https://github.com/abufarhad/go-email-client/blob/main/emails.json): local data · Sample local mailbox datastore. · `emails.json`
- [logs.txt](https://github.com/abufarhad/go-email-client/blob/main/logs.txt): runtime log · Log output reset on each run. · `logs.txt`
- [Config](https://github.com/abufarhad/go-email-client/blob/main/.env.example): runtime config · Environment-driven mode and provider settings. · `.env.example`

### Other components

- **Mail provider**: external IMAP/SMTP · External email infrastructure used in real-email mode.

## Connections

- CLI app → TUI app: starts · CLI runtime boots the terminal UI.
- Web app → Browser UI: serves · Web runtime serves the browser frontend.
- Web app → Handler: runs · Web runtime connects the browser terminal to the application handler.
- TUI app → Handler: calls · UI actions are translated into controller operations.
- Handler → Email service: orchestrates · Handler invokes domain use cases.
- Email service → Email: uses · Business logic centers on the email entity.
- Email service → File store: reads/writes · Local mode persists and deletes mail through the file-backed store.
- Email service → IMAP/SMTP: reads/sends · Real-email mode lists and sends through the live email adapter.
- File store → emails.json: stores · JSON mailbox file is the local persistence target.
- IMAP/SMTP → Mail provider: connects to · Adapter talks to external IMAP and SMTP servers.
- Handler → Logger: logs · Application flow emits operational logs.
- Email service → Logger: logs · Service layer participates in runtime logging.
- Web app → Logger: logs · Web runtime writes operational logs.
- CLI app → Logger: logs · CLI runtime writes operational logs.
- Email service → Helpers: uses · Shared helpers support application logic.
- CLI app → Config: reads config · Runtime mode and provider settings are environment-driven.
- Web app → Config: reads config · Web runtime uses the same mode and provider settings.
- Logger → logs.txt: writes · Logs are persisted to the runtime log file.
