Dev Controle

Versão em português (Brasil): README.pt-BR.md

Dev Controle is a full-stack web application for managing customer support tickets. Each authenticated user operates in an isolated workspace, seeing only their own customers and tickets.

Features

Ticket management

• Open tickets linked to a registered customer
• Edit subject, description, and status at any time
• Delete tickets with a confirmation dialog to prevent accidental removal
• Filter tickets by free-text search (subject, description, or customer name) and by status
• Status badge and elapsed time displayed inline on every ticket row

Follow-up board

• Kanban-style view with one column per status: Open, In Progress, Resolved, Closed
• Move tickets to the next stage directly from the board
• Unmapped statuses are surfaced in a warning section for quick cleanup

Work timer

• Start and pause a work timer on any in-progress ticket
• Accumulated work time persists across sessions
• Live counter updates every second while the timer is running

Customer management

• Register customers with name, email, phone, and address
• Delete customers (blocked if the customer has open tickets)
• Customer data is scoped per user

Metrics

• Summary cards: total tickets, distinct customers, statuses in use
• Bar chart of ticket volume by customer
• Doughnut chart of ticket distribution by status
• Highlighted top customer by volume

Admin panel

• User listing and role management (ADMIN / USER)
• Restricted to users with the ADMIN role
• Observability charts for system health (extensible)

General

• Authentication via NextAuth (sign in / sign out)
• Per-user data isolation enforced at the database query level
• Light and dark mode with system preference detection
• Responsive layout (mobile-first)
• Toast notifications for user feedback
• Accessible markup: semantic HTML, aria-* attributes, keyboard navigation

Tech Stack

Layer	Technology
Framework	Next.js 16 (App Router)
Language	TypeScript
Styling	Tailwind CSS v4
Database ORM	Prisma + MongoDB
Authentication	NextAuth v4
Charts	Chart.js + react-chartjs-2
Forms	React Hook Form + Zod
Toasts	Sonner
Monitoring	Sentry + Core Web Vitals
Unit/Integration tests	Vitest + Testing Library
E2E tests	Playwright
CI/CD	GitHub Actions
Containerization	Docker + Docker Compose

Architecture Highlights

• Server actions handle all mutations (create, update, delete). Client components call server actions directly — no REST API layer for internal operations.
• Server components fetch data from Prisma at render time. Only components that need interactivity (modals, timers, forms) are client components.
• Shared components (MetricCard, Container, Input, ThemeToggle) avoid duplication across pages.
• Role-based access control is enforced both at the UI level (admin tab hidden for non-admins) and at the action level (session check before every mutation).

Getting Started

Prerequisites

• Node.js 18+
• A MongoDB connection string
• A NextAuth secret and OAuth provider credentials

Install dependencies

npm install

Configure environment

cp .env.example .env

Fill in DATABASE_URL, NEXTAUTH_SECRET, and your OAuth provider variables.

Run the development server

npm run dev

Open http://localhost:3000.

Scripts

Script	Description
npm run dev	Start development server
npm run build	Build for production
npm run start	Run production build
npm run lint	Run ESLint
npm run lint:fix	Run ESLint with auto-fix
npm run format	Format with Prettier
npm run type-check	TypeScript type checking
npm run test:integration	Run integration tests
npm run test:coverage	Integration tests with coverage report
npm run test:e2e	Playwright E2E (browsers installed locally)
npm run test:e2e:docker	Playwright E2E inside Docker

Monitoring and Observability

• Sentry captures errors with full stack traces on client, server, and edge runtimes.
• Core Web Vitals (LCP, INP, CLS) are collected and persisted in MongoDB via POST /api/monitoring/web-vitals. Metrics rated poor or needs-improvement are also sent to Sentry.

Sentry environment variables

SENTRY_DSN=
NEXT_PUBLIC_SENTRY_DSN=
SENTRY_ENVIRONMENT=development
NEXT_PUBLIC_SENTRY_ENVIRONMENT=development
SENTRY_TRACES_SAMPLE_RATE=0.1
NEXT_PUBLIC_SENTRY_TRACES_SAMPLE_RATE=0.1
SENTRY_PROFILES_SAMPLE_RATE=0.1
SENTRY_AUTH_TOKEN=
SENTRY_ORG=
SENTRY_PROJECT=

SENTRY_AUTH_TOKEN, SENTRY_ORG, and SENTRY_PROJECT are required for source map upload at build time.

Docker

# Start the app
npm run docker:up

# Follow logs
npm run docker:logs

# Stop containers
npm run docker:down

# Run E2E tests in Docker
npm run docker:e2e

Files: Dockerfile (production app), Dockerfile.e2e (Playwright), docker-compose.yml.

CI/CD

GitHub Actions workflow at .github/workflows/ci.yml runs on every push and pull request:

1. npm run lint
2. npm run type-check
3. npm run test:integration
4. npm run build

To protect main, enable branch protection in Settings > Branches and require the Lint, Typecheck, Tests and Build check to pass before merging.

Documentation

• Testing: docs/testing/testing.en.md
• Monitoring: docs/monitoring/monitoring.en.md
• CI/CD: docs/ci-cd/ci-cd.en.md

Roadmap

• Audit trail with a per-ticket change history timeline
• Email notifications on ticket status changes
• File attachment support on tickets
• SLA / deadline tracking per ticket
• Export reports as PDF or CSV