tfa

A production-ready fullstack template with comprehensive authentication, RBAC, and user management. Built with React/TypeScript frontend and Go backend, featuring complete security, testing, and monitoring systems.

✨ Features

🔐 Complete Authentication System

User Registration & Login with email verification
Password Management (reset, change, strength validation)
JWT Authentication with automatic token refresh
Session Management with logout from all devices
Account Security (rate limiting, audit trails)

👥 User Management

User Profiles with preferences and settings
Role-Based Access Control (RBAC) (user/admin roles)
Account Status Management (active/inactive/suspended)
User Dashboard with statistics and activity
Email Notifications (welcome, verification, password reset)

🛡️ Security Features

RBAC Implementation with role guards and protected routes
Input Validation and sanitization
Rate Limiting and DDoS protection
Security Headers (CORS, XSS protection, etc.)
Audit Logging for sensitive operations
SQL Injection Protection with prepared statements

🏗️ Architecture

Clean Architecture with domain-driven design
Structured Logging with context and request tracking
Health Checks and monitoring endpoints
Database Migrations and seeding
Comprehensive Testing (unit, integration, E2E)
Production Deployment ready with Docker

🎯 Frontend Features

Modern React 18 with TypeScript and Vite
Responsive Design with Tailwind CSS
Component Library with reusable UI components
State Management with Context API
Form Handling with validation
Protected Routes and role-based rendering

🔧 Developer Experience

Hot Reload for frontend and backend
Comprehensive Testing suite with >90% coverage
Code Quality tools (linting, formatting)
API Documentation with examples
Development Scripts for common tasks
Docker Support for consistent environments

🚀 Quick Start (< 15 minutes)

Prerequisites

Go 1.23+ (Download)
Node.js 18+ (Download)
PostgreSQL 13+ (Download)
Git (Download)

1. Clone and Setup

# Clone the repository
git clone https://github.com/your-org/fullstack-template.git
cd tfa

# Install all dependencies (Go modules + npm packages)
make install

2. Database Setup

# Option A: Using Docker (Recommended)
docker-compose up -d postgres

# Option B: Local PostgreSQL
createdb fullstack_template

3. Environment Configuration

# Copy environment template
cp .env.example .env

# Edit .env with your settings (database, email, JWT secret)
# Defaults work with Docker PostgreSQL setup

4. Build and Run

# Build frontend and start development server
make frontend-build && make dev

# Or run frontend dev server separately for hot reload
make frontend-dev  # Terminal 1 (http://localhost:5173)
make dev          # Terminal 2 (API on http://localhost:8080)

5. Access the Application

Application: http://localhost:8080
API Health: http://localhost:8080/api/health
Admin Panel: http://localhost:8080/admin (after creating admin user)

6. Create Admin User

# Using the built-in seed command
go run cmd/api/main.go --seed-admin

# Or register normally and promote via database:
# UPDATE users SET role = 'admin' WHERE email = 'your-email@domain.com';

📚 Core Concepts

Authentication Flow

Registration: User creates account → email verification sent
Login: Credentials validated → JWT tokens issued
Access: Protected routes check JWT → automatic refresh
Logout: Tokens invalidated → audit log created

Role-Based Access Control

// Frontend: Role-based rendering
<RoleGuard requiredRole="admin">
  <AdminPanel />
</RoleGuard>

// Backend: Route protection
adminRoutes.Use(middleware.RequireRole("admin"))

User Management

Profile Management: Name, avatar, preferences
Security Settings: Password change, session management
Privacy Controls: Visibility, notification preferences
Audit Trail: Track all account changes

🏗️ Project Structure

