foundary-test-1770773605/.sdlc/features/data-models/spec.md

Feature: Core Data Models & Persistence

Problem Statement

The studio application currently uses an in-memory storage adapter with a single example entity. To build real product functionality, the system needs persistent domain entities — Projects, Tasks, Labels, and Assignments — backed by PostgreSQL. Without these core data models, no meaningful product workflows (task management, project organization, label categorization, team assignment) can be built.

User Stories

• As a developer, I want Project, Task, Label, and Assignment entities with full CRUD so that the studio application has a foundation for product features.
• As a developer, I want PostgreSQL-backed persistence via studio-db so that data survives service restarts.
• As a developer, I want a repository layer with clean interfaces so that I can swap storage implementations and write testable code.
• As a developer, I want service-layer business logic so that domain rules (validation, uniqueness, referential integrity) are enforced consistently.
• As a developer, I want REST endpoints on studio-api so that frontends and external clients can manage these entities.
• As a developer, I want database migrations so that schema changes are versioned, repeatable, and safe to apply.
• As a developer, I want handler tests so that API behavior is verified and regressions are caught.

Domain Model

Project

Field	Type	Constraints
id	UUID	PK, generated
name	string	required, 1–200 chars, unique
description	string	optional, max 1000 chars
status	enum	active, archived; default active
created_at	timestamp	UTC, set on create
updated_at	timestamp	UTC, set on create/update

Task

Field	Type	Constraints
id	UUID	PK, generated
project_id	UUID	FK → projects, required
title	string	required, 1–300 chars
description	string	optional, max 5000 chars
status	enum	todo, in_progress, done; default todo
priority	enum	low, medium, high; default medium
position	integer	ordering within project, default 0
created_at	timestamp	UTC
updated_at	timestamp	UTC

Label

