GOTHAM Enterprise Framework

An enterprise-grade, high-performance web application foundation built on the GOTHAM stack (Go, HTMX 2.x, Templ, sqlx, and PostgreSQL). Designed using Modular / Hexagonal Architecture, GOTHAM delivers type-safe server-side rendering with hypermedia-driven interactivity (HATEOAS), eliminating the overhead of client-side JavaScript single-page application (SPA) frameworks.

---

🏛️ Architectural Philosophy

1. Hypermedia-Driven (HATEOAS): The backend returns HTML fragments over the wire rather than JSON APIs, reducing client-side state synchronization bugs and heavy frontend dependencies.
2. Type-Safe UI Components: Templ components compile directly into native, zero-reflection Go code with zero runtime overhead and compile-time type checking.
3. Hexagonal / Modular Boundaries: Clear separation between Http Handlers, Business Models, Database Repositories, and Templ Views.
4. Lightweight & High Throughput: Relies on Go's standard net/http router, pure SQL queries via sqlx and pgx/v5, and explicit database connection pool tuning.
5. Zero-Dependency Production Deployment: Compiles into a single, stripped binary with embedded static assets (embed.FS).

---

📁 Project Directory Structure

enterprise-framework/
├── cmd/
│   └── api/
│       └── main.go              # Application entry point & dependency wire-up
├── internal/
│   ├── config/
│   │   └── database.go          # Postgres connection pool tuning (sqlx + pgx/v5)
│   ├── dashboard/               # Modular domain slice: Real-time Dashboard (Hexagonal)
│   │   ├── broker.go            # Thread-safe SSE Pub/Sub Event Broker & Worker
│   │   ├── handler.go           # Dashboard UI Page & SSE Stream Handlers
│   │   ├── repository.go        # PostgreSQL raw SQL metrics aggregation
│   │   └── view.templ           # Real-time Templ UI components & SSE targets
│   ├── employee/                # Modular domain slice: Employee Management
│   │   ├── handler.go           # HTTP Handler & HATEOAS response logic
│   │   ├── model.go             # Domain entities & DTOs
│   │   ├── repository.go        # Database access layer using raw SQL
│   │   └── view.templ           # Type-safe Templ UI components & rows
│   ├── middleware/
│   │   └── security.go          # Security Headers, Logger, Panic Recovery
│   ├── router/
│   │   └── router.go            # Native Go Mux routing & middleware chaining
│   └── shared/
│       └── layout.templ         # Base HTML layout shell & navigation (with HTMX SSE extension)
│       └── toast.templ          # Base Toast container (with CSP-compliant)
├── static/
│   └── js/
│       └── app.js               # Application JS core script
│       └── htmx.min.js          # HTMX 2.x core script
├── .air.toml                    # Hot-reload configuration
├── .gitignore                   # Enterprise gitignore (Go, Mac, IDEs)
├── Dockerfile                   # Multi-stage distroless production build (Optional)
├── Makefile                     # Developer tooling & orchestration task runner
└── migration.sql                # Initial database schema setup

---

🛠️ Tech Stack & Dependencies

• Language: Go 1.22+
• Frontend Hypermedia: HTMX 2.x
• Local UI State: Alpine.js 3.x
• Templating Engine: Templ (v0.3.x)
• Database Driver & Abstraction: sqlx + pgx/v5
• Styling: Tailwind CSS
• Live Reloading: Air

---

⚡ Real-time SSE Engine Architecture

The framework implements a high-throughput Server-Sent Events (SSE) architecture for streaming HTML fragments to the client without page refreshes:

[ PostgreSQL ] <--- (Raw SQL Polling) --- [ Background Metrics Worker ]
                                                    |
                                          (HTML Fragment Render)
                                                    |
                                            [ SSE Event Broker ]
                                                    |
                                    +---------------+---------------+
                                    |                               |
                           [ HTTP Connection ]             [ HTTP Connection ]
                           (Client 1 Browser)              (Client 2 Browser)
                                    |                               |
                               [ HTMX SSE ]                    [ HTMX SSE ]

Registered Dashboard Routes

Method	Endpoint	Description	Response Type
GET	/	Main Executive Dashboard Page	Full Layout HTML (text/html)
GET	/api/v1/dashboard/stream	Real-time SSE Stream Channel	Event Stream (text/event-stream)