fullstack-template/
├── 📁 cmd/api/                    # Application entry point
│   └── main.go                   # Server startup and configuration
├── 📁 internal/                  # Private application code
│   ├── 📁 auth/                  # Authentication domain
│   │   ├── domain/              # Types, entities, business rules
│   │   ├── repository/          # Data access layer
│   │   ├── service/             # Business logic
│   │   └── transport/           # HTTP handlers
│   ├── 📁 user/                  # User management domain
│   ├── 📁 admin/                 # Admin operations domain
│   ├── 📁 middleware/            # HTTP middleware
│   │   ├── auth.go              # JWT authentication
│   │   ├── rbac.go              # Role-based access control
│   │   ├── rate_limit.go        # Rate limiting
│   │   └── security.go          # Security headers
│   ├── 📁 shared/               # Shared utilities
│   │   ├── config/              # Configuration management
│   │   ├── database/            # Database connection & migrations
│   │   ├── email/               # Email service (SMTP, templates)
│   │   ├── logger/              # Structured logging
│   │   └── monitoring/          # Metrics and health checks
│   └── 📁 test/integration/     # Integration tests
├── 📁 frontend/                  # React application
│   ├── 📁 src/
│   │   ├── 📁 components/       # React components
│   │   │   ├── auth/            # Authentication components
│   │   │   ├── admin/           # Admin components
│   │   │   ├── ui/              # Reusable UI components
│   │   │   └── layout/          # Layout components
│   │   ├── 📁 contexts/         # React contexts (Auth, RBAC)
│   │   ├── 📁 hooks/            # Custom React hooks
│   │   ├── 📁 lib/              # API client and utilities
│   │   ├── 📁 pages/            # Page components
│   │   ├── 📁 types/            # TypeScript type definitions
│   │   └── 📁 test/             # Frontend tests
│   ├── package.json             # NPM dependencies and scripts
│   └── vitest.config.ts         # Test configuration
├── 📁 docs/                     # Documentation
├── 🐳 docker-compose.yml        # Development environment
├── 🐳 Dockerfile               # Production container
├── ⚙️ Makefile                 # Development commands
├── 🔧 .env.example             # Environment template
└── 📖 README.md                # This file

🔧 Development Commands

Backend Development

# Development
make dev                    # Run Go API server with hot reload
make test                   # Run all Go tests
make test-coverage          # Run tests with coverage report
make lint                   # Run Go linters (golangci-lint)

# Database
make db-migrate            # Run database migrations
make db-seed               # Seed database with test data
make db-reset              # Reset database (drop + migrate + seed)

# Building
make build                 # Build Go binary for production
make docker-build          # Build Docker image

Frontend Development

# Development
make frontend-dev          # Start Vite dev server (http://localhost:5173)
make frontend-build        # Build for production
make frontend-test         # Run frontend tests
make frontend-test-ui      # Run tests with UI
make frontend-lint         # Run ESLint
make frontend-type-check   # TypeScript type checking

# Testing
cd frontend && npm run test          # Run tests
cd frontend && npm run test:coverage # Run with coverage
cd frontend && npm run test:ui       # Interactive test UI

Full Stack Commands

make install               # Install all dependencies
make build-all            # Build frontend + backend
make clean                 # Clean build artifacts
make docker-dev           # Start full environment with Docker
make docker-logs          # View container logs

🧪 Testing

Running Tests

# Backend tests
make test                  # Unit + integration tests
make test-coverage         # With coverage report

# Frontend tests  
cd frontend && npm test    # Component + API tests
cd frontend && npm run test:coverage  # With coverage

# Integration tests
make test-integration      # End-to-end testing

Test Coverage

The template includes comprehensive test coverage:

Backend: >90% coverage including integration tests
Frontend: >85% coverage with component and API tests
E2E Tests: Critical user flows and RBAC scenarios

Test Types

Unit Tests: Individual functions and components
Integration Tests: API endpoints, database operations
Component Tests: React component behavior
E2E Tests: Complete user workflows

🔐 Environment Variables

Required Variables

# Server Configuration
PORT=8080                           # Server port
ENVIRONMENT=development             # Environment (development/production)
LOG_LEVEL=info                      # Logging level

# Database
DATABASE_HOST=localhost             # PostgreSQL host
DATABASE_PORT=5432                  # PostgreSQL port
DATABASE_USER=postgres              # Database user
DATABASE_PASSWORD=postgres          # Database password
DATABASE_NAME=fullstack_template    # Database name
DATABASE_SSL_MODE=disable           # SSL mode (disable/require)

# JWT Configuration  
JWT_SECRET=your-256-bit-secret      # JWT signing secret (generate secure key)
JWT_ACCESS_DURATION=1h              # Access token lifetime
JWT_REFRESH_DURATION=720h          # Refresh token lifetime (30 days)

# Email Configuration (Optional)
EMAIL_PROVIDER=smtp                 # Email provider (smtp/mock)
SMTP_HOST=smtp.gmail.com           # SMTP server
SMTP_PORT=587                      # SMTP port
SMTP_USERNAME=your-email@gmail.com # SMTP username
SMTP_PASSWORD=your-app-password    # SMTP password
EMAIL_FROM=noreply@yourapp.com     # From email address

