kooza-collinz-portfolio-backend/
├── cache/            # Redis cache wrapper
├── config/           # Reads .env, holds app + OAuth + storage settings
├── controllers/      # Handles incoming HTTP requests
├── dtos/             # Data Transfer Objects (request/response shapes)
├── initializers/     # Sets up the database, Redis, and mailer
├── jobs/             # Background image processing
├── mail/             # Sends emails through Resend
├── middleware/       # Guards routes (auth + CORS)
├── migrations/       # Creates/updates the database tables
├── models/           # GORM models (Go structs = database tables)
├── storage/          # S3-compatible file storage + image processing
├── docker-compose.yml
├── go.mod
├── main.go
└── .env

        Browser / Frontend
               |
               v
   [middleware]  -> checks CORS + the JWT token (are you allowed?)
               |
               v
   [controller]  -> decides WHAT to do (save a user? send a mail?)
               |
               v
  [models + initializers] -> talks to PostgreSQL / Redis

mkdir kooza-collinz-portfolio-backend
cd kooza-collinz-portfolio-backend

go mod init github.com/watuulo-kooza/kooza-collinz-portfolio-backend

mkdir cache config controllers dtos initializers jobs mail middleware migrations models storage

go get github.com/gin-gonic/gin
go get gorm.io/gorm gorm.io/driver/postgres
go get github.com/joho/godotenv
go get github.com/golang-jwt/jwt/v5
go get golang.org/x/crypto
go get github.com/redis/go-redis/v9
go get github.com/gin-contrib/cors
go get golang.org/x/oauth2
go get github.com/aws/aws-sdk-go-v2/config
go get github.com/aws/aws-sdk-go-v2/credentials
go get github.com/aws/aws-sdk-go-v2/service/s3
go get github.com/disintegration/imaging
go get github.com/MUKE-coder/gorm-studio

touch .env

# --- App settings ---
APP_NAME=Kooza Collins
APP_ENV=development
PORT=8080
APP_URL=http://localhost:3000
GIN_MODE=debug

# --- PostgreSQL (our main database) ---
POSTGRES_HOST=localhost
POSTGRES_USER=kooza_collins
POSTGRES_PASSWORD=strong-postgres-password
POSTGRES_DB=kooza_collins_db
POSTGRES_PORT=5436
POSTGRES_SSLMODE=disable

# --- JWT (login tokens) ---
SECRET_KEY=any-long-random-string-you-invent
JWT_ACCESS_EXPIRY=15m
JWT_REFRESH_EXPIRY=168h

# --- Redis (cache) ---
REDIS_PASSWORD=strong-redis-password
REDIS_URL=redis://:strong-redis-password@localhost:6380

# --- Resend (email) ---
RESEND_API_KEY=your-resend-api-key
RESEND_FROM_EMAIL=noreply@koozacollinz.com

# --- CORS (which websites may call our API) ---
CORS_ORIGINS=http://localhost:3000,http://localhost:3001

# --- OAuth2 providers (sign in with ...) ---
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_REDIRECT_URL=http://localhost:8080/api/v1/auth/google/callback
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
GITHUB_REDIRECT_URL=http://localhost:8080/api/v1/auth/github/callback

# --- S3-compatible storage (MinIO locally) ---
STORAGE_ENDPOINT=http://localhost:9002
STORAGE_ACCESS_KEY=minioadmin
STORAGE_SECRET_KEY=minioadmin
STORAGE_BUCKET=kooza-collins
STORAGE_REGION=us-east-1
STORAGE_USE_SSL=false

package config

import (
	"fmt"
	"os"
	"strings"
	"time"

	"github.com/joho/godotenv"
)

// Config holds every value the application needs, mapped 1:1 to .env keys.
type Config struct {
	AppName    string
	AppEnv     string
	Port       string
	AppURL     string
	GinMode    string

	PostgresHost     string
	PostgresUser     string
	PostgresPassword string
	PostgresDB       string
	PostgresPort     string
	PostgresSSLMode  string

	JWTSecret        string
	JWTAccessExpiry  time.Duration
	JWTRefreshExpiry time.Duration

	RedisURL string

	ResendAPIKey  string
	MailFromEmail string

	CORSOrigins []string
}

// Load reads .env, maps every key into the struct, and validates
// required fields.
func Load() (*Config, error) {
	_ = godotenv.Load()

	jwtSecret := getEnv("SECRET_KEY", "")

	accessExpiry, err := time.ParseDuration(getEnv("JWT_ACCESS_EXPIRY", "15m"))
	if err != nil {
		return nil, fmt.Errorf("invalid JWT_ACCESS_EXPIRY: %w", err)
	}
	refreshExpiry, err := time.ParseDuration(getEnv("JWT_REFRESH_EXPIRY", "168h"))
	if err != nil {
		return nil, fmt.Errorf("invalid JWT_REFRESH_EXPIRY: %w", err)
	}

	cfg := &Config{
		AppName:    getEnv("APP_NAME", "Kooza Collins"),
		AppEnv:     getEnv("APP_ENV", "development"),
		Port:       getEnv("PORT", "8080"),
		AppURL:     getEnv("APP_URL", "http://localhost:3000"),
		GinMode:    getEnv("GIN_MODE", "debug"),

		PostgresHost:     getEnv("POSTGRES_HOST", "localhost"),
		PostgresUser:     getEnv("POSTGRES_USER", "postgres"),
		PostgresPassword: getEnv("POSTGRES_PASSWORD", "postgres"),
		PostgresDB:       getEnv("POSTGRES_DB", "portfolio_db"),
		PostgresPort:     getEnv("POSTGRES_PORT", "5432"),
		PostgresSSLMode:  getEnv("POSTGRES_SSLMODE", "disable"),

		JWTSecret:        jwtSecret,
		JWTAccessExpiry:  accessExpiry,
		JWTRefreshExpiry: refreshExpiry,

		RedisURL: getEnv("REDIS_URL", "redis://localhost:6379"),

		ResendAPIKey:  getEnv("RESEND_API_KEY", ""),
		MailFromEmail: getEnv("RESEND_FROM_EMAIL", "noreply@localhost"),

		CORSOrigins: strings.Split(getEnv("CORS_ORIGINS", "http://localhost:3000"), ","),
	}

	// --- Required-field validation ---
	if cfg.PostgresPassword == "" {
		return nil, fmt.Errorf("POSTGRES_PASSWORD is required")
	}
	if cfg.JWTSecret == "" {
		return nil, fmt.Errorf("SECRET_KEY is required")
	}

	return cfg, nil
}

