# prasunka/postal-routing-server architecture

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

- Interactive diagram: https://gitdiagram.com/prasunka/postal-routing-server
- Repository: https://github.com/prasunka/postal-routing-server

## Overview

##### Project type and purpose
- This is a standalone backend API server written in Go.
- Its sole responsibility is to expose HTTP endpoints that create and manage email-forwarding routes on a Postal SMTP server, and to persist routing data in a MySQL database.

##### File structure
- cmd/web/
- main.go: sets up the HTTP server and router
- handlers.go: defines HTTP handlers for your API endpoints
- pkg/models/
- models.go: defines core domain models or interfaces
- mysql/
- endpoints.go: model methods to CRUD “endpoints” table
- routes.go: model methods to CRUD “routes” table
- Dockerfile, go.mod/sum: build, dependency management

##### Key architecture insights from README
- Single‐purpose API: no UI or external frontends.
- Data storage: MySQL (via pkg/models/mysql).
- External integration: Postal SMTP service (addressable over network).

##### Main components
a. API Server
- Go http.Server + router (in cmd/web/main.go)
- Handlers (cmd/web/handlers.go)
b. Business Logic / Models Layer
- pkg/models (interfaces, validations)
- pkg/models/mysql (concrete implementations accessing the database)
c. Database
- MySQL instance (endpoints, routes tables)
d. External Service
- Postal SMTP server (remote service for which routes are configured via API or direct database writes)

##### Relationships and interactions
1. Client (e.g., curl, Postman, other services) issues HTTP request →
2. API Server (cmd/web) routes request → appropriate Handler →
3. Handler invokes Models Layer (pkg/models) →
4. Models/mysql executes SQL queries against MySQL →
5. Database returns data → Models transform into domain objects →
6. Handler optionally calls Postal’s Admin API (or writes directly to Postal’s DB) to configure SMTP routing →
7. Handler returns HTTP response to Client

##### Architectural patterns / design principles
- Layered Architecture: clear separation of transport (HTTP), business logic, data access.
- Dependency Injection: handlers depend on interfaces in pkg/models.
- Single Responsibility: each package has one clear role.

##### Technologies / frameworks
- Go’s net/http (standard library) for HTTP server
- Go modules (go.mod)
- MySQL driver/library (imported in pkg/models/mysql)
- Docker (via Dockerfile)

1. Client → API Server (HTTP request)
2. API Server → Models Layer (method call)
3. Models Layer → MySQL Adapters → MySQL (SQL query)
4. API Server → Postal SMTP Server (configuration API call)
5. API Server → Client (HTTP response)
- Optionally, group layers vertically: top = client, then API, then models, then database & external.

##### Final advice
- Keep it simple but complete—reflect the layering and data flow through your cmd/web and pkg/models folders.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Entities
    Client["Client (curl/Postman)"]:::external

    %% API Server Layer
    subgraph "API Server (cmd/web)" 
        direction TB
        Router["Router"]:::transport
        Handlers["Handlers"]:::transport
    end

    %% Business Logic Layer
    subgraph "Models Layer (pkg/models)"
        direction TB
        DomainModels["Domain Models & Interfaces"]:::business
    end

    %% Data Access Layer
    subgraph "MySQL Adapters (pkg/models/mysql)"
        direction TB
        Endpoints["endpoints.go"]:::dataaccess
        Routes["routes.go"]:::dataaccess
    end

    %% Persistence and External
    MySQLDB["MySQL Database"]:::persistence
    PostalSMTP["Postal SMTP Server"]:::external

    %% Project Configuration Files
    subgraph "Project Config & Docs"
        direction TB
        DockerfileNode["Dockerfile"]:::config
        GoMod["go.mod"]:::config
        GoSum["go.sum"]:::config
        Readme["README.md"]:::config
    end

    %% Data Flow
    Client -->|"HTTP Request"| Router
    Router -->|"route to handler"| Handlers
    Handlers -->|"invoke business logic"| DomainModels
    DomainModels -->|"implements via endpoints.go"| Endpoints
    DomainModels -->|"implements via routes.go"| Routes
    Endpoints -->|"SQL SELECT/INSERT"| MySQLDB
    Routes -->|"SQL SELECT/INSERT"| MySQLDB
    Handlers -->|"HTTP POST /configure-route"| PostalSMTP
    Handlers -->|"HTTP Response"| Client

    %% Click Events
    click Router "https://github.com/prasunka/postal-routing-server/blob/master/cmd/web/main.go"
    click Handlers "https://github.com/prasunka/postal-routing-server/blob/master/cmd/web/handlers.go"
    click DomainModels "https://github.com/prasunka/postal-routing-server/blob/master/pkg/models/models.go"
    click Endpoints "https://github.com/prasunka/postal-routing-server/blob/master/pkg/models/mysql/endpoints.go"
    click Routes "https://github.com/prasunka/postal-routing-server/blob/master/pkg/models/mysql/routes.go"
    click DockerfileNode "https://github.com/prasunka/postal-routing-server/tree/master/Dockerfile"
    click GoMod "https://github.com/prasunka/postal-routing-server/blob/master/go.mod"
    click GoSum "https://github.com/prasunka/postal-routing-server/blob/master/go.sum"
    click Readme "https://github.com/prasunka/postal-routing-server/blob/master/README.md"

    %% Styles
    classDef transport fill:#a8ddb5,stroke:#238b45,color:#000
    classDef business fill:#9ecae1,stroke:#08519c,color:#000
    classDef dataaccess fill:#c7e9c0,stroke:#238b45,color:#000
    classDef persistence fill:#fdae6b,stroke:#e6550d,color:#000
    classDef external fill:#df65b0,stroke:#7a0177,color:#000
    classDef config fill:#f0f0f0,stroke:#636363,color:#000
```
