1Engage Multitenant Backend Codebase Guide

This guide is a companion for understanding the Go features, patterns, and flows used throughout the 1Engage multitenant backend. It is designed to help developers get up to speed quickly for code reviews, debugging, and contributing new features. Each page focuses on a specific concept area with real code references, explanations, and diagrams.

Technology Stack

Category	Technology	Usage
Language	Go 1.25.5	All microservices
HTTP Router	Chi	Lightweight, idiomatic Go HTTP router
ORM / Database	GORM + PostgreSQL / CockroachDB	Data access layer, migrations, multi-tenant schemas
Message Broker	Kafka segmentio/kafka-go	Async event processing, webhook ingestion
Cache / Pub-Sub	Redis	Caching, rate limiting, session storage
Authentication	JWT (golang-jwt)	Access & refresh tokens, RBAC claims
Observability	OpenTelemetry	Distributed tracing across services
Object Storage	AWS S3	Media uploads, broadcast assets
API Docs	Huma (OpenAPI)	Auto-generated OpenAPI specs

Microservices Overview

Service	Port	Purpose	Database
gateway-service	8080	API Gateway — reverse proxy, JWT validation, tenant ID injection	—
auth-service	8081	Authentication, user management, roles & permissions	PostgreSQL
admin-service	8082	Tenant management, Meta / WhatsApp integration setup	PostgreSQL
broadcast-service	8083	WhatsApp broadcast campaigns, recipients, templates	PostgreSQL
broadcast-worker	N/A	Kafka consumer for async message processing (no HTTP server)	PostgreSQL
meta-webhook-service	8085	Receives Meta platform webhooks, publishes events to Kafka	—

Project Structure

1eng-multitenant-backend/
├── apps/                       # 6 microservices
│   ├── gateway-service/        # API Gateway (reverse proxy)
│   ├── auth-service/           # Authentication & RBAC
│   ├── admin-service/          # Tenant & Meta management
│   ├── broadcast-service/      # WhatsApp broadcasts
│   ├── meta-webhook-service/   # Meta webhook receiver
│   └── chatbot-service/        # (placeholder)
├── pkg/                        # Shared packages
│   ├── auth/                   # JWT, context helpers, middleware
│   ├── crypto/                 # AES-256 encryption
│   ├── eventbus/               # Event envelope & Kafka
│   ├── middleware/              # CORS, request ID, tenant
│   ├── shared/                 # HTTP, helpers, mail, redis, validator
│   ├── tracing/                # OpenTelemetry
│   └── version/                # Build-time version info
├── deploy/                     # Docker Compose, K8s manifests
├── tools/                      # Service scaffolding generator
├── Makefile                    # Central command hub
└── Tiltfile                    # Local K8s dev with live reload

Documentation Pages

Each page covers a specific concept area. Start wherever is most relevant to your task.

Go Concurrency Patterns

Mutex, WaitGroup, Channels, Goroutines, and Select — how the codebase handles parallelism, synchronization, and concurrent data access.

Context & Interfaces

Context propagation across layers, interface patterns for testability, and dependency injection strategies used throughout the services.

Error Handling

Custom error types, error wrapping, PermanentError for non-retryable failures, and Meta API error parsing.

Go Language Features

Generics, struct embedding, reflection, defer patterns, closures, type assertions, and other Go-specific techniques used in the codebase.

Architecture & Patterns

Project structure, layered architecture (handler → service → repository), API Gateway pattern, and multitenancy implementation.

Authentication & Authorization

JWT token lifecycle, hybrid authentication middleware, role-based access control (RBAC), and refresh token rotation.

Event-Driven Architecture

Kafka producers & consumers, idempotency keys, retry with dead-letter queues, worker pool patterns, and rate limiting.

Request Flow Traces

Complete request lifecycle walkthroughs — from HTTP ingress through the gateway, service layers, database, and back to the client.

Template & Broadcasting

WhatsApp and email templates, high-volume broadcast campaigns with chunking, worker pools, rate limiting, and best practices for millions of messages.

Major Dependencies

Key packages from go.mod

Package	Purpose
`github.com/go-chi/chi/v5`	HTTP router and middleware
`gorm.io/gorm`	ORM for PostgreSQL / CockroachDB
`gorm.io/driver/postgres`	GORM PostgreSQL driver
`github.com/segmentio/kafka-go`	Kafka producer & consumer
`github.com/redis/go-redis/v9`	Redis client
`github.com/golang-jwt/jwt/v5`	JWT creation & validation
`go.opentelemetry.io/otel`	Distributed tracing (OpenTelemetry)
`github.com/aws/aws-sdk-go-v2`	AWS S3 for object storage
`github.com/danielgtaylor/huma/v2`	OpenAPI spec generation & validation
`github.com/rs/zerolog`	Structured JSON logging
`golang.org/x/crypto`	bcrypt password hashing
`github.com/google/uuid`	UUID generation

1Engage Multitenant Backend — Codebase Guide — Built for developers who need to understand the codebase quickly.