Stubrix — Global Rules for Windsurf

# Stubrix — Global Rules for Windsurf

## Project Overview

Stubrix is a monorepo (npm workspaces) that provides a unified mock server platform with WireMock/Mockoon engines, a NestJS 11 control plane API, a React 19 dashboard, and a multi-database management system.

## Architecture

- **Monorepo**: npm workspaces at `packages/`
- **@stubrix/api**: NestJS 11 + Express, WebSockets (Socket.IO), class-validator
- **@stubrix/ui**: React 19 + Vite 7 + TailwindCSS + Lucide + React Router 7
- **@stubrix/db-ui**: Database microfrontend (React, consumed by @stubrix/ui)
- **@stubrix/shared**: TypeScript types shared across all packages
- **Docker**: Multi-profile compose (wiremock, mockoon, postgres, mysql)
- **Mocks**: Canonical WireMock format (mappings/_.json + \_\_files/_)

## Tech Stack & Versions

- Node.js >= 24, npm >= 10
- TypeScript 5.x across all packages
- NestJS 11 (API)
- React 19, Vite 7, TailwindCSS 3 (UI)
- PostgreSQL 17, MySQL 8, SQLite (better-sqlite3)
- Docker Compose with profiles
- Jest 30 + Supertest (API tests)
- ESLint 9 + Prettier (formatting)

## Code Style Rules

- Use TypeScript strict mode in all packages
- Follow NestJS conventions for the API: modules, controllers, services, DTOs
- Use class-validator decorators for all DTOs in @stubrix/api
- React components: functional components with hooks only, no class components
- TailwindCSS for all styling in UI packages — no inline styles or CSS modules
- Use Lucide React for all icons
- Imports: always absolute paths within each package (e.g., `@/` or relative from src)
- No default exports except for React pages/components where idiomatic
- All shared types go in @stubrix/shared, never duplicate types across packages

## File Naming

- API: kebab-case for files (e.g., `mock-engine.service.ts`, `create-mock.dto.ts`)
- UI: PascalCase for components (e.g., `MockEditor.tsx`, `DatabasesPage.tsx`)
- Shared: kebab-case for type files (e.g., `mock.types.ts`)
- Tests: co-located as `*.spec.ts` (API) or `*.test.tsx` (UI)

## API Conventions

- All REST endpoints under `/api/` prefix
- WebSocket namespace: `/ws/logs`
- Project-scoped routes: `/api/projects/:projectId/...`
- Database routes: `/api/db/...`
- Use NestJS pipes for validation (ValidationPipe global)
- Return consistent error shapes with HttpException

## Database Operations

- PostgreSQL: real operations via pg_dump/psql
- MySQL/SQLite: driver pattern with placeholder implementations
- Snapshots stored in `dumps/{engine}/`
- Metadata in `dumps/.snapshot-metadata.json` and `dumps/.project-databases.json`

## Docker & Infrastructure

- All services use Docker Compose profiles — never start services without explicit profile
- Environment variables defined in `.env` (loaded by Makefile, docker-compose, NestJS config)
- Mock port default: 8081, API port default: 9090
- Always use `make` targets as the primary CLI interface

## MCP Integration

- **GitHub MCP**: Use for all git operations, PR management, issue tracking
- **PostgreSQL MCP**: Use for direct database queries and inspection
- **Playwright MCP**: Use for E2E testing of the dashboard UI
- **Memory MCP**: Use for persistent knowledge graph about project decisions
- **DeepWiki MCP**: Use for referencing NestJS, React, WireMock documentation
- **Sequential Thinking MCP**: Use for complex architectural decisions

## Branch Strategy

- **dev** (default): All development work happens here — feature branches merge into `dev` via PR
- **stg**: Staging/QA — receives merges from `dev` via PR before going to production
- **main**: Production only — receives merges exclusively from `stg` via PR with 1 review required
- Flow: `feat/*` or `fix/*` → `dev` → `stg` → `main`
- **All three branches require PR** — never push directly to `main`, `stg`, or `dev`
- All PRs require 1 review approval and CodeQL passing

## Feature Development

- Feature specs live in `/features/` directory as numbered markdown files
- Follow the integration plan in `features/integracao-db-docker.md`
- Each feature should be developed in a feature branch off `dev`
- Always build shared package first: `npm run build:shared`

## Build Order (critical)

1. @stubrix/shared (no deps)
2. @stubrix/api (depends on shared)
3. @stubrix/db-ui (depends on shared)
4. @stubrix/ui (depends on shared + db-ui)

## Testing

- Unit tests required for all services in @stubrix/api
- E2E tests for critical API flows
- Use Playwright MCP for dashboard E2E when available
- Test database operations with real PostgreSQL via Docker profile

## Security

- Never commit `.env` files — use `.env.example` as template
- CORS configured via environment variable
- No hardcoded credentials in source code
- API keys and secrets only via environment variables