[projects] introduce module

go.mod

@@ -16,6 +16,7 @@ require (
 	github.com/gofiber/fiber/v2 v2.52.12
 	github.com/golang-jwt/jwt/v5 v5.3.1
 	github.com/google/uuid v1.6.0
+	github.com/gosimple/slug v1.15.0
 	github.com/pressly/goose/v3 v3.27.0
 	github.com/prometheus/client_golang v1.23.2
 	github.com/samber/lo v1.52.0
@@ -50,6 +51,7 @@ require (
 	github.com/go-viper/mapstructure/v2 v2.4.0 // indirect
 	github.com/gofiber/contrib/fiberzap/v2 v2.1.6 // indirect
 	github.com/gofiber/swagger v1.1.1 // indirect
+	github.com/gosimple/unidecode v1.0.1 // indirect
 	github.com/jinzhu/inflection v1.0.0 // indirect
 	github.com/joho/godotenv v1.5.1 // indirect
 	github.com/josharian/intern v1.0.0 // indirect

go.sum

@@ -84,6 +84,10 @@ github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/gosimple/slug v1.15.0 h1:wRZHsRrRcs6b0XnxMUBM6WK1U1Vg5B0R7VkIf1Xzobo=
+github.com/gosimple/slug v1.15.0/go.mod h1:UiRaFH+GEilHstLUmcBgWcI42viBN7mAb818JrYOeFQ=
+github.com/gosimple/unidecode v1.0.1 h1:hZzFTMMqSswvf0LBJZCZgThIZrpDHFXux9KeGmn6T/o=
+github.com/gosimple/unidecode v1.0.1/go.mod h1:CP0Cr1Y1kogOtx0bJblKzsVWrqYaqfNOnHzpgWw4Awc=
 github.com/jinzhu/inflection v1.0.0 h1:K317FqzuhWc8YvSVlFMCCUb36O/S9MCKRDI7QkRKD/E=
 github.com/jinzhu/inflection v1.0.0/go.mod h1:h+uFLlag+Qp1Va5pdKtLDYj+kHp5pxUVkryuEj+Srlc=
 github.com/joho/godotenv v1.5.1 h1:7eLL/+HRGLY0ldzfGMeQkb7vMd0as4CfYvUVzLqw0N0=

internal/app.go

@@ -6,6 +6,7 @@ import (
 	"github.com/bit-issues/backend/internal/config"
 	"github.com/bit-issues/backend/internal/db"
 	"github.com/bit-issues/backend/internal/jwt"
+	"github.com/bit-issues/backend/internal/projects"
 	"github.com/bit-issues/backend/internal/server"
 	"github.com/bit-issues/backend/internal/users"
 	"github.com/go-core-fx/bunfx"
@@ -50,6 +51,7 @@ func Run(version healthfx.Version) {
 		fx.Supply(version),
 		jwt.Module(),
 		users.Module(),
+		projects.Module(),
 		//
 		fx.Invoke(func(lc fx.Lifecycle, logger *zap.Logger) {
 			lc.Append(fx.Hook{

internal/db/migrations/20260413013944_create_projects.sql

@@ -0,0 +1,17 @@
+-- +goose Up
+-- +goose StatementBegin
+CREATE TABLE `projects` (
+    `id` VARCHAR(255) NOT NULL,
+    `name` VARCHAR(255) NOT NULL,
+    `repo_url` VARCHAR(512) NOT NULL,
+    `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `idx_projects_name` (`name`)
+) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COLLATE = utf8mb4_unicode_ci;
+-- +goose StatementEnd
+---
+-- +goose Down
+-- +goose StatementBegin
+DROP TABLE `projects`;
+-- +goose StatementEnd

internal/projects/config.go

@@ -0,0 +1,9 @@
+package projects
+
+// Config holds configuration for the projects module.
+// Currently empty as no module-specific configuration is needed for MVP.
+// This struct can be extended in the future for feature flags or
+// other configurable aspects.
+type Config struct {
+	// Example: MaxProjectsPerPage int `env:"MAX_PROJECTS_PER_PAGE" default:"100"`
+}

internal/projects/doc.go

@@ -0,0 +1,33 @@
+// Package projects provides project management functionality for the
+// Corporate Task Tracker. Projects serve as containers for tasks and
+// are linked to external BitBucket repositories.
+//
+// The projects module follows a clean architecture pattern with clear
+// separation between domain logic, data access, and HTTP presentation.
+//
+// Domain Layer:
+//   - Project: Core business entity
+//   - ProjectInput: Data for creating projects
+//   - ProjectUpdate: Data for updating projects
+//
+// Repository Layer:
+//   - Handles all database operations
+//   - Uses Bun ORM for type-safe queries
+//
+// Service Layer:
+//   - Implements business rules and validation
+//   - Validates repository URLs
+//   - Ensures name uniqueness
+//
+// HTTP Layer:
+//   - RESTful API endpoints
+//   - Admin-only write operations
+//   - Authenticated read operations
+//
+// Usage:
+//
+//	app := fx.New(
+//	    projects.Module(),
+//	    // other modules...
+//	)
+package projects

internal/projects/domain.go

@@ -0,0 +1,100 @@
+package projects
+
+import (
+	"fmt"
+	"net/url"
+	"strings"
+	"time"
+)
+
+// Project represents the core business entity for a project.
+// A project is a container for tasks and is linked to a BitBucket repository.
+type Project struct {
+	ID        string    // Primary key
+	Name      string    // Unique project name
+	RepoURL   string    // BitBucket repository URL
+	CreatedAt time.Time // Creation timestamp
+	UpdatedAt time.Time // Last update timestamp
+}
+
+// ProjectInput represents the data required to create a new project.
+// All fields are required and must be validated before creation.
+type ProjectInput struct {
+	Name    string // Unique project name, required
+	RepoURL string // BitBucket repository URL, required
+}
+
+// ProjectUpdate represents the data that can be updated for a project.
+// All fields are optional (pointers) to support partial updates.
+type ProjectUpdate struct {
+	Name    *string // Optional new name, must be unique if provided
+	RepoURL *string // Optional new repository URL, must be valid if provided
+}
+
+// Validate checks if the input data is valid for creating a new project.
+func (i ProjectInput) Validate() error {
+	// Trim and validate name
+	name := strings.TrimSpace(i.Name)
+	if name == "" {
+		return fmt.Errorf("%w: project name is required", ErrValidationFailed)
+	}
+
+	// Validate repository URL
+	repoURL := strings.TrimSpace(i.RepoURL)
+	if err := validateRepoURL(repoURL); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+// IsEmpty returns true if no update fields are set.
+// This prevents unnecessary database operations when no data is provided.
+func (u ProjectUpdate) IsEmpty() bool {
+	return u.Name == nil && u.RepoURL == nil
+}
+
+func (u ProjectUpdate) Validate() error {
+	if u.Name != nil {
+		// Trim and validate name
+		name := strings.TrimSpace(*u.Name)
+		if name == "" {
+			return fmt.Errorf("%w: project name is required", ErrValidationFailed)
+		}
+	}
+
+	if u.RepoURL != nil {
+		// Validate repository URL
+		repoURL := strings.TrimSpace(*u.RepoURL)
+		if err := validateRepoURL(repoURL); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+// validateRepoURL validates that the repository URL is in a valid format.
+// Accepts HTTPS URLs (https://bitbucket.org/...).
+func validateRepoURL(repoURL string) error {
+	if repoURL == "" {
+		return fmt.Errorf("%w: repository URL is required", ErrValidationFailed)
+	}
+
+	u, err := url.Parse(repoURL)
+	if err != nil {
+		return fmt.Errorf("%w: failed to parse repository URL: %w", ErrValidationFailed, err)
+	}
+
+	// Accept HTTPS scheme
+	if u.Scheme != "https" {
+		return fmt.Errorf("%w: repository URL must be in HTTPS format", ErrValidationFailed)
+	}
+
+	// Basic validation: must have host
+	if u.Host == "" {
+		return fmt.Errorf("%w: repository URL must have a host", ErrValidationFailed)
+	}
+
+	return nil
+}

internal/projects/errors.go

@@ -0,0 +1,19 @@
+package projects
+
+import "errors"
+
+var (
+	// ErrValidationFailed is returned when input data fails validation.
+	ErrValidationFailed = errors.New("validation failed")
+
+	// ErrNotFound is returned when a project with the given ID does not exist.
+	ErrNotFound = errors.New("project not found")
+
+	// ErrNameAlreadyUsed is returned when attempting to create or update
+	// a project with a name that is already in use by another project.
+	ErrNameAlreadyUsed = errors.New("project name already in use")
+
+	// ErrInvalidURL is returned when the repository URL is not in a valid
+	// format.
+	ErrInvalidURL = errors.New("invalid repository URL")
+)

internal/projects/models.go

@@ -0,0 +1,52 @@
+package projects
+
+import (
+	"time"
+
+	"github.com/go-core-fx/bunfx"
+	"github.com/uptrace/bun"
+	"github.com/uptrace/bun/schema"
+)
+
+// projectModel is the database representation of a project.
+// This struct is used for Bun ORM operations and maps to the `projects` table.
+type projectModel struct {
+	bun.BaseModel `bun:"table:projects,alias:p"`
+	bunfx.TimedModel
+
+	ID      string `bun:"id,pk"` // Primary key
+	Name    string `bun:"name,notnull,unique"`
+	RepoURL string `bun:"repo_url,notnull"`
+}
+
+// newProjectModel creates a new projectModel from a ProjectInput.
+// It automatically sets the ID from the name and timestamps.
+func newProjectModel(input ProjectInput, slug string) *projectModel {
+	now := time.Now()
+	return &projectModel{
+		BaseModel: schema.BaseModel{},
+		TimedModel: bunfx.TimedModel{
+			CreatedAt: now,
+			UpdatedAt: now,
+		},
+
+		ID:      slug,
+		Name:    input.Name,
+		RepoURL: input.RepoURL,
+	}
+}
+
+// toDomain converts the database model to a domain Project entity.
+// Returns nil if the model is nil.
+func (m *projectModel) toDomain() *Project {
+	if m == nil {
+		return nil
+	}
+	return &Project{
+		ID:        m.ID,
+		Name:      m.Name,
+		RepoURL:   m.RepoURL,
+		CreatedAt: m.CreatedAt,
+		UpdatedAt: m.UpdatedAt,
+	}
+}

internal/projects/module.go

@@ -0,0 +1,28 @@
+package projects
+
+import (
+	"github.com/go-core-fx/logger"
+	"go.uber.org/fx"
+)
+
+// Module creates and returns an FX module for the projects package.
+// This module wires up all dependencies for the projects functionality:
+//   - Repository (private): Data access layer, only used within this module
+//   - Service (public): Business logic layer, can be injected into other modules
+//
+// The module also registers a named logger for structured logging.
+func Module() fx.Option {
+	return fx.Module(
+		"projects",
+		// Add a named logger for this module
+		logger.WithNamedLogger("projects"),
+
+		// Provide the repository as a private dependency
+		// This means it can only be used within this module
+		fx.Provide(NewRepository, fx.Private),
+
+		// Provide the service as a public dependency
+		// This means it can be injected into other modules (e.g., tasks module)
+		fx.Provide(NewService),
+	)
+}