ref-app

README

ref-app

Reference Application Template - A production-ready Go web application foundation with complete authentication, security, and internationalization. Clone this template to quickly start new projects with a solid foundation.

---

🎯 What is ref-app?

ref-app is a template, not a framework. It's a complete, working web application that you clone and customize for your specific needs. Unlike starting from scratch, you get:

• ✅ Complete authentication system - Login, registration, 2FA, password reset
• ✅ Admin panel - User management, role-based access control
• ✅ Internationalization - 4 languages (German default: DE, EN, NL, AF)
• ✅ Security - CSRF protection, rate limiting, encryption
• ✅ Modern UI - htmx + Alpine.js + Tailwind CSS
• ✅ Production-ready - Logging, migrations, health checks

Don't rebuild what already works. Clone ref-app, build your features on top.

---

🚀 Quick Start: Clone a New Project

Step 1: Clone ref-app for your project

cd /path/to/ref-app/clone
./clone_ref_app.sh myproject "My awesome project description"

Step 2: Set up your new project

cd myproject
cp .env.example .env
# Edit .env - set database credentials, generate encryption keys

createdb myproject
make migrate-up

go build -o bin/myproject cmd/api/main.go
./bin/myproject

Step 3: Start building features

The foundation is ready - now build your project-specific features!

---

📚 Documentation

• Cloning Guide - How to create new projects from ref-app
• Quick Reference - TL;DR cloning instructions
• CLAUDE.md - AI assistant context
• CONTRIBUTING.md - Development guidelines

---

✨ What's Included

Authentication & Security

• User Management

  • Registration and login
  • Email verification workflow
  • Password reset with tokens
  • Secure password hashing (bcrypt cost 12)

• Two-Factor Authentication (2FA)

  • TOTP-based (works with Google Authenticator, Authy, etc.)
  • QR code setup
  • Recovery codes
  • Mandatory 2FA enforcement

• Session Management

  • Secure session cookies
  • Session cleanup (automatic)
  • Multi-device support
  • Activity logging

• Security Features

  • CSRF protection
  • Rate limiting (configurable per endpoint)
  • AES-256-GCM encryption for sensitive data
  • Secure headers (CSP, X-Frame-Options, etc.)
  • Activity audit logging

Admin Panel

• User Management

  • List, search, filter users
  • Create, edit, deactivate users
  • Role management (super_admin, admin, moderator, customer)
  • Session monitoring
  • View user activity history

• System Configuration

  • Email server settings (SMTP)
  • Site branding (name, colors, logo)
  • Feature flags
  • Health monitoring

Internationalization (i18n)

• 4 Languages Supported

  • 🇩🇪 German (default)
  • 🇬🇧 English
  • 🇳🇱 Dutch
  • 🇿🇦 Afrikaans

• 544 translation keys per language

• Language switcher component

• User-specific language preferences

• URL/cookie/database preference support

Developer Experience

• Database

  • PostgreSQL with migrations (golang-migrate)
  • Connection pooling
  • Prepared statements
  • GORM-free (uses database/sql)

• Testing

  • Unit tests
  • Integration tests with testcontainers
  • Handler tests
  • Code coverage reporting

• Development Tools

  • Hot reload with air
  • Makefile for common tasks
  • Database migrations up/down
  • Seed data scripts

• CI/CD

  • GitHub Actions workflow
  • Automated testing
  • Security scanning (gosec, govulncheck)
  • Multi-platform builds

Tech Stack

• Backend: Go 1.21+ with PostgreSQL 15+
• Frontend: HTML templates + htmx 2.0 + Alpine.js 3.14 + Tailwind CSS
• Auth: Session-based (not JWT)
• Email: SMTP with templates
• Logging: Structured logging with zerolog

---

🛠️ Development

Prerequisites

• Go 1.21 or higher
• PostgreSQL 15 or higher
• make (optional, for Makefile commands)

Local Development

# Clone the repository (for development on ref-app itself)
git clone https://github.com/namaqua/ref-app.git
cd ref-app