// getEnv returns the .env value for key, or a default if it's missing.
func getEnv(key, fallback string) string {
	if val := os.Getenv(key); val != "" {
		return val
	}
	return fallback
}

package config

import "golang.org/x/oauth2"

// GoogleOAuthConfig needs these .env variables:
//   GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REDIRECT_URL
func GoogleOAuthConfig() *oauth2.Config {
	return &oauth2.Config{
		ClientID:     getEnv("GOOGLE_CLIENT_ID", ""),
		ClientSecret: getEnv("GOOGLE_CLIENT_SECRET", ""),
		RedirectURL:  getEnv("GOOGLE_REDIRECT_URL", ""),
		Scopes: []string{
			"https://www.googleapis.com/auth/userinfo.email",
			"https://www.googleapis.com/auth/userinfo.profile",
		},
		Endpoint: oauth2.Endpoint{
			AuthURL:  "https://accounts.google.com/o/oauth2/v2/auth",
			TokenURL: "https://oauth2.googleapis.com/token",
		},
	}
}

package initializers

import (
	"fmt"
	"log"

	"github.com/Watuulo-Richard/kooza-collins-portfolio-backend/config"
	"gorm.io/driver/postgres"
	"gorm.io/gorm"
)

var DB *gorm.DB

func ConnectToDB(cfg *config.Config) {
	var err error

	databaseUrl := fmt.Sprintf(
		"host=%s user=%s password=%s dbname=%s port=%s sslmode=%s",
		cfg.PostgresHost,
		cfg.PostgresUser,
		cfg.PostgresPassword,
		cfg.PostgresDB,
		cfg.PostgresPort,
		cfg.PostgresSSLMode,
	)

	DB, err = gorm.Open(postgres.Open(databaseUrl), &gorm.Config{})
	if err != nil {
		log.Fatal("Failed to connect to the DB:", err)
	}

	fmt.Println("Successfully connected to database!")
}

package initializers

import (
	"context"
	"log"

	"github.com/Watuulo-Richard/kooza-collins-portfolio-backend/config"
	"github.com/redis/go-redis/v9"
)

var RedisClient *redis.Client

func ConnectToRedis(cfg *config.Config) {
	opts, err := redis.ParseURL(cfg.RedisURL)
	if err != nil {
		log.Fatal("Failed to parse REDIS_URL: ", err)
	}

	RedisClient = redis.NewClient(opts)

	if err := RedisClient.Ping(context.Background()).Err(); err != nil {
		log.Fatal("Failed to connect to Redis: ", err)
	}

	log.Println("Connected to Redis")
}

package initializers

import (
	"github.com/Watuulo-Richard/kooza-collins-portfolio-backend/config"
	"github.com/Watuulo-Richard/kooza-collins-portfolio-backend/mail"
)

var Mailer *mail.Mailer

func InitMailer(cfg *config.Config) {
	Mailer = mail.New(
		cfg.ResendAPIKey,
		cfg.MailFromEmail,
	)
}

package models

import (
	"time"

	"gorm.io/gorm"
)

// Role constants (UPPERCASE — role checks compare against these exactly)
const (
	RoleAdmin = "ADMIN"
	RoleUser  = "USER"
)

type User struct {
	ID        uint      `gorm:"primaryKey" json:"id"`
	FirstName string    `gorm:"size:255;not null" json:"first_name" binding:"required"`
	LastName  string    `gorm:"size:255;not null" json:"last_name" binding:"required"`
	Email     string    `gorm:"size:255;uniqueIndex;not null" json:"email" binding:"required,email"`
	Password  string    `gorm:"size:255" json:"-"`
	Role      string    `gorm:"size:20;default:'USER'" json:"role"`
	Avatar    string    `gorm:"size:500" json:"avatar"`
	JobTitle  string    `gorm:"size:255" json:"job_title"`
	Bio       string    `gorm:"type:text" json:"bio"`
	Active    bool      `gorm:"default:true" json:"active"`
	Provider  string    `gorm:"size:50;default:'local'" json:"provider"`

	// One of these gets set when the user signs in with that provider
	GoogleID string `gorm:"size:255;index" json:"-"`
	GithubID string `gorm:"size:255;index" json:"-"`
	// ...LinkedinID, SpotifyID, DiscordID follow the exact same pattern...

	EmailVerifiedAt *time.Time `json:"email_verified_at"`

	// We store HASHES of tokens, never the tokens themselves
	VerificationTokenHash        string     `gorm:"size:64;index" json:"-"`
	VerificationTokenExpiresAt   *time.Time `json:"-"`
	ResetPasswordTokenHash       string     `gorm:"size:64;index" json:"-"`
	ResetPasswordTokenExpiresAt  *time.Time `json:"-"`

	CreatedAt time.Time      `json:"created_at"`
	UpdatedAt time.Time      `json:"updated_at"`
	DeletedAt gorm.DeletedAt `gorm:"index" json:"-"`
}

