frontend/.specify/memory/constitution.md

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:

# 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