How abufarhad/go-email-client works
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: email_service.go Email service · logger.go Logger · main.go Web app · handler.go Handler
Components 15
Runtimes
Two entry points into the same application core.
Interface layer
UI and request orchestration around the domain.
- Handler · Application-facing seam between UI and domain.
internal/interface/controller/handler.go - TUI app · Terminal interface for inbox, compose, delete, and navigation.
internal/interface/ui/app.go - File store · Local JSON-backed mailbox and deletion-capable storage path.
internal/interface/persistence/file_store.go - IMAP/SMTP · Live mailbox read and send adapter for external providers.
internal/interface/persistence/imap_smtp_store.go
Domain
Core email model and business rules.
- Email · Central email entity used across the app.
internal/domain/model/email.go - Email service · Business logic for listing, sending, and deleting mail.
internal/domain/service/email_service.go
Infrastructure
Cross-cutting and storage backends.
Artifacts
Local runtime files and bundled frontend assets.
- Browser UI · Static page served by the web runtime.
web/static/index.html - emails.json · Sample local mailbox datastore.
emails.json - logs.txt · Log output reset on each run.
logs.txt - Config · Environment-driven mode and provider settings.
.env.example
Other components
- Mail provider · External email infrastructure used in real-email mode.
Connections 18
- 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.