Optional Variables

# Rate Limiting
RATE_LIMIT_REQUESTS=100            # Requests per window
RATE_LIMIT_WINDOW=1m               # Rate limit window

# Security
CORS_ORIGINS=http://localhost:3000 # Allowed CORS origins
SECURE_COOKIES=false               # Use secure cookies (true in production)

# Monitoring
METRICS_ENABLED=true               # Enable metrics collection
HEALTH_CHECK_INTERVAL=30s          # Health check interval

🚀 Deployment

Production Deployment

Build the application:
```
make build-all
```

Set production environment variables:

export ENVIRONMENT=production
export JWT_SECRET="your-production-jwt-secret"
export DATABASE_URL="postgresql://user:pass@host:5432/dbname"

Run migrations:
```
./bin/api --migrate
```
Start the server:
```
./bin/api
```

Docker Deployment

# Build and run with Docker
docker build -t fullstack-template .
docker run -p 8080:8080 --env-file .env fullstack-template

# Or use Docker Compose
docker-compose -f docker-compose.prod.yml up -d

Deployment Checklist

Set strong JWT secret (256-bit random key)
Configure production database
Set up email service (SMTP)
Enable HTTPS/TLS
Configure reverse proxy (nginx/traefik)
Set up monitoring and logging
Configure backup strategy
Set proper CORS origins
Review security headers

🔧 Customization & Extension

Adding New Features

Backend: Follow the domain-driven structure

internal/
├── newfeature/
│   ├── domain/      # Types and business rules
│   ├── repository/  # Data access
│   ├── service/     # Business logic
│   └── transport/   # HTTP handlers

Frontend: Use the component structure

src/components/newfeature/
├── NewFeatureForm.tsx
├── NewFeatureList.tsx
└── index.ts

Extending Authentication

Add OAuth providers: Extend auth service
Custom user fields: Update user domain model
Additional roles: Extend RBAC system
MFA support: Add to auth flow

Customizing UI

Theming: Modify Tailwind config
Components: Extend the UI component library
Layouts: Create new layout components
Styling: Use CSS modules or styled-components

📊 Monitoring & Health Checks

Built-in Endpoints

GET /api/health - Application health status
GET /api/metrics - Prometheus metrics (if enabled)
GET /api/info - Application version and environment

Health Check Response

{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00Z",
  "version": "1.0.0",
  "environment": "production",
  "database": "connected",
  "email": "configured"
}

🐛 Troubleshooting

Common Issues

Frontend not loading

# Ensure frontend is built
make frontend-build

# Check if dist directory exists
ls frontend/dist/

# Verify server is serving static files
curl http://localhost:8080/

Database connection failed

# Check PostgreSQL is running
pg_isready -h localhost -p 5432

# Verify environment variables
echo $DATABASE_HOST $DATABASE_USER

# Test connection manually
psql -h localhost -U postgres -d fullstack_template

Authentication not working

# Check JWT secret is set
echo $JWT_SECRET

# Verify user is created and active
psql -c "SELECT email, status, email_verified FROM users;"

# Check browser network tab for auth errors

Rate limiting errors

# Check rate limit configuration
echo $RATE_LIMIT_REQUESTS

# Clear rate limit (Redis) or restart server
# Rate limits reset after window expires

Development Tips

Use Docker for consistent environment
Check logs for detailed error messages
Run tests to verify functionality
Use browser dev tools for frontend debugging
Monitor database connections and queries

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Add tests for new functionality
Ensure all tests pass (make test && cd frontend && npm test)
Run linters (make lint && make frontend-lint)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Standards

Go: Follow Effective Go guidelines
TypeScript/React: Follow React Best Practices
Testing: Maintain >90% backend and >85% frontend coverage
Documentation: Update docs for new features
Security: Follow OWASP Guidelines

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

Documentation: docs/
API Reference: docs/api/
Issues: GitHub Issues
Discussions: GitHub Discussions

🎯 Roadmap

Built with ❤️ for developers who value security, testing, and maintainable code.

Name		Name	Last commit message	Last commit date
.claude		.claude
.github/workflows		.github/workflows
cmd/api		cmd/api
docs		docs
frontend		frontend
internal		internal
tests/integration		tests/integration
.env.example		.env.example
.gitignore		.gitignore
.golangci.yml		.golangci.yml
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
REQUIREMENTS.md		REQUIREMENTS.md
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

tfa