# Agent Guidelines for placebo.mk

## Project Overview
News site in Macedonia with sarcastic tone. Minimalistic design using TanStack stack.

## Tech Stack
- **Frontend**: TanStack (React 19, Query, Router) + Vite + Tailwind CSS + shadcn/ui
- **Backend**: NestJS + TypeORM + SQLite
- **CMS**: Strapi (in /cms)

## Root-Level Commands
```bash
# Docker development
npm run docker:up           # Start all services
npm run docker:down         # Stop all services
npm run docker:build        # Rebuild containers
npm run docker:logs         # View logs
npm run dev:docker          # Start docker dev (alias)

# Local development
npm run dev:local           # Start backend & frontend locally
npm run dev:backend:local   # Backend only (local env)
npm run dev:frontend:local  # Frontend only (local env)

# Code quality
npm run lint                # Lint both projects
npm run lint:fix            # Auto-fix lint issues
npm run type-check          # Type check both projects

# Database operations
npm run db:backup           # Backup database
npm run db:restore          # Restore database
npm run db:reset            # Reset database

# Environment
npm run reset:env           # Reset to docker environment
```

## Build Commands

### Backend (NestJS)
```bash
cd backend
npm install
npm run start:dev           # Watch mode
npm run start:debug         # Debug mode
npm run build
npm run start:prod
npm run lint                # Lint
npm run lint:fix            # Auto-fix
npm run type-check          # TypeScript check
npm test                    # All tests
npm test:watch              # Watch mode tests
npm test:cov                # Coverage
npm test:e2e                # E2E tests
npm test app.service.spec.ts  # Single file
npm test -t "should return"    # By test name pattern
npm run format              # Format with Prettier
npm run dev:local           # Local env with .env.local
npm run dev:docker          # Docker env with .env.docker
```

### Frontend (TanStack)
```bash
cd frontend
npm install
npm run dev                 # Vite dev server
npm run build
npm run preview
npm run lint                # Lint
npm run lint:fix            # Auto-fix
npm run type-check          # TypeScript check
npm test                    # All tests (Vitest)
npm test:ui                 # Vitest UI
npm test:coverage           # Test coverage
npm test Header.test.tsx    # Single file
npm test -t "renders"       # By test name pattern
npm run dev:local           # Local env with .env.local
npm run dev:docker          # Docker env with .env.docker
```

## Code Style

### Formatting & TypeScript
- Use Prettier (2 spaces, single quotes, trailing commas, 100 char max)
- Strict TypeScript - no implicit `any`, avoid `any`, use `unknown`
- Explicit return types for public methods
- Prefer interfaces over types for objects
- Use `readonly` for immutable properties
- Backend: `noImplicitAny: true`, `strictNullChecks: true`
- Frontend: Path alias `@/*` maps to `./src/*`

### Naming Conventions
- **Files**: kebab-case (`user-profile.ts`, `auth.service.ts`)
- **Classes**: PascalCase (`UserService`, `AuthGuard`)
- **Functions/Variables**: camelCase (`getUser`, `isLoading`)
- **Constants**: UPPER_SNAKE_CASE (`MAX_RETRIES`)
- **Private members**: underscore prefix (`_cache`, `_validate()`)
- **Interfaces**: PascalCase, no 'I' prefix (`User`, `ApiResponse`)

### Import Order
- External libraries first, then internal modules, then relative imports
- Group imports with blank lines between groups
- Example:
  ```typescript
  // External
  import { Module } from '@nestjs/common';
  import { TypeOrmModule } from '@nestjs/typeorm';
  
  // Internal modules
  import { AuthModule } from '../auth/auth.module';
  
  // Relative imports
  import { UserService } from './user.service';
  import { UserController } from './user.controller';
  ```


### File Structure
```
backend/src/
  modules/feature-name/
    feature-name.module.ts
    feature-name.controller.ts
    feature-name.service.ts
    feature-name.entity.ts
    feature-name.dto.ts
  common/{decorators,filters,guards,interceptors,pipes}
  config/

frontend/src/
  components/{ui,layout,features}/
  hooks/
  lib/
  queries/
  routes/
  types/
  utils/
```

### Error Handling
- **Backend**: Use NestJS exceptions (`NotFoundException`, `BadRequestException`), custom exceptions, Logger
- **Frontend**: Error boundaries, try-catch with user-friendly messages

### API Conventions
- REST endpoints: `/api/v1/resources`
- JSON fields: snake_case
- Pagination: `page`, `limit` query params
- Response format:
  ```typescript
  {
    data: T,
    meta: { total, page, limit },
    error?: { code, message }
  }
  ```

### Testing
- **Backend**: Jest with ts-jest transformer
- **Frontend**: Vitest with React Testing Library patterns
- Unit tests for services/hooks (AAA pattern: Arrange-Act-Assert)
- Integration tests for API endpoints
- E2E tests for critical user flows
- Descriptive test names that explain what is tested (e.g., `should return user data when valid ID provided`)
- Mock external dependencies (use Jest for backend, Vitest for frontend)
- Run `npm test` for all tests or target specific files/names
- Test files: `*.spec.ts` (backend), `*.test.tsx` (frontend)
- Coverage reports: `npm test:cov` (backend), `npm test:coverage` (frontend)

### Git Workflow
- Conventional commits: `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`
- Keep commits atomic and focused
- Write clear commit messages in imperative mood

### Component Guidelines
- Keep components small and focused (< 200 lines)
- Use functional components with hooks
- Prefer composition over inheritance
- Extract complex logic into custom hooks
- Use TanStack Query for server state management
- Use TanStack Router for routing
- Validate props with TypeScript

### Database
- Use TypeORM for SQLite
- Define entities with proper relationships
- Use migrations for schema changes
- Seed data with factory functions
- Use TypeORM repositories for data access

### UI Components
- Use shadcn/ui components from `components/ui/`
- Use class-variance-authority (CVA) for component variants
- Use clsx and tailwind-merge for class composition
- Follow shadcn patterns for new component creation


## Environment Variables
- Backend: `@nestjs/config` with `.env` files
- Frontend: Vite env vars (`VITE_API_URL`)
- Never commit secrets to the repository.
- Example frontend env: `VITE_API_URL=http://localhost:3000`
- Example backend env: `DATABASE_PATH=./data.db`
- Store sensitive config in `.env` files
- Use `DATABASE_PATH` for SQLite location
- Use `@nestjs/config` for backend environment management
- Frontend env vars must be prefixed with `VITE_`

## Agent-Specific Instructions
- **ALWAYS** run `npm run lint` and `npm run type-check` after making changes
- **NEVER** commit changes without explicit user request
- **ALWAYS** follow existing code patterns and conventions
- **PREFER** editing existing files over creating new ones
- **VERIFY** tests pass before considering work complete
- **USE** the root-level commands for common operations
- **CHECK** both backend and frontend when making API changes