Add .specify and .claude configuration

2026-01-29 12:25:57 -03:00
parent 7392e885fd
commit 7fe3c15c37
21 changed files with 3674 additions and 0 deletions
--- a/.specify/memory/constitution.md
+++ b/.specify/memory/constitution.md
@@ -0,0 +1,255 @@
+<!--
+=====================================================================
+SYNC IMPACT REPORT
+=====================================================================
+Version change: 1.0.0 → 1.1.0 (MINOR: Added shadcn/ui component library)
+
+Modified principles:
+- III. Styling → III. Styling & UI Components (expanded scope)
+
+Added sections:
+- shadcn/ui configuration and usage guidelines
+- UI component library in Tech Stack
+- components/ui/ directory in Project Structure
+
+Removed sections: None
+
+Templates requiring updates:
+- .specify/templates/plan-template.md ✅ (compatible - no changes needed)
+- .specify/templates/spec-template.md ✅ (compatible - no changes needed)
+- .specify/templates/tasks-template.md ✅ (compatible - no changes needed)
+
+Follow-up TODOs: None
+=====================================================================
+-->
+
+# ThumbPreview Constitution
+
+## Core Principles
+
+### I. Tech Stack
+
+All new code MUST use the established technology stack:
+
+**Frontend (React SPA):**
+- React 19.x with TypeScript 5.x
+- Vite as build tool with HMR
+- Tailwind CSS 4.x for styling
+- shadcn/ui for UI components (Radix UI primitives)
+- Zustand for client state management
+- @tanstack/react-query for server state
+- Axios for HTTP requests
+- lucide-react for icons
+
+**Backend (NestJS API):**
+- NestJS 11.x with TypeScript 5.x
+- Express via @nestjs/platform-express
+- PostgreSQL with TypeORM
+- class-validator and class-transformer for DTOs
+- Multer for file uploads
+- Sharp for image processing
+
+**Rationale:** Consistent tooling reduces onboarding friction, ensures compatibility,
+and enables shared patterns across the codebase.
+
+### II. Architecture & Project Structure
+
+This is a **monorepo** with separate frontend and backend packages. New code MUST
+follow the established directory organization:
+
+**Frontend (`/frontend/src/`):**
+- `components/` - Application React UI components
+- `components/ui/` - shadcn/ui primitive components (auto-generated)
+- `hooks/` - Custom React hooks (useX naming)
+- `store/` - Zustand state stores
+- `api/` - Axios client and API methods
+- `types/` - TypeScript interfaces and types
+- `lib/` - Utility functions (includes `utils.ts` for cn() helper)
+- `assets/` - Static images and resources
+
+**Backend (`/backend/src/`):**
+- `modules/` - Feature modules (NestJS module pattern)
+  - Each module contains: `*.module.ts`, `*.controller.ts`, `*.service.ts`
+- `entities/` - TypeORM entity definitions
+
+**Configuration Files:**
+- `components.json` - shadcn/ui configuration (registry, aliases, styling)
+- `tsconfig.json` - Must include `@/*` path alias for shadcn imports
+
+**Rules:**
+- One component/hook/service per file
+- Feature-based module organization in backend
+- Clear separation between API, state, and presentation layers
+- All imports MUST use `@/` alias for shadcn components and lib utilities
+- Application components use relative imports within packages
+
+**Rationale:** Predictable structure enables faster navigation and reduces
+cognitive load when adding features.
+
+### III. Styling & UI Components
+
+All styling MUST use Tailwind CSS utility classes combined with shadcn/ui:
+
+**shadcn/ui Usage:**
+- Use shadcn/ui components for standard UI elements (Button, Card, Input, etc.)
+- Install components via `npx shadcn@latest add <component>`
+- Components installed to `src/components/ui/` - DO NOT modify generated files
+- Use shadcn MCP server for component discovery and installation commands
+- Compose shadcn components with application-specific styling via className prop
+
+**Tailwind Integration:**
+- Import Tailwind via `@import "tailwindcss"` in index.css
+- CSS variables defined in index.css for theming (--primary, --background, etc.)
+- Use `cn()` utility from `@/lib/utils` for conditional class merging
+- Dark mode via `class="dark"` on html element
+- Follow established color scheme via CSS variables
+
+**Styling Rules:**
+- Prefer shadcn/ui components over custom implementations
+- Use Tailwind utilities for layout, spacing, and custom styling
+- Use CSS variables (--primary, --muted-foreground, etc.) for colors
+- Use Tailwind's responsive breakpoints (sm, md, lg, xl) for layouts
+
+**Forbidden:**
+- Inline style objects except for dynamic values (e.g., computed widths)
+- Creating new CSS files for component-specific styles
+- Using `!important` overrides
+- CSS Modules, styled-components, or CSS-in-JS libraries
+- Modifying files in `components/ui/` directory
+
+**Icon Usage:**
+- Use lucide-react for all icons
+- Import icons individually: `import { IconName } from 'lucide-react'`
+- Use `size-X` or `className="size-X"` for icon sizing
+
+**Rationale:** shadcn/ui provides accessible, well-designed primitives while
+Tailwind enables customization. This combination ensures consistency and
+reduces custom CSS maintenance.
+
+### IV. Data Management
+
+**Frontend State:**
+- Use Zustand for UI/client state (view mode, selections, form data)
+- Use React Query for server state (API data, caching, mutations)
+- Define all store actions in the store file, not in components
+- React Query stale time: 1 hour for search results
+
+**Backend Storage:**
+- PostgreSQL for persistent data (via TypeORM)
+- UUID primary keys for all entities
+- File uploads stored in `/backend/uploads/` directory
+- YouTube API responses cached in database with 24-hour TTL
+
+**Environment Configuration:**
+- Backend: Use @nestjs/config with .env files
+- Frontend: Use Vite proxy for API calls (no .env needed)
+- Never commit .env files or API keys
+
+**Rationale:** Clear boundaries between client and server state prevent
+synchronization bugs and simplify debugging.
+
+### V. Development Practices
+
+**TypeScript:**
+- Strict mode enabled for frontend application code
+- All new code MUST have explicit type annotations for function parameters
+- Use interfaces for object shapes, types for unions/aliases
+- No `any` type except in exceptional cases with justification
+- Path aliases MUST be configured: `@/*` → `./src/*`
+
+**Linting & Formatting:**
+- Frontend: ESLint with React hooks and React Refresh plugins
+- Backend: ESLint + Prettier (singleQuote, trailingComma: all)
+- Run `npm run lint` before committing
+- Run `npm run format` (backend) for consistent formatting
+
+**Testing (Backend):**
+- Jest for unit and integration tests
+- Test files: `*.spec.ts` adjacent to source files
+- Run `npm run test` for test suite
+
+**Validation:**
+- Backend: Use class-validator decorators on all DTOs
+- Global validation pipe enabled (whitelist + transform)
+- File uploads: Validate MIME types (JPEG, PNG, WebP only, 5MB max)
+
+**Rationale:** Consistent quality standards prevent regressions and
+maintain code health over time.
+
+## Technology Stack Reference
+
+| Layer | Technology | Version | Purpose |
+|-------|------------|---------|---------|
+| Frontend Runtime | React | 19.x | UI library |
+| Frontend Build | Vite | 7.x | Build + HMR |
+| Frontend Styling | Tailwind CSS | 4.x | Utility CSS |
+| Frontend UI | shadcn/ui | 3.x | Component library |
+| Frontend Icons | lucide-react | latest | Icon library |
+| Frontend State | Zustand | 5.x | Client state |
+| Frontend Data | React Query | 5.x | Server state |
+| Backend Framework | NestJS | 11.x | API server |
+| Backend Database | PostgreSQL | 16 | Data persistence |
+| Backend ORM | TypeORM | 0.3.x | DB abstraction |
+| Runtime | Node.js | 20+ | Server runtime |
+
+New dependencies MUST be justified and reviewed for:
+- Compatibility with existing versions
+- Bundle size impact (frontend)
+- Maintenance status (active development, security updates)
+- License compatibility (MIT preferred)
+
+**shadcn/ui Component Installation:**
+```bash
+# List available components
+npx shadcn@latest add --help
+
+# Add a component (use shadcn MCP for discovery)
+npx shadcn@latest add button card input --yes
+
+# Components are added to src/components/ui/
+```
+
+## Code Quality Standards
+
+**Pull Request Checklist:**
+1. Code follows architecture patterns (correct directory placement)
+2. Styling uses Tailwind utilities and/or shadcn components
+3. TypeScript types are explicit (no implicit any)
+4. Linter passes with no errors
+5. New backend endpoints include validation
+6. Environment variables documented if added
+7. shadcn components used for standard UI elements
+
+**Commit Guidelines:**
+- Use conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`
+- Reference issue numbers when applicable
+- Keep commits focused (one logical change per commit)
+
+**Code Review Focus Areas:**
+- Security: No hardcoded credentials, proper input validation
+- Performance: Avoid unnecessary re-renders, efficient queries
+- Maintainability: Clear naming, appropriate abstractions
+- UI Consistency: Use shadcn components, follow established patterns
+
+## Governance
+
+This constitution establishes non-negotiable development standards for the
+ThumbPreview project. All contributors MUST adhere to these principles.
+
+**Amendment Process:**
+1. Propose changes via pull request to this file
+2. Document rationale for changes
+3. Increment version according to semver rules
+4. Update dependent templates if principle changes affect them
+
+**Version Policy:**
+- MAJOR: Backward-incompatible changes (removing principles, changing stack)
+- MINOR: New principles or significant expansions
+- PATCH: Clarifications, typo fixes, non-semantic refinements
+
+**Compliance:**
+- All PRs MUST pass constitution checks before merge
+- Violations require explicit justification in PR description
+- Repeated violations should trigger constitution review
+
+**Version**: 1.1.0 | **Ratified**: 2026-01-29 | **Last Amended**: 2026-01-29