Backend Overview

Backend Overview

The Merq Backend is a high-performance REST API built in Go (Golang), serving as the central nervous system for the entire platform. It handles all business logic, data persistence, and communication with the web dashboard and mobile application.

Built on a foundation of Gin for routing, GORM for database interaction, and a strict clean architecture, the backend is designed for scalability, testability, and maintainability.

Go Version

1.24+

Primary Framework

Gin

Database

PostgreSQL 14+

Core Principle

Handler -> Service -> Repository

Core Features & Scope

The backend’s responsibilities include:

• Authentication & RBAC: Manages user login, JWT generation, and granular role-based access control for all API endpoints.
• Workspace Scoping: Enforces strict data isolation between different client workspaces. Every database query is scoped to the authenticated user’s workspace.
• CRUD Operations: Provides a complete set of APIs for managing the core domain entities: Principals, Projects, Teams, Outlets, Visits, and Submissions.
• Data Persistence: Interacts with a PostgreSQL database via GORM for all data storage and retrieval.
• Caching: Utilizes Redis for caching frequently accessed data, reducing database load and improving response times.
• Full-Text Search: Integrates with Typesense to provide powerful and fast search capabilities across various entities.
• Push Notifications: Manages and sends push notifications to mobile devices via Firebase Cloud Messaging (FCM).
• File Storage: Handles uploads and serves files (e.g., photo evidence from visits) using an S3-compatible object storage solution like DigitalOcean Spaces.
• Background Jobs: Manages long-running data import and export tasks asynchronously via import_jobs and export_jobs.
• Email Notifications: Sends transactional emails using a failover chain of providers: Resend → Plunk → Mailersend.
• HR Management: Tracks employee schedules, compensation, leave entitlements, and leave requests.
• Reimbursements: Manages expense reimbursement claims with a full approval workflow.
• Sales Orders: Records and tracks sales orders submitted by field agents.
• Form Builder: Allows workspace admins to define custom dynamic forms for outlet visit submissions.
• Dashboard & Analytics: Provides aggregated metrics and KPIs for the admin dashboard.
• Currency & Locations: Maintains reference data for supported currencies and geographic locations.
• Workspace Settings: Allows per-workspace configuration of operating schedules and other master settings.

Handler Modules

The following handler modules exist in internal/handler/:

Module	File	Description
Auth	auth_handler.go	Login, logout, password reset, token refresh
Profile	profile_handler.go	Current user profile read/update
User	user_handler.go	User CRUD and management
RBAC	rbac_handler.go	Roles and permission management
Workspace	workspace_handler.go	Workspace CRUD
Workspace Settings	workspace_setting_handler.go	Operating schedules and master settings
Principal	principal_handler.go	Principal (brand) CRUD
Project	project_handler.go	Project CRUD and team assignments
Team	team_handler.go	Team CRUD and member management
Outlet	— (via outlet domain)	Outlet CRUD
Outlet Visit	outlet_visit_handler.go	Visit check-in/check-out
Submission	submission_handler.go	Visit submission data
Product	product_handler.go	Product CRUD
Dashboard	dashboard_handler.go	Aggregated metrics and KPIs
Notification	notification_handler.go	In-app notifications
Employee HR	employee_hr_handler.go	Schedules, compensation, leave
Reimbursement	reimbursement_handler.go	Expense claims and approval
Sales Order	sales_order_handler.go	Sales order management
Form Builder	form_builder_handler.go	Dynamic form definitions
Location	location_handler.go	Geographic location reference data
Currency	currency_handler.go	Currency reference data
Export	export_handler.go + export_job_handler.go	Async data export
Import	import_job_handler.go	Async data import
Health	health_handler.go	Health check endpoint

Key Technical Decisions

The technology stack and architecture were chosen to meet specific platform goals:

• Go (Golang): Selected for its high performance, low memory footprint, and excellent support for concurrency, which is crucial for handling many simultaneous requests from mobile clients.
• Gin Framework: A lightweight and fast HTTP web framework that provides the necessary tools for building a REST API without unnecessary bloat.
• GORM (Go-ORM): Simplifies database interactions by mapping Go structs to database tables, while still allowing for raw SQL when performance is critical.
• Clean Architecture (Handler → Service → Repository): This strict separation of concerns makes the codebase easier to understand, test, and maintain.
  • Handlers: Responsible only for HTTP request/response handling.
  • Services: Contain all business logic and orchestration.
  • Repositories: Manage all data access and database queries.
• PostgreSQL: A robust, open-source relational database known for its reliability and data integrity.
• Redis: Used as a high-speed cache to reduce latency on common read operations.
• Typesense: Chosen for its simplicity and performance as a dedicated search engine, offloading complex search queries from the primary database.