package models

import "time"

// ContactMessage stores submissions from the site's "Contact me" form.
type ContactMessage struct {
	ID        uint      `gorm:"primaryKey" json:"id"`
	Name      string    `gorm:"not null" json:"name"`
	Email     string    `gorm:"not null" json:"email"`
	Message   string    `gorm:"type:text;not null" json:"message"`
	Read      bool      `gorm:"not null;default:false;index" json:"read"`
	Replied   bool      `gorm:"not null;default:false" json:"replied"`
	Reply     *string   `gorm:"type:text" json:"reply,omitempty"`
	RepliedAt *time.Time `gorm:"index" json:"replied_at,omitempty"`
	CreatedAt time.Time `gorm:"not null;default:now();index" json:"created_at"`
}

func (ContactMessage) TableName() string {
	return "contact_messages"
}

package dtos

// SuccessResponse represents a successful API response
type SuccessResponse struct {
	Success bool        `json:"success"`
	Data    interface{} `json:"data,omitempty"`
	Message string      `json:"message,omitempty"`
}

// ErrorResponse represents an error API response
type ErrorResponse struct {
	Success bool   `json:"success"`
	Error   string `json:"error"`
	Message string `json:"message,omitempty"`
}

package dtos

import "time"

type CreateUserRequest struct {
	FirstName string `json:"first_name" binding:"required,min=2,max=100"`
	LastName  string `json:"last_name" binding:"required,min=2,max=100"`
	Email     string `json:"email" binding:"required,email"`
	Password  string `json:"password" binding:"required,min=6,max=100"`
}

type LoginUserRequest struct {
	Email      string `json:"email" binding:"required,email"`
	Password   string `json:"password" binding:"required,min=6,max=100"`
	RememberMe bool   `json:"remember_me"`
}

type LoginResponse struct {
	ID        uint   `json:"id"`
	FirstName string `json:"first_name"`
	LastName  string `json:"last_name"`
	Email     string `json:"email"`
	Token     string `json:"token"`
	Role      string `json:"role"`
	ExpiresIn int64  `json:"expires_in"`
}