---

🚀 Getting Started

Prerequisites

• Go 1.22 or higher
• PostgreSQL instance
• templ CLI: go install [github.com/a-h/templ/cmd/templ@latest](https://github.com/a-h/templ/cmd/templ@latest)
• air CLI: go install [github.com/air-verse/air@latest](https://github.com/air-verse/air@latest)

1. Database Setup

Ensure your PostgreSQL service is running, create a database named enterprise_db, and execute the schema:

psql "postgres://postgres:postgres@localhost:5432/enterprise_db?sslmode=disable" -f migration.sql

2. Environment Variables

Set your database connection URL (or rely on the default fallback in internal/config/database.go):

export DATABASE_URL="postgres://postgres:postgres@localhost:5432/enterprise_db?sslmode=disable"
export PORT="8080"

3. Local Development (Hot-Reloading)

Initialize project dependencies and start the Air live-reload development server:

# Download and synchronize Go modules
go mod tidy

# Generate initial Templ components
templ generate

# Start Air watcher
make watch

Navigate to http://localhost:8080 in your browser.

---

🛠️ Developer Commands (Makefile)

Command	Description
make watch	Starts the automatic hot-reload workflow (re-generates Templ files and rebuilds binary on save).
make build	Compiles Templ components and builds a local development binary into ./bin/api.
make build-prod	Performs production build (generates Templ, strips debug symbols -s -w, CGO_ENABLED=0).
make run	Builds and immediately runs the binary.
make clean	Removes generated binaries (/bin, /tmp) and cleans up *_templ.go files.
make install-tools	Installs required CLI development utilities (templ and air).

---

🔒 Enterprise Security & Reliability

The framework integrates key OWASP security controls and resilience mechanisms out-of-the-box:

• Security Headers Middleware: Configures Content-Security-Policy, X-Frame-Options: DENY, X-XSS-Protection, X-Content-Type-Options: nosniff, and Referrer-Policy.
• Panic Recovery Middleware: Intercepts unhandled panics, logs stack traces, and prevents complete server downtime by returning a graceful 500 Internal Server Error fragment.
• Tuned Connection Pooling: Pre-configured database connections with MaxOpenConns(25), MaxIdleConns(10), ConnMaxLifetime(15m), and ConnMaxIdleTime(5m) to avoid connection starvation under high concurrency.

---

🚢 Production Deployment

Option A: Compiled Native Binary

Compile a stripped, standalone statically-linked binary:

make build-prod

Run the binary on your Linux target server:

./bin/gotham-api

Option B: Docker Containerization (Distroless Multi-Stage)

Build an ultra-lightweight (~18MB) Docker container based on gcr.io/distroless/static-debian12:

Dockerfile

# ==========================================
# STAGE 1: Build & Compile Environment
# ==========================================
FROM golang:1.22-alpine AS builder

# Install build dependencies
RUN apk add --no-cache git make

WORKDIR /app

# Install Templ Generator CLI
RUN go install github.com/a-h/templ/cmd/templ@latest

# Copy Go Module Specs
COPY go.mod go.sum ./
RUN go mod download

# Copy Source Code
COPY . .

# Generate Templ HTML components & Build Binary
RUN templ generate
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build \
    -trimpath \
    -ldflags="-s -w" \
    -o /app/gotham-api ./cmd/api

# ==========================================
# STAGE 2: Minimal Distroless Runtime
# ==========================================
FROM gcr.io/distroless/static-debian12:nonroot

WORKDIR /app

# Copy compiled binary from Builder stage
COPY --from=builder /app/gotham-api /app/gotham-api

# Expose HTTP Port
EXPOSE 8080

# Run as Non-Root User for OWASP Hardening
USER nonroot:nonroot

ENTRYPOINT ["/app/gotham-api"]

Run Docker Container

# Build image
docker build -t enterprise/gotham-api:latest .

# Run container
docker run -d \
  -p 8080:8080 \
  -e DATABASE_URL="postgres://user:password@host:5432/dbname?sslmode=require" \
  enterprise/gotham-api:latest

---

📄 License

Distributed under the MIT License.

---