How prasunka/postal-routing-server works
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.