Integrated Management System

Introduction

This document serves as the single source of truth for all technical decisions, architecture, and step-by-step development plans for the Integrated Management System. It is intended for current and future developers working on the project.

Languages: UI in Portuguese (pt-BR), code/comments in English.
Development model: Monorepo, full-stack separated (Next.js + NestJS), containerized.

Approved Technology Stack

Architecture Overview

Monorepo Structure (Turborepo + pnpm)

/
├── apps/
│   ├── web/          # Next.js frontend
│   └── api/          # NestJS backend
├── packages/
│   ├── config/       # shared configs (eslint, tsconfig)
│   └── types/        # shared TypeScript types
├── docker-compose.yml
├── turbo.json
├── pnpm-workspace.yaml
└── package.json

Communication: REST API with JSON, JWT authentication.
Database: MySQL via Prisma ORM, with migrations.

Environment Variables

Phase 1: Setup (Steps 1-10)

1. Create workspace with pnpm init and turbo.json.
2. Initialize apps/web using create-next-app with TypeScript and App Router.
3. Configure Tailwind CSS with custom colors (primary orange palette).
4. Install dependencies: @tanstack/react-query, zustand, i18next, react-hook-form, zod.
5. Set up ESLint and Prettier with shared config from packages/config.
6. Create base folder structure: components/, app/, lib/, hooks/, types/.
7. Implement root layout with Inter font and metadata in pt-BR.
8. Configure i18next (initial locale pt-BR).
9. Create reusable Button component and a sample form with Tailwind + Zod validation.
10. Verify dev server runs and production build succeeds.

Phase 2: Authentication & Layout (Steps 1-8)

1. Design login page (email/password).
2. Create registration page (company basic data).
3. Implement API calls for auth using React Query.
4. Configure Zustand store for session state (token, user).
5. Protect private routes (Next.js middleware).
6. Create dashboard layout (sidebar, header, content area).
7. Implement logout and automatic token refresh.
8. Add error handling and toast notifications.

Phase 3: First Business Module (Steps 1-10)

1. Decide module (suggest "Users" or "Clients").
2. Create listing page with table (server or client component).
3. Implement pagination and search with React Query.
4. Create create/edit form (modal or separate page).
5. Integrate validation with Zod and React Hook Form.
6. Connect to backend endpoints (GET, POST, PUT, DELETE).
7. Add loading states and skeletons.
8. Implement delete confirmation.
9. Add visual feedback (success/error).
10. Review responsiveness and basic accessibility.

Phase 1: Setup (Steps 1-10)

1. Create apps/api with NestJS CLI.
2. Configure environment variables with @nestjs/config.
3. Install Prisma and set up MySQL client.
4. Define initial Prisma schema (User, Company models).
5. Run first migration against local Docker MySQL.
6. Set up Swagger for automatic API documentation.
7. Install and configure class-validator and class-transformer.
8. Create HealthController for status checks.
9. Configure CORS for frontend origin.
10. Verify API starts and responds correctly.

Phase 2: Authentication & Users (Steps 1-10)

1. Create Auth module with controller and service.
2. Implement company + admin user registration.
3. Generate JWT access/refresh tokens with @nestjs/jwt.
4. Create Passport JWT strategy.
5. Protect routes with custom guards.
6. Implement login endpoint (validate credentials, return tokens).
7. Create refresh token endpoint.
8. Implement logout (invalidate refresh token).
9. Add DTO validation with global pipes.
10. Document endpoints in Swagger with examples.

Phase 3: CRUD & Roles (Steps 1-10)

1. Create Users module (controller, service, repository via Prisma).
2. Define DTOs for create, update, response.
3. Implement endpoints: list (paginated), get by ID, create, update, delete.
4. Add search filters.
5. Create Roles module with basic CRUD.
6. Associate roles to users (many-to-many).
7. Implement role guard for authorization.
8. Add centralized exception handling (filters).
9. Write unit tests for core services.
10. Manual test with Swagger and adjust.

Coding Standards & Conventions

• TypeScript strict mode enabled in all projects.
• Use functional components and hooks; avoid class components.
• Naming: camelCase for variables/functions, PascalCase for components/classes, UPPER_SNAKE_CASE for constants.
• All backend DTOs must use validation decorators from class-validator.
• Frontend forms must use React Hook Form + Zod schemas.
• API responses should follow a consistent envelope: { data, meta?, error? }.
• Error messages in UI must be in Portuguese; code comments in English.

Essential Commands

Monorepo

# Install dependencies
pnpm install

# Run all apps in dev mode
pnpm dev

# Build all apps
pnpm build

# Lint all
pnpm lint

Backend (NestJS + Prisma)

# Generate Prisma client
pnpm --filter api prisma generate

# Run migrations
pnpm --filter api prisma migrate dev

# Start API in dev
pnpm --filter api start:dev

Frontend (Next.js)

# Start dev server
pnpm --filter web dev

# Build for production
pnpm --filter web build