256 lines
9.3 KiB
Markdown
256 lines
9.3 KiB
Markdown
<!--
|
|
=====================================================================
|
|
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
|