type UserResponse struct {
	ID        uint      `json:"id"`
	FirstName string    `json:"first_name"`
	LastName  string    `json:"last_name"`
	Email     string    `json:"email"`
	Role      string    `json:"role"`
	Avatar    string    `json:"avatar,omitempty"`
	JobTitle  string    `json:"job_title,omitempty"`
	Active    bool      `json:"active"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

package middleware

import (
	"time"

	"github.com/gin-contrib/cors"
	"github.com/gin-gonic/gin"
)

func CORSMiddleware() gin.HandlerFunc {
	return cors.New(cors.Config{
		AllowAllOrigins: true, // Use for development
		AllowMethods:    []string{"GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"},
		AllowHeaders:    []string{"Origin", "Content-Type", "Accept", "Authorization"},
		ExposeHeaders:   []string{"Content-Length"},
		AllowCredentials: false,
		MaxAge:          12 * time.Hour,
	})
}

package middleware

import (
	"fmt"
	"net/http"
	"strings"
	"time"

	"github.com/Watuulo-Richard/kooza-collins-portfolio-backend/config"
	"github.com/Watuulo-Richard/kooza-collins-portfolio-backend/dtos"
	"github.com/Watuulo-Richard/kooza-collins-portfolio-backend/initializers"
	"github.com/Watuulo-Richard/kooza-collins-portfolio-backend/models"
	"github.com/gin-gonic/gin"
	"github.com/golang-jwt/jwt/v5"
)

func RequireAuthWithToken(c *gin.Context) {
	// 1. Get the token from the "Authorization: Bearer <token>" header
	authHeader := c.GetHeader("Authorization")
	if authHeader == "" {
		c.JSON(http.StatusUnauthorized, dtos.ErrorResponse{
			Success: false,
			Error:   "Unauthorized - No token provided",
		})
		c.Abort()
		return
	}

	// 2. Strip the "Bearer " prefix
	tokenString := strings.TrimPrefix(authHeader, "Bearer ")
	if tokenString == authHeader {
		c.JSON(http.StatusUnauthorized, dtos.ErrorResponse{
			Success: false,
			Error:   "Unauthorized - Invalid token format. Use 'Bearer <token>'",
		})
		c.Abort()
		return
	}

	// 3. Decode + verify the token's signature
	token, err := jwt.Parse(tokenString, func(token *jwt.Token) (interface{}, error) {
		if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
			return nil, fmt.Errorf("unexpected signing method: %v", token.Header["alg"])
		}
		return []byte(config.JWTSecret), nil
	})
	if err != nil {
		c.JSON(http.StatusUnauthorized, dtos.ErrorResponse{
			Success: false,
			Error:   "Unauthorized - Invalid token",
		})
		c.Abort()
		return
	}

	// 4. Check the payload + expiry
	claims, ok := token.Claims.(jwt.MapClaims)
	if !ok || !token.Valid {
		c.AbortWithStatusJSON(http.StatusUnauthorized, dtos.ErrorResponse{
			Success: false,
			Error:   "Unauthorized - Invalid token claims",
		})
		return
	}

	exp, ok := claims["exp"].(float64)
	if !ok || float64(time.Now().Unix()) > exp {
		c.AbortWithStatusJSON(http.StatusUnauthorized, dtos.ErrorResponse{
			Success: false,
			Error:   "Unauthorized - Token expired",
		})
		return
	}

	// 5. Pull out the user ID we stored in "sub" and load that user
	subFloat, ok := claims["sub"].(float64)
	if !ok || subFloat <= 0 {
		c.AbortWithStatusJSON(http.StatusUnauthorized, dtos.ErrorResponse{
			Success: false,
			Error:   "Unauthorized - Invalid token subject",
		})
		return
	}
	userID := uint(subFloat)

	var user models.User
	if err := initializers.DB.First(&user, "id = ?", userID).Error; err != nil {
		c.AbortWithStatusJSON(http.StatusUnauthorized, dtos.ErrorResponse{
			Success: false,
			Error:   "Unauthorized - User not found",
		})
		return
	}

	// 6. Hand the user to the next handler via the context
	c.Set("user", user)
	c.Next() // continue to the controller
}

package mail

import (
	"bytes"
	"context"
	"encoding/json"
	"fmt"
	"html/template"
	"net/http"
	"time"
)

// Mailer sends emails via the Resend API.
type Mailer struct {
	apiKey string
	from   string
	client *http.Client
}

func New(apiKey, from string) *Mailer {
	return &Mailer{
		apiKey: apiKey,
		from:   from,
		client: &http.Client{Timeout: 10 * time.Second},
	}
}

// SendOptions configures an email to send.
type SendOptions struct {
	To       string
	Subject  string
	Template string // name of the template in EmailTemplates
	Data     map[string]interface{}
}

// Send renders a template and sends the email via Resend.
func (m *Mailer) Send(ctx context.Context, opts SendOptions) error {
	htmlBody, err := m.renderTemplate(opts.Template, opts.Data)
	if err != nil {
		return fmt.Errorf("rendering template %q: %w", opts.Template, err)
	}

	payload := map[string]interface{}{
		"from":    m.from,
		"to":      []string{opts.To},
		"subject": opts.Subject,
		"html":    htmlBody,
	}

	body, err := json.Marshal(payload)
	if err != nil {
		return err
	}

	req, err := http.NewRequestWithContext(ctx, http.MethodPost, "https://api.resend.com/emails", bytes.NewReader(body))
	if err != nil {
		return err
	}
	req.Header.Set("Authorization", "Bearer "+m.apiKey)
	req.Header.Set("Content-Type", "application/json")

	resp, err := m.client.Do(req)
	if err != nil {
		return err
	}
	defer resp.Body.Close()

	if resp.StatusCode >= 400 {
		return fmt.Errorf("resend API error (%d)", resp.StatusCode)
	}
	return nil
}

package mail

var EmailTemplates = map[string]string{
	"welcome":            welcomeTemplate,
	"password-reset":     passwordResetTemplate,
	"email-verification": emailVerificationTemplate,
	"notification":       notificationTemplate,
	"contact-acknowledgment": contactAcknowledgmentTemplate,
	"contact-reply":          contactReplyTemplate,
}

const emailVerificationTemplate = `... <h1>Verify Your Email</h1>
<p>Hi {{.Name}}, welcome aboard! Please enter this code to verify your email:</p>
<div class="code">{{.Code}}</div>
<p>This code expires in 10 minutes...</p> ...`

func SignUpWithToken(c *gin.Context) {
	// 1. Read + validate the incoming JSON
	var request dtos.CreateUserRequest
	if err := c.ShouldBindJSON(&request); err != nil {
		c.JSON(http.StatusBadRequest, dtos.ErrorResponse{
			Success: false,
			Error:   "Invalid input: " + err.Error(),
		})
		return
	}

	// 2. Hash the password (never store it raw!)
	hashPassword, err := bcrypt.GenerateFromPassword([]byte(request.Password), 10)
	if err != nil {
		c.JSON(http.StatusBadRequest, dtos.ErrorResponse{
			Success: false,
			Error:   "Failed to hash the password",
		})
		return // fixed: this was missing, so a hash failure used to fall through
	}

	// 3. Build the user row
	user := models.User{
		FirstName: request.FirstName,
		LastName:  request.LastName,
		Email:     request.Email,
		Password:  string(hashPassword),
		Role:      models.RoleUser,
	}

	// 4. Save to the database
	if err := initializers.DB.Create(&user).Error; err != nil {
		if strings.Contains(err.Error(), "duplicate") ||
			strings.Contains(err.Error(), "unique") {
			c.JSON(http.StatusConflict, dtos.ErrorResponse{
				Success: false,
				Error:   "User with this email already exists",
			})
			return
		}
		c.JSON(http.StatusInternalServerError, dtos.ErrorResponse{
			Success: false,
			Error:   "Failed to create user",
		})
		return
	}

	// 5. Log the action to the audit trail
	// ...initializers.AuditLogger.Log(context.Background(), audit.Entry{...})...

	// 6. Generate a 6-digit verification code, hash it, save the hash
	rawCode, hashedCode, err := generateVerificationCode()
	if err != nil { /* handle */ }

	expiresAt := time.Now().Add(time.Minute * 10)
	user.VerificationTokenHash = hashedCode
	user.VerificationTokenExpiresAt = &expiresAt
	initializers.DB.Save(&user)

	// 7. Email the raw code (the hash stays in the DB)
	initializers.Mailer.Send(context.Background(), mail.SendOptions{
		To:       user.Email,
		Subject:  "Verify your email",
		Template: "email-verification",
		Data: map[string]interface{}{
			"AppName": "Kooza Collins",
			"Name":    user.FirstName,
			"Code":    rawCode,
			"Year":    time.Now().Year(),
		},
	})

	c.JSON(http.StatusCreated, dtos.SuccessResponse{
		Success: true,
		Message: "Account created! Please check your email for a 6-digit verification code",
		Data: dtos.UserResponse{
			ID: user.ID, FirstName: user.FirstName,
			LastName: user.LastName, Email: user.Email,
			Role: user.Role,
		},
	})
}

const (
	rememberMeTTL = time.Hour * 24 * 30 // "Remember me" checked
	sessionTTL    = time.Hour * 24      // not checked
)

func LoginWithToken(c *gin.Context) {
	var req dtos.LoginUserRequest
	if err := c.ShouldBindJSON(&req); err != nil {
		c.JSON(http.StatusBadRequest, dtos.ErrorResponse{Success: false, Error: "Invalid input: " + err.Error()})
		return
	}

	// 1. Find the user by email
	var user models.User
	result := initializers.DB.Where("email = ?", req.Email).First(&user)
	if result.Error != nil {
		c.JSON(http.StatusUnauthorized, dtos.ErrorResponse{Success: false, Error: "Invalid email or password"})
		return
	}

	// 2. Compare the submitted password against the stored hash
	if err := bcrypt.CompareHashAndPassword([]byte(user.Password), []byte(req.Password)); err != nil {
		c.JSON(http.StatusUnauthorized, dtos.ErrorResponse{Success: false, Error: "Invalid email or password"})
		return
	}

	// 3. Block inactive + unverified accounts
	if !user.Active {
		c.JSON(http.StatusForbidden, dtos.ErrorResponse{Success: false, Error: "Account is inactive"})
		return
	}
	if !user.IsEmailVerified() {
		c.JSON(http.StatusForbidden, dtos.ErrorResponse{Success: false, Error: "Email not verified"})
		return
	}

	// 4. Build the JWT
	ttl := sessionTTL
	if req.RememberMe {
		ttl = rememberMeTTL
	}

	token := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
		"sub": user.ID,                                  // subject = the user's ID
		"exp": time.Now().Add(ttl).Unix(),               // expiry
	})
	tokenString, err := token.SignedString([]byte(config.JWTSecret))
	if err != nil {
		c.JSON(http.StatusInternalServerError, dtos.ErrorResponse{Success: false, Error: "Failed to create token"})
		return
	}

	// 5. Audit log, then respond with the token
	c.JSON(http.StatusOK, dtos.SuccessResponse{
		Success: true,
		Message: "Login successful",
		Data: dtos.LoginResponse{
			ID: user.ID, FirstName: user.FirstName, LastName: user.LastName,
			Email: user.Email, Token: tokenString, Role: user.Role,
			ExpiresIn: int64(ttl.Seconds()),
		},
	})
}

func ValidateUser(c *gin.Context) {
	raw, exists := c.Get("user")
	if !exists {
		c.JSON(http.StatusUnauthorized, dtos.ErrorResponse{Success: false, Error: "Unauthorized - No user in context"})
		return
	}
	user, ok := raw.(models.User)
	if !ok {
		c.JSON(http.StatusInternalServerError, dtos.ErrorResponse{Success: false, Error: "Failed to parse user from context"})
		return
	}

	c.JSON(http.StatusOK, dtos.SuccessResponse{
		Success: true,
		Message: "User retrieved successfully",
		Data: dtos.UserResponse{
			ID: user.ID, FirstName: user.FirstName, LastName: user.LastName,
			Email: user.Email, Role: user.Role, Active: user.Active,
		},
	})
}

// generateVerificationCode creates a random 6-digit numeric code (e.g. "042817")
// and its SHA-256 hash. We email the raw code, but only store the hash.
func generateVerificationCode() (rawCode string, hashedCode string, err error) {
	n, err := rand.Int(rand.Reader, big.NewInt(1000000))
	if err != nil {
		return "", "", err
	}
	rawCode = fmt.Sprintf("%06d", n.Int64()) // zero-pad so it's always 6 digits

	hash := sha256.Sum256([]byte(rawCode))
	hashedCode = hex.EncodeToString(hash[:])
	return rawCode, hashedCode, nil
}

// generateResetToken creates a cryptographically random 32-byte value,
// hex-encodes it (the part we email), then SHA-256 hashes it (the part we store).
func generateResetToken() (rawToken string, hashedToken string, err error) {
	bytes := make([]byte, 32)
	if _, err = rand.Read(bytes); err != nil {
		return "", "", err
	}
	rawToken = hex.EncodeToString(bytes)

	hash := sha256.Sum256([]byte(rawToken))
	hashedToken = hex.EncodeToString(hash[:])
	return rawToken, hashedToken, nil
}

const redisContactListKey = "contact:messages:list"
const contactListCacheTTL = 60 * time.Second

// Public rate limit for the contact form — max submissions per IP per hour
const contactRateLimitWindow = time.Hour
const contactRateLimitMax = 5

func CreateContactMessage(c *gin.Context) {
	ctx := context.Background()

	// --- Rate limit by IP, before touching the database ---
	rateLimitKey := "contact:ratelimit:" + c.ClientIP()
	count, err := initializers.RedisClient.Incr(ctx, rateLimitKey).Result()
	if err == nil {
		if count == 1 {
			initializers.RedisClient.Expire(ctx, rateLimitKey, contactRateLimitWindow)
		}
		if count > contactRateLimitMax {
			c.JSON(http.StatusTooManyRequests, dtos.ErrorResponse{
				Success: false, Error: "Too many requests",
			})
			return
		}
	}

	// --- Validate + save the message ---
	var request dtos.CreateContactMessageRequest
	if err := c.ShouldBindJSON(&request); err != nil {
		c.JSON(http.StatusBadRequest, dtos.ErrorResponse{Success: false, Error: "Invalid input: " + err.Error()})
		return
	}

	message := models.ContactMessage{
		Name: request.Name, Email: request.Email, Message: request.Message,
	}
	if err := initializers.DB.Create(&message).Error; err != nil {
		c.JSON(http.StatusInternalServerError, dtos.ErrorResponse{Success: false, Error: "Failed to save your message"})
		return
	}

	// --- Send a "thanks!" email (fire-and-forget) ---
	// ...Mailer.Send(..., Template: "contact-acknowledgment", ...)...

	// --- Invalidate the cached list (it's now stale) ---
	initializers.RedisClient.Del(ctx, redisContactListKey)

	c.JSON(http.StatusCreated, dtos.SuccessResponse{
		Success: true,
		Message: "Thanks for reaching out! I'll get back to you soon",
		Data:    toContactMessageResponse(message),
	})
}

// GetContactMessages serves the list from Redis cache when possible,
// falling back to Postgres on a miss.
func GetContactMessages(c *gin.Context) {
	ctx := context.Background()

	cached, err := initializers.RedisClient.Get(ctx, redisContactListKey).Result()
	if err == nil {
		var messages []dtos.ContactMessageResponse
		if jsonError := json.Unmarshal([]byte(cached), &messages); jsonError == nil {
			c.JSON(http.StatusOK, dtos.SuccessResponse{Success: true, Data: messages})
			return // cache hit — Postgres never touched
		}
	}

	// cache miss — read from Postgres
	var messages []models.ContactMessage
	initializers.DB.Order("created_at desc").Find(&messages)
	responses := toContactMessageResponses(messages)

	// store in cache for next time
	if encoded, err := json.Marshal(responses); err == nil {
		initializers.RedisClient.Set(ctx, redisContactListKey, encoded, contactListCacheTTL)
	}

	c.JSON(http.StatusOK, dtos.SuccessResponse{Success: true, Data: responses})
}

1. User clicks "Continue with Google"  → GET /api/v1/auth/google
2. OAuthLoginHandler redirects browser → Google's login/consent page
3. User approves on Google's website (we never see their Google password)
4. Google redirects back            → GET /api/v1/auth/google/callback?code=...&state=...
5. OAuthCallbackHandler swaps code  → gets an access token (server-to-server)
6. ...asks Google "who is this?"    → fetchUserInfo(accessToken)
7. ...finds-or-creates a User row   → findOrCreateOAuthUser
8. ...issues the same JWT as login  → redirects browser to frontend with ?token=JWT

type oauthUserInfo struct {
	ProviderUserID string // the provider's own unique ID for this person
	Email          string
	FirstName      string
	LastName       string
	AvatarURL      string
}

type fetchUserInfoFunc func(accessToken string) (*oauthUserInfo, error)

func OAuthLoginHandler(cfg *oauth2.Config) gin.HandlerFunc {
	return func(c *gin.Context) {
		// Generate a signed "state" value — the CSRF guard
		state, err := generateOAuthState()
		if err != nil {
			c.JSON(http.StatusInternalServerError, dtos.ErrorResponse{Success: false, Error: "Failed to start sign-in"})
			return
		}

		// Redirect the browser to the provider's consent page
		authURL := cfg.AuthCodeURL(state)
		c.Redirect(http.StatusFound, authURL)
	}
}

func OAuthCallbackHandler(provider string, cfg *oauth2.Config, fetchUserInfo fetchUserInfoFunc) gin.HandlerFunc {
	return func(c *gin.Context) {
		frontendURL := config.AppURL

		// Step 4a: verify the state round-tripped untouched
		state := c.Query("state")
		if !verifyOAuthState(state) {
			c.Redirect(http.StatusFound, frontendURL+"/auth/callback?error=invalid_state")
			return
		}

		// Step 4b: the user may have hit "Cancel" instead of "Allow"
		if oauthErr := c.Query("error"); oauthErr != "" {
			c.Redirect(http.StatusFound, frontendURL+"/auth/callback?error="+url.QueryEscape(oauthErr))
			return
		}

		// Step 4c: swap the temporary code for a real access token (server-to-server)
		code := c.Query("code")
		token, err := cfg.Exchange(context.Background(), code)
		if err != nil {
			c.Redirect(http.StatusFound, frontendURL+"/auth/callback?error=token_exchange_failed")
			return
		}

		// Step 5a: ask the provider "who is this user?"
		info, err := fetchUserInfo(token.AccessToken)
		if err != nil || info.Email == "" {
			c.Redirect(http.StatusFound, frontendURL+"/auth/callback?error=profile_fetch_failed")
			return
		}

		// Step 5b: find their account, or create one
		user, err := findOrCreateOAuthUser(provider, info)
		if err != nil {
			c.Redirect(http.StatusFound, frontendURL+"/auth/callback?error=account_creation_failed")
			return
		}

		// Same deactivated-account guard as normal login
		if !user.Active {
			c.Redirect(http.StatusFound, frontendURL+"/auth/callback?error=account_inactive")
			return
		}

		// Step 6a: issue the same kind of JWT as LoginWithToken
		jwtToken := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
			"sub": user.ID,
			"exp": time.Now().Add(time.Hour * 24 * 30).Unix(),
		})
		tokenString, _ := jwtToken.SignedString([]byte(config.JWTSecret))

		// Step 6b: hand the browser back to the frontend, JWT in tow
		c.Redirect(http.StatusFound, frontendURL+"/auth/callback?token="+tokenString)
	}
}

func findOrCreateOAuthUser(provider string, info *oauthUserInfo) (*models.User, error) {
	// 1. Seen this exact provider account before? → log into that row
	if user, err := findUserByProviderID(provider, info.ProviderUserID); err == nil {
		return user, nil
	}

	// 2. No? But is there already an account with this email?
	//    → LINK this provider to that existing row (no duplicate accounts!)
	var userByEmail models.User
	if err := initializers.DB.Where("email = ?", info.Email).First(&userByEmail).Error; err == nil {
		setProviderID(&userByEmail, provider, info.ProviderUserID)
		if userByEmail.Avatar == "" {
			userByEmail.Avatar = info.AvatarURL
		}
		if !userByEmail.IsEmailVerified() {
			now := time.Now()
			userByEmail.EmailVerifiedAt = &now // provider already verified this email
		}
		initializers.DB.Save(&userByEmail)
		return &userByEmail, nil
	}

	// 3. Nobody matched → brand-new person, create a fresh row
	now := time.Now()
	newUser := models.User{
		FirstName: info.FirstName, LastName: info.LastName,
		Email: info.Email, Role: models.RoleUser,
		Avatar: info.AvatarURL, Active: true,
		Provider: provider, EmailVerifiedAt: &now,
	}
	setProviderID(&newUser, provider, info.ProviderUserID)
	initializers.DB.Create(&newUser)
	return &newUser, nil
}

func FetchGoogleUserInfo(accessToken string) (*oauthUserInfo, error) {
	var raw struct {
		Sub        string `json:"sub"`
		Email      string `json:"email"`
		GivenName  string `json:"given_name"`
		FamilyName string `json:"family_name"`
		Picture    string `json:"picture"`
	}
	if err := fetchProviderJSON("https://www.googleapis.com/oauth2/v3/userinfo", accessToken, &raw); err != nil {
		return nil, err
	}
	return &oauthUserInfo{
		ProviderUserID: raw.Sub,
		Email:          raw.Email,
		FirstName:      raw.GivenName,
		LastName:       raw.FamilyName,
		AvatarURL:      raw.Picture,
	}, nil
}

package main

import (
	"log"

	"github.com/Watuulo-Richard/kooza-collins-portfolio-backend/config"
	"github.com/Watuulo-Richard/kooza-collins-portfolio-backend/initializers"
	"github.com/Watuulo-Richard/kooza-collins-portfolio-backend/models"
)

func init() {
	cfg, err := config.Load()
	if err != nil {
		log.Fatal("Failed to load config: ", err)
	}
	initializers.ConnectToDB(cfg)
}

func main() {
	log.Println("Starting database migration...")

	err := initializers.DB.AutoMigrate(
		&models.User{},
		&models.Project{},
		&models.ContactMessage{},
		&models.AuditLog{},
	)
	if err != nil {
		log.Fatal("Failed to migrate database:", err)
	}

	log.Println("Database migration completed successfully!")
}

go run ./migrations

package main

import (
	"log"

	"github.com/MUKE-coder/gorm-studio/studio"
	"github.com/Watuulo-Richard/kooza-collins-portfolio-backend/config"
	"github.com/Watuulo-Richard/kooza-collins-portfolio-backend/controllers"
	"github.com/Watuulo-Richard/kooza-collins-portfolio-backend/initializers"
	"github.com/Watuulo-Richard/kooza-collins-portfolio-backend/middleware"
	"github.com/Watuulo-Richard/kooza-collins-portfolio-backend/models"
	"github.com/gin-gonic/gin"
)

func init() {
	cfg, err := config.Load()
	if err != nil {
		log.Fatal("Failed to load config: ", err)
	}

	gin.SetMode(cfg.GinMode)

	initializers.ConnectToDB(cfg)
	initializers.InitAuditLogger()
	initializers.ConnectToRedis(cfg)
	initializers.InitMailer(cfg)
}

func main() {
	router := gin.Default()
	router.Use(middleware.CORSMiddleware()) // CORS for every route

	v1 := router.Group("/api/v1")
	{
		users := v1.Group("/users")
		{
			users.POST("", controllers.SignUpWithToken)
			users.POST("/login", controllers.LoginWithToken)
			users.GET("/validate", middleware.RequireAuthWithToken, controllers.ValidateUser)
			users.POST("/verify-email", controllers.VerifyEmail)
			users.POST("/resend-verification", controllers.ResendVerification)
			users.POST("/forgot-password", controllers.ForgotPassword)
			users.POST("/reset-password", controllers.ResetPassword)
		}

		contact := v1.Group("/contact")
		{
			contact.POST("", controllers.CreateContactMessage) // PUBLIC

			// ADMIN ONLY — the middleware chain protects these
			contact.GET("", middleware.RequireAuthWithToken, middleware.RequireAdmin(), controllers.GetContactMessages)
			contact.GET("/:id", middleware.RequireAuthWithToken, middleware.RequireAdmin(), controllers.GetContactMessage)
			contact.PATCH("/:id", middleware.RequireAuthWithToken, middleware.RequireAdmin(), controllers.UpdateContactMessage)
			contact.DELETE("/:id", middleware.RequireAuthWithToken, middleware.RequireAdmin(), controllers.DeleteContactMessage)
		}
	}

	// --- OAuth (social login) ---
	// IMPORTANT: the OAuth configs are built HERE, inside main(), NOT in a
	// package-level var. Package-level vars run BEFORE init() loads the .env,
	// so they'd always see empty client IDs. Calling the functions here,
	// after init() ran, sidesteps that completely.
	auth := v1.Group("/auth")
	{
		auth.GET("/google", controllers.OAuthLoginHandler(config.GoogleOAuthConfig()))
		auth.GET("/google/callback", controllers.OAuthCallbackHandler("google", config.GoogleOAuthConfig(), controllers.FetchGoogleUserInfo))

		auth.GET("/github", controllers.OAuthLoginHandler(config.GithubOAuthConfig()))
		auth.GET("/github/callback", controllers.OAuthCallbackHandler("github", config.GithubOAuthConfig(), controllers.FetchGithubUserInfo))

		// ...linkedin, spotify, discord follow the same two lines each...
	}

	// --- GORM Studio: a visual GUI for your database at /studio ---
	studio.Mount(router, initializers.DB, []interface{}{
		&models.User{},
		&models.Project{},
		&models.ContactMessage{},
		&models.AuditLog{},
	})

	router.Run() // starts the server on PORT (default 8080)
}

services:
  postgres:
    image: postgres:16-alpine
    profiles: ["infra"]
    restart: unless-stopped
    environment:
      POSTGRES_USER: kooza_collins
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: kooza_collins_db
    ports:
      - "5436:5432"   # 5436 on our machine → 5432 inside the container
    volumes:
      - postgres_data:/var/lib/postgresql/data   # survive container restarts
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U kooza_collins -d kooza_collins_db"]
      interval: 5s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    profiles: ["infra"]
    restart: unless-stopped
    command: redis-server --requirepass ${REDIS_PASSWORD} --appendonly yes
    ports:
      - "6380:6379"
    volumes:
      - redisdata:/data
    healthcheck:
      test: ['CMD', 'redis-cli', '-a', '${REDIS_PASSWORD}', 'ping']
      interval: 5s
      timeout: 5s
      retries: 5

  minio:
    image: minio/minio
    profiles: ["storage"]
    restart: unless-stopped
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin
    ports:
      - "9002:9000"   # API
      - "9003:9001"   # web console
    volumes:
      - minio_data:/data
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
      interval: 30s
      timeout: 20s
      retries: 3

  mailhog:
    image: mailhog/mailhog   # fake email inbox for development
    restart: unless-stopped
    ports:
      - "1026:1025"  # SMTP
      - "8026:8025"  # web UI

volumes:
  postgres_data:
  redisdata:
  minio_data:

docker compose --profile infra --profile storage up -d

docker compose --profile infra up -d          # api's essentials
docker compose --profile storage up -d        # uploads only
docker compose --profile infra --profile storage up -d   # everything

go run ./migrations

go run .

# Signup
curl -X POST http://localhost:8080/api/v1/users \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Kooza","last_name":"Collins","email":"k@gmail.com","password":"secret123"}'

# Login
curl -X POST http://localhost:8080/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{"email":"k@gmail.com","password":"secret123"}'

curl http://localhost:8080/api/v1/users/validate \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

go install github.com/air-verse/air@latest

air

package storage

// Storage provides S3-compatible file storage (AWS S3, MinIO, R2, B2).
func New(cfg config.StorageConfig) (*Storage, error) {
	// ...loads AWS SDK with custom endpoint + static credentials...

	client := s3.NewFromConfig(awsCfg, func(o *s3.Options) {
		o.UsePathStyle = true // Required for MinIO
	})

	// Verify the bucket exists, or create it
	_, err = client.HeadBucket(ctx, &s3.HeadBucketInput{Bucket: aws.String(cfg.Bucket)})
	if err != nil {
		client.CreateBucket(ctx, &s3.CreateBucketInput{Bucket: aws.String(cfg.Bucket)})
	}

	return &Storage{client: client, bucket: cfg.Bucket, cfg: cfg}, nil
}

func (s *Storage) Upload(ctx context.Context, key string, reader io.Reader, contentType string) error // PutObject
func (s *Storage) Download(ctx context.Context, key string) (io.ReadCloser, error)                    // GetObject
func (s *Storage) Delete(ctx context.Context, key string) error                                       // DeleteObject
func (s *Storage) GetURL(key string) string                                                           // build public URL

const MaxImageWidth = 1920
const ThumbnailSize = 300

// ProcessImage resizes images wider than 1920px, preserving aspect ratio.
func ProcessImage(reader io.Reader, mimeType string) ([]byte, error)

// GenerateThumbnail creates a square 300x300 thumbnail, center-cropped.
func GenerateThumbnail(reader io.Reader, mimeType string) ([]byte, error)

type UploadHandler struct {
	DB      *gorm.DB
	Storage *storage.Storage
	Jobs    *jobs.Client
}

// jobs.Client processes images in the BACKGROUND so the request
// doesn't wait for thumbnail generation.
func (c *Client) EnqueueProcessImage(uploadID uint, key, mimeType string) error {
	c.wg.Add(1)
	go func() {
		defer c.wg.Done()
		c.processImage(uploadID, key, mimeType)
	}()
	return nil
}

type Cache struct {
	client *redis.Client
}

func (c *Cache) Get(ctx context.Context, key string, dest interface{}) (bool, error)          // false if key missing
func (c *Cache) Set(ctx context.Context, key string, value interface{}, ttl time.Duration) error
func (c *Cache) Delete(ctx context.Context, key string) error
func (c *Cache) DeletePattern(ctx context.Context, pattern string) error // e.g. "contact:*"
func (c *Cache) Flush(ctx context.Context) error

type Logger struct {
	db *gorm.DB
}

func (l *Logger) Log(ctx context.Context, e Entry) error {
	// writes exactly one row to the audit_logs table
	// rows are only ever CREATED — never updated or deleted
}

# Start all infrastructure (database + storage + mailhog)
docker compose --profile infra --profile storage up -d

# Start the API with hot reload
air

# Run database migrations after changing models
go run ./migrations

# Just run once, no reload
go run .

# Stop everything
docker compose down

# Look at logs
docker compose logs -f

# Check for compile errors / bugs
go build ./...
go vet ./...