Field	Type	Constraints
id	UUID	PK, generated
project_id	UUID	FK → projects, required
name	string	required, 1–50 chars, unique per project
color	string	required, hex color (e.g., #FF5733)
created_at	timestamp	UTC
updated_at	timestamp	UTC

Assignment (join entity: Task ↔ User)

Field	Type	Constraints
id	UUID	PK, generated
task_id	UUID	FK → tasks, required
assignee	string	required, 1–200 chars (user identifier)
created_at	timestamp	UTC

Note: assignee is a string identifier (email or user ID) rather than a FK to a users table, since user management is out of scope for this feature. A unique constraint on (task_id, assignee) prevents duplicate assignments.

Acceptance Criteria

Migrations

• Migration 001_create_projects.sql creates the projects table with all fields, constraints, and indexes
• Migration 002_create_tasks.sql creates the tasks table with FK to projects, indexes on project_id and status
• Migration 003_create_labels.sql creates the labels table with FK to projects, unique constraint on (project_id, name)
• Migration 004_create_assignments.sql creates the assignments table with FK to tasks, unique constraint on (task_id, assignee)
• Migrations run via the existing database.MustRunMigrations() system with embedded SQL files
• All migrations are idempotent and run in transactions

Domain Layer

• Domain entities Project, Task, Label, Assignment defined with strongly-typed IDs (e.g., ProjectID, TaskID)
• Domain constructors (NewProject, NewTask, NewLabel, NewAssignment) validate all required fields
• Domain errors defined: ErrProjectNotFound, ErrTaskNotFound, ErrLabelNotFound, ErrAssignmentNotFound, ErrDuplicateProjectName, ErrDuplicateLabelName, ErrDuplicateAssignment, ErrInvalidStatus, ErrInvalidPriority
• Update methods validate mutable fields and set updated_at

Repository Layer (Ports)

• ProjectRepository interface with List, Get, Create, Update, Delete, ExistsByName
• TaskRepository interface with ListByProject, Get, Create, Update, Delete
• LabelRepository interface with ListByProject, Get, Create, Update, Delete, ExistsByName
• AssignmentRepository interface with ListByTask, Get, Create, Delete, ExistsByTaskAndAssignee

Adapter Layer (Postgres)

• adapter/postgres/ package implementing all repository interfaces using sqlx
• Proper SQL parameterization ($1, $2, etc.) — no string concatenation
• sql.ErrNoRows mapped to domain ErrNotFound errors
• Unique constraint violations mapped to domain duplicate errors

Service Layer

• ProjectService with Create (duplicate name check), Get, List, Update, Delete (cascade consideration)
• TaskService with Create (validate project exists), Get, ListByProject, Update, Delete
• LabelService with Create (validate project exists, duplicate name per project), Get, ListByProject, Update, Delete
• AssignmentService with Create (validate task exists, duplicate check), ListByTask, Delete

Handler Layer (REST API)

• Projects: POST /api/studio-api/projects, GET /api/studio-api/projects, GET /api/studio-api/projects/{id}, PUT /api/studio-api/projects/{id}, DELETE /api/studio-api/projects/{id}
• Tasks: POST /api/studio-api/projects/{projectId}/tasks, GET /api/studio-api/projects/{projectId}/tasks, GET /api/studio-api/tasks/{id}, PUT /api/studio-api/tasks/{id}, DELETE /api/studio-api/tasks/{id}
• Labels: POST /api/studio-api/projects/{projectId}/labels, GET /api/studio-api/projects/{projectId}/labels, GET /api/studio-api/labels/{id}, PUT /api/studio-api/labels/{id}, DELETE /api/studio-api/labels/{id}
• Assignments: POST /api/studio-api/tasks/{taskId}/assignments, GET /api/studio-api/tasks/{taskId}/assignments, DELETE /api/studio-api/assignments/{id}
• All handlers follow app.Wrap() + app.BindAndValidate() pattern
• All responses use httpresponse.OK, httpresponse.Created, httpresponse.NoContent envelope
• URL parameters use {param} brace syntax, extracted with chi.URLParam()
• Domain errors mapped to HTTP errors via mapDomainError() functions

OpenAPI Specification

• All schemas defined in spec.go using openapi.* helpers
• All endpoints documented with request/response types, status codes, and tags
• Tags: Projects, Tasks, Labels, Assignments

Tests

• Handler tests for all CRUD operations on each entity using mock repositories
• Table-driven tests covering: success, not found, validation failure, duplicate/conflict
• Test setup uses newTestHandler() pattern with mock repositories
• Tests use chi.NewRouter() + httptest for HTTP testing

Wiring

• main.go updated to: connect to database, run migrations, create postgres adapters, inject into services and handlers
• Database connection uses config.ReadDatabaseConfig() + database.MustConnect()
• Migrations embedded with //go:embed migrations/*.sql
• Graceful shutdown closes database pool

Technical Constraints

• Database: PostgreSQL via sqlx + lib/pq driver (already in pkg/database)
• Migration system: Embedded SQL files using database.MustRunMigrations() — no external migration tool
• Architecture: Hexagonal architecture — domain has no external dependencies; ports define interfaces; adapters implement them
• Routing: chi router with {param} brace syntax; all handlers return error wrapped with app.Wrap()
• Validation: Struct tags using go-playground/validator via app.BindAndValidate()
• ID generation: UUIDs generated server-side (e.g., uuid.New().String())
• Timestamps: All UTC, set by domain constructors
• Cascading deletes: Deleting a project should delete its tasks, labels, and associated assignments (via ON DELETE CASCADE in FK constraints)

Dependencies

• pkg/database — PostgreSQL connection pool and migration runner (exists)
• pkg/config — Database URL and pool configuration (exists)
• pkg/app — Handler wrapping, binding, routing (exists)
• pkg/httperror, pkg/httpresponse, pkg/httpvalidation — HTTP layer helpers (exists)
• pkg/openapi — API documentation (exists)
• Running PostgreSQL instance for local development and integration tests
• github.com/google/uuid — UUID generation (add to go.mod if not present)

Out of Scope

• User management / authentication: assignee is a plain string, not a FK to a users table. Auth middleware integration is not part of this feature.
• Pagination: List endpoints return all records. Pagination will be a follow-up feature.
• Filtering/sorting: List endpoints are unfiltered. Query parameters for filtering by status, priority, etc. will be a follow-up.
• Task-Label association: Many-to-many relationship between tasks and labels (a task_labels join table) is not included. This is a follow-up feature.
• Soft deletes: All deletes are hard deletes. Soft delete (archive) behavior may be added later.
• Audit logging: No change tracking or audit trail in this feature.
• Frontend integration: No UI changes. This is backend-only.

Open Questions

1. Delete cascade vs. restrict: Should deleting a project cascade-delete all tasks, labels, and assignments? The spec assumes ON DELETE CASCADE, but an alternative is to return an error if a project has tasks (forcing explicit cleanup). Which behavior is preferred?

2. Assignment entity vs. simple field: Should task assignment be a separate entity with its own table (supporting multiple assignees per task), or a simple assignee string field on the Task table (single assignee)? The spec assumes a separate join entity for multiple assignees.

3. Task position/ordering: The spec includes a position integer for ordering tasks within a project. Should this be included in the initial implementation, or deferred until a drag-and-drop UI feature is built?

4. Project status transitions: Should there be business rules governing status transitions (e.g., can only archive a project if all tasks are done)? The spec currently allows free status changes.

5. Database name: The requirements mention studio-db as the database. Should this be a new PostgreSQL database name, or should it refer to the database configured in DATABASE_URL? The spec assumes the existing DATABASE_URL configuration.