Maize - Modern E-Commerce Platform

A fast, secure e-commerce application built with Go, featuring real-time updates and type-safe templates.

Tech Stack

Backend

• Go 1.25.3 - Core programming language
• Chi Router v5.2.3 - HTTP routing and middleware
• MySQL 9.5.0 - Database with connection pooling
• Stripe API v72.122.0 - Payment processing
• SCS v2.9.0 - Session management with MySQL backend
• Server-Sent Events (SSE) - Real-time server-to-client notifications

Frontend

• Templ v0.3.960 - Type-safe Go templates compiled to Go code
• Datastar (Open Source) - Reactive UI framework with data-binding
• Bootstrap 5.3.3 - CSS framework
• SweetAlert2 - Beautiful alert dialogs
• Stripe.js - Client-side payment processing

Security

• CORS middleware - Environment-based origin control
• Session-based authentication - Secure user sessions
• Panic recovery - Graceful error handling
• Request logging - Comprehensive audit trail

Architecture

The application consists of three services:

1. Web Service (cmd/web) - Main frontend application (port 4000)
2. API Service (cmd/api) - RESTful API backend (port 4001)
3. Invoice Service (cmd/micro/invoice) - Microservice for invoice generation

Features

• ✅ Single & recurring payment processing via Stripe
• ✅ Real-time logout notifications using SSE
• ✅ Admin dashboard for user/order management
• ✅ Virtual terminal for manual charges
• ✅ Password reset functionality
• ✅ Type-safe templates with compile-time validation
• ✅ Database connection pooling (25 connections, 5min lifetime)
• ✅ Comprehensive middleware (panic recovery, logging, CORS)

Prerequisites

• Go 1.25+
• MySQL 9.5+ (or compatible)
• Stripe account (test keys for development)
• Templ CLI (go install github.com/a-h/templ/cmd/templ@latest)

Installation

1. Clone the repository

   git clone https://github.com/carlomunguia/maize.git
   cd maize

2. Install dependencies

   go mod download
   go mod verify

3. Set up MySQL database

   # Create database and user
   mysql -u root -p << EOF
   CREATE DATABASE maize;
   CREATE USER 'maize'@'localhost' IDENTIFIED BY 'maize';
   GRANT ALL PRIVILEGES ON maize.* TO 'maize'@'localhost';
   FLUSH PRIVILEGES;
   EOF

4. Run database migrations

   # Install migrate tool
   brew install golang-migrate
   
   # Run migrations
   migrate -path migrations -database "mysql://maize:maize@tcp(localhost:3306)/maize" up

5. Configure environment variables

   # Create .env file in project root
   cat > .env << EOF
   SECRET_KEY=$(openssl rand -base64 32)
   STRIPE_KEY=pk_test_your_publishable_key
   STRIPE_SECRET=sk_test_your_secret_key
   EOF

Building

Build all services

# Web application
go build -o dist/web ./cmd/web

# API service
go build -o dist/api ./cmd/api

# Invoice microservice
go build -o dist/invoice ./cmd/micro/invoice

Generate templ templates

# Generate Go code from .templ files
templ generate

# Watch mode for development
templ generate --watch

Running

Development mode

# Web service (port 4000)
./dist/web

# API service (port 4001)
./dist/api

# Or run in background with logging
nohup ./dist/web > /tmp/web.log 2>&1 &
nohup ./dist/api > /tmp/api.log 2>&1 &

Configuration flags

./dist/web \
  -port 4000 \
  -env development \
  -dsn "maize:maize@tcp(localhost:3306)/maize?parseTime=true&tls=false" \
  -api "http://localhost:4001" \
  -frontend "http://localhost:4000"

Testing

Run all tests

go test ./...

Static analysis

# Vet code
go vet ./...

# Check for unused code
staticcheck -checks=U1000 ./...

Manual endpoint testing

# Public pages
curl http://localhost:4000/
curl http://localhost:4000/login
curl http://localhost:4000/plans/bronze

# Admin pages (requires authentication)
curl http://localhost:4000/admin/all-users
curl http://localhost:4000/admin/all-sales

Project Structure

.
├── cmd/
│   ├── api/           # API service
│   ├── micro/invoice/ # Invoice microservice
│   └── web/           # Web frontend
│       ├── *.templ    # Templ templates (16 files)
│       ├── handlers.go
│       ├── routes.go
│       └── main.go
├── internal/
│   ├── cards/         # Payment card handling
│   ├── driver/        # Database driver
│   ├── encryption/    # Encryption utilities
│   ├── models/        # Database models
│   ├── urlsigner/     # URL signing for security
│   └── validator/     # Input validation
├── migrations/        # Database migrations (17 files)
├── static/            # CSS, JS, images
└── go.mod

Database Schema

• users - User accounts with authentication
• customers - Customer information for orders
• maize - Products catalog (2 seeded products)
• orders - Order tracking
• transactions - Payment transactions
• transaction_statuses - Payment status tracking
• statuses - Order status definitions
• tokens - Password reset tokens
• sessions - User session data

API Endpoints

Web Service (Port 4000)

• GET / - Home page
• GET /login - Login page
• POST /login - Authenticate user
• GET /logout - Logout (broadcasts SSE event)
• GET /maize/{id} - Product purchase page
• GET /plans/bronze - Subscription plan page
• GET /admin/* - Admin dashboard (authenticated)
• GET /sse - Server-Sent Events stream
• POST /internal/broadcast - Trigger SSE broadcasts

API Service (Port 4001)

• POST /api/payment-intent - Create Stripe payment intent
• POST /api/authenticate - User authentication
• POST /api/admin/all-users - List all users
• POST /api/admin/all-sales - List all sales
• POST /api/admin/refund - Process refund
• POST /api/forgot-password - Send password reset email
• POST /api/reset-password - Reset user password

Development Workflow

1. Make changes to .templ files
2. Generate Go code: templ generate
3. Build: go build -o dist/web ./cmd/web
4. Restart server: pkill web && ./dist/web
5. Test endpoints: curl http://localhost:4000/

Deployment

Production build

# Build with optimizations
CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o dist/web ./cmd/web
CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o dist/api ./cmd/api

Environment configuration

• Set STRIPE_KEY and STRIPE_SECRET with production keys
• Use strong SECRET_KEY (32+ bytes)
• Configure MySQL with SSL in production
• Set proper CORS origins in production mode
• Use reverse proxy (nginx/caddy) for HTTPS

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Run go vet and staticcheck
5. Submit a pull request

License

See LICENSE file for details.

Acknowledgments

• Chi Router - HTTP routing
• Templ - Type-safe templates
• Datastar - Reactive UI framework
• Stripe - Payment processing
• SCS - Session management