feat: update README.md with comprehensive tech stack, setup instructions, and development guidelines

This commit is contained in:
2026-03-06 19:37:55 +03:00
parent 5bb086c86a
commit 409b9454c0
2 changed files with 440 additions and 26 deletions
+54 -26
View File
@@ -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-name> <task>`
- Workspace names: `api`, `frontend`, `mobile`
- **Turbo Commands**: `turbo run <task>` (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 <app> 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 <migration-name>
pnpm --filter @dpep/api run prisma generate
pnpm --filter api run prisma:migrate:dev --name <migration-name>
pnpm --filter api run prisma:generate
```
6. Run focused tests for changed behavior:
```bash
# Backend
pnpm --filter @dpep/api test -- <file-pattern>
pnpm --filter api test -- <file-pattern>
# Frontend
pnpm --filter frontend test -- <file-pattern>
@@ -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 <name>`.
- Never hand-edit migration files.
- Commit both schema and migration files.
- Always generate migrations via `pnpm --filter api run prisma:migrate:dev --name <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 <pattern>` or E2E tests if relevant.
- **Backend changes**: run targeted `pnpm --filter api test <pattern>` 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 <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 <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
```
---