work-hub-server/openspec/changes/archive/2026-06-22-project-crud-sync/design.md

Context

The previous context remains: a unified technical layer for full CRUD operations is required for the Project resource across API and Web UI layers. The goal is to establish a canonical method for initializing a Project resource that can be consumed both programmatically (via API) and through the standard user interface. This requires centralizing validation and persistence logic.

Goals / Non-Goals

Goals:

• To expose a stable, RESTful endpoint (POST /api/v1/projects) for project creation.
• To ensure data consistency: any project created via the API must behave identically to one created via the Web UI (and vice versa).
• To establish project-creation as the single source of truth requirement for project setup.
• Local Development: The entire stack (API, Web, DB) must be orchestrated via Docker Compose to guarantee a reproducible and persistent development environment.

Non-Goals:

• Implementing granular ownership/permission checks within the creation payload itself; this should be handled by middleware/services post-creation.
• Handling advanced lifecycle events (e.g., project suspension) via the creation endpoint—these should use dedicated endpoints.

Decisions

• Architecture: The implementation must use a clear separation of concerns: Controllers handle HTTP concerns (routing, validation), Services encapsulate business logic, and Repositories handle data access. NestJS's module system enforces this structure naturally.
• Database Technology & Setup: PostgreSQL is mandated as the standard database engine for persistence. The root of the monorepo MUST have a docker-compose.yml dedicated to infrastructure services (Postgres, volumes). API and Web apps run natively via pnpm dev — no containerization for application code in development.
• Lifecycle Management: Database migrations (schema versioning) must be executed manually via a dedicated CLI tool. This is critical for controlling both local and production deployment processes.
• Input Validation Standard (NEW): Input validation for all API endpoints MUST be handled at the Controller level using Schema-Driven Pipes. All schemas used (Project DTOs, etc.) must be imported from and adhere to the contract defined in the shared @workspace/schema package.

Risks / Trade-offs

[Risk] The migration tooling might not cleanly support optional data seeding after a schema change. [Mitigation] We must provide clear setup steps in the final documentation (tasks.md) to ensure developers run migrations first, then seed scripts separately (and idempotently).