# Set up environment
cp .env.example .env
# Edit .env with your settings

# Create database
createdb ref_app
make migrate-up

# Run with hot reload
air

# Or build and run
go build -o bin/ref-app cmd/api/main.go
./bin/ref-app

Running Tests

# All tests
go test ./...

# With coverage
go test -cover ./...

# Specific package
go test ./internal/auth -v

# Integration tests (requires Docker)
go test -tags=integration ./tests/integration/...

Database Migrations

# Create new migration
make migrate-create name=add_users_table

# Run migrations
make migrate-up

# Rollback
make migrate-down

# Check status
make migrate-status

---

🎨 UI/UX Design

ref-app follows modern web design principles:

• Clean & Minimal - Focused, uncluttered interfaces
• Responsive - Works on mobile, tablet, desktop
• Accessible - WCAG 2.1 AA compliant
• Modern Stack - htmx for interactivity, Alpine.js for reactivity, Tailwind for styling

Design System: See notes/engine-ui.md for colors, typography, and component guidelines

---

📁 Project Structure

ref-app/
├── cmd/
│   └── api/              # Application entry point
├── internal/             # Private application code
│   ├── auth/            # Authentication & authorization
│   ├── twofa/           # Two-factor authentication
│   ├── admin/           # Admin panel handlers
│   ├── customer/        # Customer dashboard
│   ├── settings/        # User settings
│   ├── i18n/            # Internationalization
│   ├── templates/       # Template system
│   ├── email/           # Email service
│   ├── encryption/      # Data encryption
│   ├── ratelimit/       # Rate limiting
│   ├── logging/         # Structured logging
│   ├── audit/           # Activity auditing
│   └── middleware/      # HTTP middleware
├── migrations/          # Database migrations
├── internal/templates/  # HTML templates
├── static/             # Static assets (CSS, JS, fonts)
├── tests/              # Integration tests
├── clone/              # 📦 Cloning tools
│   ├── clone_ref_app.sh
│   ├── README.md
│   └── USAGE.md
├── .claude/            # AI assistant agents
└── notes/              # Documentation & scripts

---

🔐 Security

ref-app takes security seriously:

• ✅ Secure by default - CSRF, secure headers, HTTPS redirect
• ✅ No SQL injection - Prepared statements everywhere
• ✅ No XSS - Template auto-escaping
• ✅ Rate limiting - Protect against brute force
• ✅ Encryption - AES-256-GCM for sensitive data
• ✅ Audit logging - Track all security-relevant events
• ✅ Regular scanning - gosec and govulncheck in CI

Security Scanning

# Run security scanner
make security-scan

# Check for vulnerabilities
make vuln-check

---

🌍 Internationalization

Adding new languages:

1. Copy an existing TOML file: internal/i18n/locales/en.toml
2. Translate all keys to your language
3. Add language code to IsValidLanguage() in middleware.go
4. Test with ?lang=xx URL parameter

---

📦 Cloning for New Projects

This is the recommended way to use ref-app:

cd ref-app/clone
./clone_ref_app.sh mynewapp "My new application description"

The script will:

• Copy the entire ref-app directory
• Update all references (go.mod, README, etc.)
• Create fresh documentation
• Initialize a clean git repository
• Commit with descriptive message

See clone/README.md for full documentation.

---

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Development Workflow

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

Code Standards

• Go code formatted with gofmt
• Run go vet and fix issues
• Test coverage > 70%
• All public functions documented
• Commit messages follow conventional commits

---

📄 License

MIT License - see LICENSE file for details.

---

🙏 Acknowledgments

ref-app builds on excellent open-source projects:

• Go - Programming language
• PostgreSQL - Database
• htmx - HTML-first interactivity
• Alpine.js - Lightweight JavaScript framework
• Tailwind CSS - Utility-first CSS
• zerolog - Structured logging

---

🆘 Support

• Documentation: Check notes/ directory
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Remember: ref-app is a template, not a framework. Clone it, customize it, make it yours!

🚀 Ready to start? cd clone && ./clone_ref_app.sh myproject "My project"