diff --git a/.github/.copilot-instructions.md b/.github/.copilot-instructions.md index 528635b..64bc8dd 100644 --- a/.github/.copilot-instructions.md +++ b/.github/.copilot-instructions.md @@ -22,19 +22,34 @@ Produce production-grade changes that are correct, verifiable, maintainable, and - **Git Hooks**: Lefthook (lefthook.yml) ### Key Dependencies & Tools -- NestJS + Prisma (backend data access) -- Next.js 14+ with App Router -- Expo + Expo Router -- class-validator, class-transformer (DTOs) -- Biome for linting + formatting -- Jest for unit/integration tests -- TypeScript strict mode enabled +- **Backend (apps/api)**: + - NestJS 11.0.1 + - Prisma ORM 7.4.2 with @prisma/client 7.4.2 + - TypeScript 5.7.3 + - Jest 30.0.0 + - class-validator & class-transformer (DTOs) +- **Frontend (apps/frontend)**: + - Next.js 16.1.6 with App Router + - React 19.2.3 + - Tailwind CSS 4 + - Jest 30.2.0 + - TypeScript 5 +- **Mobile (apps/mobile)**: + - Expo 55.0.5 with Expo Router + - React Native 0.83.2 + - React 19.2.0 +- **Tooling**: + - Biome 2.4.6 (linting + formatting) + - Turbo 2.8.13 (monorepo orchestration) + - Lefthook 2.1.2 (git hooks) + - TypeScript strict mode enabled across all apps ### Runtime & Package Manager -- **Node.js**: 24.x (see `.nvmrc`) +- **Node.js**: v24.14.0 (see `.nvmrc` for version pinning) - **Package Manager**: pnpm@10.30.3 - **Commands**: `pnpm dev`, `pnpm test`, `pnpm lint`, `pnpm build` - **Monorepo Command**: `pnpm --filter ` + - Workspace names: `api`, `frontend`, `mobile` - **Turbo Commands**: `turbo run ` (respects pnpm workspaces) ### Production Deployment @@ -78,10 +93,10 @@ A task is complete only when all applicable items pass: 1. ✓ Requested behavior implemented. 2. ✓ All touched files are lint/error clean (run `pnpm lint` or `pnpm --filter run biome check --write`). 3. ✓ Tests relevant to the change pass: - - Backend: `pnpm --filter @dpep/api test` (or targeted test file) + - Backend: `pnpm --filter api test` (or targeted test file) - Frontend: `pnpm --filter frontend test` (if test harness exists) - Mobile: `pnpm --filter mobile test` (if test harness exists) -4. ✓ Coverage for touched backend files is at least 90% when running `pnpm --filter @dpep/api run test:cov`. +4. ✓ Coverage for touched backend files is at least 90% when running `pnpm --filter api run test:cov`. 5. ✓ No duplicated logic introduced when a reusable abstraction is appropriate. 6. ✓ Public API changes include all call-site and type updates across apps. 7. ✓ Final diff is minimal and free of unrelated edits. @@ -103,13 +118,13 @@ A task is complete only when all applicable items pass: ``` 5. If Prisma schema changes (backend only): ```bash - pnpm --filter @dpep/api run prisma migrate dev --name - pnpm --filter @dpep/api run prisma generate + pnpm --filter api run prisma:migrate:dev --name + pnpm --filter api run prisma:generate ``` 6. Run focused tests for changed behavior: ```bash # Backend - pnpm --filter @dpep/api test -- + pnpm --filter api test -- # Frontend pnpm --filter frontend test -- @@ -121,7 +136,7 @@ A task is complete only when all applicable items pass: ### Verification 7. Run coverage checks when available (backend): ```bash - pnpm --filter @dpep/api run test:cov + pnpm --filter api run test:cov ``` - Refactor if quality gates fail (aim for ≥90% coverage on touched files). 8. Finalize only after all gates pass. @@ -138,10 +153,11 @@ A task is complete only when all applicable items pass: ## 6. Code Purity and Output Rules - Generate raw executable code only. -- **Forbidden**: commented-out code, inline rationale comments, placeholder comments. +- **Forbidden**: commented-out code, inline rationale comments, placeholder comments, emojis. - **Allowed**: required JSDoc/docstrings explaining non-obvious logic. - Keep code deterministic, explicit, and readable. - Follow Biome's auto-formatting output; do not argue style choices. +- Never use emojis in code, documentation, commit messages, or any project files. --- @@ -157,11 +173,17 @@ A task is complete only when all applicable items pass: ### 7.2 Prisma and Data Access -- Use Prisma client for data access; avoid raw SQL unless strictly necessary. +- **Prisma v7 Configuration**: + - Connection URL configured in `apps/api/prisma.config.ts` (NOT in schema file) + - Config file loads root `.env` from `../../.env` + - Schema location: `apps/api/prisma/schema.prisma` + - Migrations: `apps/api/prisma/migrations/` +- Use Prisma Client for data access; avoid raw SQL unless strictly necessary. - Model relations in Prisma schema, not as loose id fields. - Use transactions for multi-step writes. - Avoid N+1 queries: use `include`/`select` and batching. - Keep Prisma schema well-organized by model. +- Always use workspace scripts: `prisma:generate`, `prisma:migrate:dev`, `prisma:studio` ### 7.3 Auth, Cache, and Integrations @@ -171,9 +193,10 @@ A task is complete only when all applicable items pass: ### 7.4 Migrations -- Always generate migrations via `prisma migrate dev --name `. -- Never hand-edit migration files. -- Commit both schema and migration files. +- Always generate migrations via `pnpm --filter api run prisma:migrate:dev --name `. +- Never hand-edit migration files unless absolutely necessary for data migration. +- Commit schema, config, and migration files together. +- For production: use `pnpm --filter api run prisma:migrate:deploy`. ### 7.5 Error Handling @@ -285,11 +308,11 @@ import { MyService } from './my.service'; ### 12.1 Baseline Requirements -- **Backend changes**: run targeted `pnpm --filter @dpep/api test ` or E2E tests if relevant. +- **Backend changes**: run targeted `pnpm --filter api test ` or E2E tests if relevant. - **Frontend changes**: run relevant tests if a harness exists (`pnpm --filter frontend test`). - **Mobile changes**: run relevant tests if a harness exists (`pnpm --filter mobile test`). - **All changes**: always run Biome lint checks on touched files and pass all formatting. -- **Backend logic changes**: run `pnpm --filter @dpep/api run test:cov` to verify coverage ≥90%. +- **Backend logic changes**: run `pnpm --filter api run test:cov` to verify coverage ≥90%. ### 12.2 Required Test Scenarios by Change Type @@ -374,10 +397,11 @@ pnpm dev # Start dev servers (Turbo orchestrated) ### Workspace-Specific ```bash # Backend (apps/api) -pnpm --filter @dpep/api test -pnpm --filter @dpep/api run test:cov -pnpm --filter @dpep/api run prisma migrate dev --name -pnpm --filter @dpep/api run prisma studio +pnpm --filter api test +pnpm --filter api run test:cov +pnpm --filter api run prisma:migrate:dev --name +pnpm --filter api run prisma:studio +pnpm --filter api run prisma:generate # Frontend (apps/frontend) pnpm --filter frontend dev @@ -411,7 +435,11 @@ pnpm dev # Check Turbo cache turbo --version -turbo prune --docker --scope=@dpep/api # For monorepo analysis +turbo prune --docker --scope=api # For monorepo analysis + +# Prisma-specific troubleshooting +pnpm --filter api run prisma:generate # Regenerate client +pnpm --filter api exec prisma validate --config prisma.config.ts # Validate schema ``` --- diff --git a/README.md b/README.md new file mode 100644 index 0000000..0fb5ede --- /dev/null +++ b/README.md @@ -0,0 +1,386 @@ +# Blog Nest + +A modern full-stack blog platform built with TypeScript, featuring a NestJS backend API, Next.js web frontend, and Expo mobile app. + +## Tech Stack + +### Backend (API) +- **NestJS** 11.0.1 - Progressive Node.js framework +- **Prisma ORM** 7.4.2 - Type-safe database access +- **PostgreSQL** 17 - Primary database +- **Redis** 7 - Caching layer +- **TypeScript** 5.7.3 - Static typing +- **Jest** 30.0.0 - Testing framework + +### Frontend (Web) +- **Next.js** 16.1.6 - React framework with App Router +- **React** 19.2.3 - UI library +- **Tailwind CSS** 4 - Utility-first CSS +- **TypeScript** 5 - Static typing +- **Jest** 30.2.0 - Testing framework + +### Mobile (App) +- **Expo** 55.0.5 - React Native framework +- **Expo Router** - File-based routing +- **React Native** 0.83.2 - Mobile framework +- **React** 19.2.0 - UI library +- **TypeScript** - Static typing + +### Tooling +- **Turbo** 2.8.13 - Monorepo orchestration +- **pnpm** 10.30.3 - Package manager +- **Biome** 2.4.6 - Linting & formatting +- **Lefthook** 2.1.2 - Git hooks +- **Docker** - Containerization +- **Nginx** - Reverse proxy (production) + +## Prerequisites + +- **Node.js** v24.14.0 (use `.nvmrc` for version management) +- **pnpm** 10.30.3 or higher +- **Docker** & Docker Compose +- **Git** + +## Quick Start + +### 1. Clone the repository +```bash +git clone +cd blog-nest +``` + +### 2. Install dependencies +```bash +pnpm install +``` + +### 3. Set up environment variables +```bash +cp .env.example .env +# Edit .env with your configuration +``` + +### 4. Start development database +```bash +pnpm docker:dev +``` + +### 5. Run database migrations +```bash +pnpm --filter api run prisma:migrate:dev +``` + +### 6. Start development servers +```bash +pnpm dev +``` + +This starts all apps in parallel: +- **API**: http://localhost:3001 +- **Frontend**: http://localhost:3000 +- **Mobile**: Expo DevTools (follow terminal instructions) + +## Project Structure + +``` +blog-nest/ +├── apps/ +│ ├── api/ # NestJS backend API +│ │ ├── prisma/ # Prisma schema & migrations +│ │ ├── src/ # Source code +│ │ └── test/ # E2E tests +│ ├── frontend/ # Next.js web application +│ │ └── src/ # Source code +│ └── mobile/ # Expo mobile application +│ ├── assets/ # Static assets +│ └── src/ # Source code +├── infra/ # Infrastructure configuration +│ ├── docker-compose.yml +│ └── nginx.conf +├── .github/ # GitHub configuration +├── package.json # Root package.json +├── pnpm-workspace.yaml # pnpm workspace config +├── turbo.json # Turbo configuration +├── biome.json # Biome linting config +└── lefthook.yml # Git hooks configuration +``` + +## Development + +### Available Commands + +#### Root Level (affects all apps) +```bash +pnpm dev # Start all apps in development mode +pnpm build # Build all apps +pnpm test # Run tests in all apps +pnpm lint # Lint all apps +pnpm clean # Clean build artifacts +pnpm check-types # Type-check all apps +``` + +#### Workspace-Specific Commands + +**Backend (API)** +```bash +pnpm --filter api dev # Start dev server +pnpm --filter api build # Build for production +pnpm --filter api test # Run unit tests +pnpm --filter api run test:cov # Run tests with coverage +pnpm --filter api run test:e2e # Run E2E tests +pnpm --filter api run prisma:generate # Generate Prisma Client +pnpm --filter api run prisma:migrate:dev # Run migrations (dev) +pnpm --filter api run prisma:migrate:deploy # Run migrations (prod) +pnpm --filter api run prisma:studio # Open Prisma Studio +``` + +**Frontend (Web)** +```bash +pnpm --filter frontend dev # Start dev server +pnpm --filter frontend build # Build for production +pnpm --filter frontend start # Start production server +pnpm --filter frontend test # Run tests +pnpm --filter frontend lint # Lint code +``` + +**Mobile (App)** +```bash +pnpm --filter mobile dev # Start Expo DevTools +pnpm --filter mobile android # Run on Android +pnpm --filter mobile ios # Run on iOS +pnpm --filter mobile web # Run on web +pnpm --filter mobile test # Run tests +``` + +### Docker Commands + +```bash +# Development +pnpm docker:dev # Start PostgreSQL & Redis +pnpm docker:down # Stop all containers + +# Production +pnpm docker:prod # Start all services (production) +pnpm docker:prod:down # Stop production containers +``` + +## Database Management + +### Prisma Workflow + +1. **Update schema**: Edit `apps/api/prisma/schema.prisma` +2. **Create migration**: + ```bash + pnpm --filter api run prisma:migrate:dev --name + ``` +3. **Apply to production**: + ```bash + pnpm --filter api run prisma:migrate:deploy + ``` +4. **Explore data**: + ```bash + pnpm --filter api run prisma:studio + ``` + +### Configuration + +Prisma v7 uses `apps/api/prisma.config.ts` for configuration: +- Connection URL loaded from root `.env` file +- Schema location: `apps/api/prisma/schema.prisma` +- Migrations stored in: `apps/api/prisma/migrations/` + +## Testing + +### Running Tests + +```bash +# All apps +pnpm test + +# Specific app +pnpm --filter api test +pnpm --filter frontend test +pnpm --filter mobile test + +# With coverage +pnpm --filter api run test:cov + +# Watch mode +pnpm --filter api run test:watch +``` + +### Test Structure + +- **Unit tests**: `*.spec.ts` or `*.spec.tsx` +- **E2E tests**: `test/*.e2e-spec.ts` (backend only) +- **Coverage target**: ≥90% for backend code + +## Configuration + +### Environment Variables + +Create a `.env` file in the project root: + +```env +# Database +DATABASE_URL=postgresql://blog:postgres@localhost:5432/blog_dev +DATABASE_HOST=localhost +DATABASE_PORT=5432 +DATABASE_NAME=blog_dev +DATABASE_USER=blog +DATABASE_PASSWORD=postgres + +# API +API_PORT=3001 + +# Frontend +NEXT_PUBLIC_API_URL=http://localhost:3001 + +# Mobile +EXPO_PUBLIC_API_URL=http://localhost:3001 +``` + +## Deployment + +### Production Deployment + +See [DEPLOY_VPS.md](DEPLOY_VPS.md) for complete VPS deployment guide including: +- Docker Compose setup +- Nginx reverse proxy configuration +- SSL/TLS with Let's Encrypt +- Database backup strategies +- Monitoring setup + +### Quick Production Build + +```bash +# Build all apps +pnpm build + +# Start production services +pnpm docker:prod +``` + +## Code Quality + +### Linting & Formatting + +This project uses **Biome** for linting and formatting: + +```bash +# Lint all code +pnpm lint + +# Auto-fix issues +pnpm lint --write + +# Check specific app +pnpm --filter api lint +``` + +### Git Hooks + +**Lefthook** runs pre-commit checks: +- Linting staged files +- Type checking +- Running relevant tests + +Hooks are automatically installed when you run `pnpm install`. + +## Architecture Decisions + +### Monorepo Strategy +- **Tool**: Turbo + pnpm workspaces +- **Benefits**: Shared TypeScript configs, parallel task execution, efficient caching +- **Workspace isolation**: Each app has its own dependencies and configuration + +### Prisma v7 +- Configuration moved from schema to `prisma.config.ts` +- Environment variables loaded from root `.env` +- Improved TypeScript integration and migration workflows + +### Next.js App Router +- Server Components by default +- Client Components only when needed +- Optimized for performance and SEO + +### Expo Router +- File-based routing for mobile app +- Seamless navigation between screens +- Web compatibility built-in + +## Contributing + +1. Create a feature branch: `git checkout -b feature/amazing-feature` +2. Make your changes +3. Run quality checks: `pnpm lint && pnpm test` +4. Commit following [Conventional Commits](https://www.conventionalcommits.org/): + ``` + feat(api): add user authentication + fix(frontend): resolve navigation bug + ``` +5. Push and create a Pull Request + +### Commit Format + +``` +(): + +[optional body] + +[optional footer] +``` + +**Types**: `feat`, `fix`, `refactor`, `test`, `chore`, `perf`, `docs` + +## Additional Documentation + +- [API Documentation](apps/api/README.md) +- [Frontend Documentation](apps/frontend/README.md) +- [Mobile Documentation](apps/mobile/README.md) +- [Infrastructure Guide](infra/README.md) +- [Deployment Guide](DEPLOY_VPS.md) +- [Copilot Instructions](.github/.copilot-instructions.md) + +## Troubleshooting + +### Common Issues + +**Port already in use** +```bash +# Kill processes on specific ports +pkill -f "next dev" +pkill -f "nest start" +``` + +**Stale dependencies** +```bash +pnpm clean +rm -rf node_modules +pnpm install +``` + +**Database connection issues** +```bash +# Restart database container +pnpm docker:down +pnpm docker:dev +``` + +**Prisma Client out of sync** +```bash +pnpm --filter api run prisma:generate +``` + +## License + +[License Type] - See LICENSE file for details + +## Team + +- [Your Name/Team] +- [Contact Information] + +--- + +Built with TypeScript