Fixr - O jeito fácil de gerenciar sua assistência técnica
O Fixr é uma aplicação web desenvolvida para o gerenciamento de ordens de serviço em assistências técnicas. O projeto tem como objetivo otimizar processos internos, centralizar informações e facilitar o acompanhamento de serviços, oferecendo uma solução completa para empresas do setor.
A aplicação foi idealizada a partir de entrevistas com profissionais da área de eletroeletrônicos, realizadas com o propósito de compreender as principais dificuldades enfrentadas por empresas de pequeno e médio porte. A partir dessas entrevistas, foram definidos os requisitos funcionais e não funcionais do sistema, elaborados os modelos de banco de dados (conceitual, lógico e físico) e desenvolvido um protótipo de interface utilizando a ferramenta Figma.
O Fixr foi desenvolvido como parte da disciplina de Projeto Integrador do curso de Ciência da Computação da Faculdade das Américas (FAM), aplicando tecnologias modernas e práticas consolidadas de desenvolvimento web para garantir segurança, desempenho e escalabilidade.
[!NOTE]
Acesse o projeto agora mesmo: https://fixr.com.br
Criado com
Sumário
Objetivo
O gerenciamento de ordens de serviço em assistências técnicas enfrenta diversos desafios, especialmente em empresas de pequeno e médio porte que ainda utilizam processos manuais. Entre os problemas mais comuns estão a perda de formulários, atrasos no atendimento, dificuldade de acompanhamento do status de reparos e controle ineficiente de estoque.
O Fixr foi desenvolvido para superar essas limitações, oferecendo uma plataforma centralizada que integra o gerenciamento de ordens de serviço, controle de estoque e geração de orçamentos. O sistema permite que técnicos e clientes acompanhem o progresso das ordens em tempo real, além de automatizar o registro de peças utilizadas e pedidos de compra junto a fornecedores, promovendo maior eficiência operacional.
Além disso, o Fixr implementa um modelo de permissões de acesso que organiza os usuários em diferentes níveis funcionais, garantindo segurança e flexibilidade no uso da plataforma pelos setores de atendimento, laboratório e administração.
Arquitetura
O Fixr adota uma arquitetura moderna, organizada em um monorepo que centraliza frontend, backend e pacotes compartilhados, permitindo reuso de código, consistência entre aplicações e automação de tarefas. O projeto utiliza Bun como runtime e gerenciador de pacotes, oferecendo maior performance e compatibilidade com o ecossistema JavaScript/TypeScript.
A estrutura principal do repositório é:
apps/
├─ web/ → Aplicação principal para clientes e técnicos (Next.js)
├─ admin/ → Painel administrativo interno para gerentes e administradores (Next.js)
└─ server/ → API REST em Fastify, responsável por toda a lógica de negócios e integração com o banco de dados
packages/
├─ db/ → Schemas, migrações e conexão com o banco de dados (Drizzle ORM + MySQL)
├─ schemas/ → Schemas Zod compartilhados entre frontend e backend para validação consistente
├─ constants/ → Constantes e enums do sistema
├─ env/ → Configuração centralizada de variáveis de ambiente com validação via Zod
├─ infra/ → Implementação da infraestrutura de deploy
├─ mail/ → Templates de email em React e configuração da fila de processamento com BullMQ
└─ typescript-config/ → Configurações TypeScript compartilhadas entre os projetos
Backend
O servidor é construído com Fastify, garantindo alta performance e baixo overhead em requisições HTTP. A comunicação com o banco de dados é feita através do Drizzle ORM, enquanto Redis é utilizado para cache e armazenamento temporário de jobs. Operações pesadas, como envio de emails ou importação de grandes volumes de funcionários, são processadas de forma assíncrona com BullMQ, garantindo respostas rápidas no frontend.
A autenticação é realizada via JWT, com suporte a refresh tokens, garantindo segurança e controle de acesso baseado em permissões definidas por cargo.
Frontend
O frontend é desenvolvido em Next.js, oferecendo renderização híbrida (SSR, ISR) para melhor desempenho e experiência do usuário. Ele consome a API REST, exibindo informações em interfaces intuitivas e responsivas, compatíveis com dispositivos móveis.
Infraestrutura
Toda a aplicação é conteinerizada com Docker, facilitando deploy e escalabilidade. A API é documentada com OpenAPI, permitindo integração e testes automatizados, utilizando Swagger e Scalar UI para visualização interativa.
Funcionalidades Principais
-
Gerenciamento de Ordens de Serviço (OS)
Permite criar, atualizar e acompanhar ordens de serviço com registro completo de histórico, controle de status (aberta, em andamento, concluída ou cancelada) e informações detalhadas sobre clientes, serviços e produtos utilizados.
-
Criação de Orçamentos e Controle de Peças
Gera orçamentos automaticamente com base nas peças e serviços vinculados a cada OS, garantindo precisão nos custos e verificando a disponibilidade em estoque antes da aprovação.
-
Gestão de Estoque e Fornecedores
Controla entradas, saídas e níveis de estoque de produtos, permitindo a criação automática de pedidos de compra quando peças estão em falta, otimizando a reposição e evitando interrupções nos serviços.
-
Controle de Acesso e Permissões
Implementa papéis e permissões detalhados (administrador, gerente, técnico, financeiro, estoquista), garantindo que cada usuário tenha acesso apenas às funções relevantes à sua função, aumentando a segurança e a organização do fluxo interno.
-
Acompanhamento em Tempo Real
Técnicos e clientes podem acompanhar o progresso das OS em tempo real, visualizando atualizações automáticas de status e informações relevantes, reduzindo falhas de comunicação e agilizando o atendimento.
-
Notificações Automáticas
Envia emails automáticos para atualização de status, aprovações de orçamentos e confirmações de cadastro, mantendo clientes e colaboradores sempre informados sem a necessidade de contato manual.
Tecnologias Utilizadas
O Fixr foi desenvolvido utilizando tecnologias modernas e consolidadas, que garantem desempenho, escalabilidade e segurança em todas as camadas da aplicação.
Frontend
- Next.js: Framework React para renderização híbrida (SSR/ISR), otimizando performance e SEO.
- React: Biblioteca para construção de interfaces dinâmicas e reutilizáveis.
- TailwindCSS: Framework utilitário para estilização rápida e consistente, com foco em responsividade.
- shadcn/ui: Componentes prontos e personalizáveis para acelerar a construção de interfaces.
- React Hook Form: Gerenciamento eficiente de formulários e validação de dados.
- Zod: Validação de dados em frontend, garantindo consistência com a API.
Backend
- Bun: Runtime JavaScript/TypeScript de alta performance, utilizado como ambiente de execução e gerenciador de pacotes.
- Fastify: Framework leve e de alta performance para construção da API REST.
- Drizzle ORM: Mapeamento objeto-relacional para MySQL, simplificando consultas e migrações.
- MySQL: Banco de dados relacional confiável para armazenar informações estruturadas.
- Redis: Cache em memória e armazenamento de dados temporários para otimização de desempenho.
- BullMQ: Gerenciamento de filas para processamento assíncrono de tarefas pesadas.
- JWT (JSON Web Tokens): Autenticação segura baseada em tokens de acesso e refresh tokens.
- Zod: Validação de dados no backend, garantindo integridade das informações recebidas.
- Swagger: Documentação interativa da API para testes e integração.
- Scalar UI: Interface gráfica para visualização e interação com a documentação da API.
Infraestrutura
- Docker: Conteinerização completa do ambiente de desenvolvimento e produção.
- Bun Workspaces: Gerenciamento de monorepo com workspaces nativos do Bun, permitindo compartilhamento eficiente de pacotes e dependências.
- TypeScript: Tipagem estática para maior segurança e manutenção do código.
- Husky: Git hooks para automação de tarefas pré-commit (formatação e validação de tipos).
Estrutura do Repositório
O repositório do Fixr segue uma organização em monorepo, separando claramente frontend, backend e pacotes compartilhados, facilitando o desenvolvimento, reuso de código e manutenção.
fixr/
├─ apps/
│ ├─ web/ # Aplicação principal para usuários e clientes (Next.js)
│ ├─ admin/ # Painel administrativo interno (Next.js)
│ └─ server/ # API REST construída com Fastify
│
├─ packages/
│ ├─ db/ # Schemas, conexões e migrações do banco de dados (Drizzle + MySQL)
│ ├─ schemas/ # Schemas Zod compartilhados entre frontend e backend
│ ├─ constants/ # Constantes globais e enums do sistema
│ ├─ env/ # Configuração centralizada de variáveis de ambiente
│ ├─ infra/ # Infraestrutura de deploy
│ ├─ mail/ # Templates de e-mail em React e fila de envio (BullMQ)
│ └─ typescript-config/ # Configurações TypeScript compartilhadas
│
├─ .husky/ # Git hooks para pré-commit (formatação e type-checking)
└─ package.json # Configuração do monorepo com Bun workspaces
Essa estrutura permite:
- Desenvolvimento independente de frontend e backend
- Reuso de código e validações compartilhadas entre projetos
- Gerenciamento centralizado de variáveis de ambiente com validação
- Automação de tarefas via Bun workspaces e scripts do package.json
- Qualidade de código garantida por hooks pré-commit
Documentação da API
A API do Fixr é totalmente documentada seguindo o padrão OpenAPI 3.0, garantindo clareza, consistência e facilidade de integração com outras aplicações.
Os principais pontos de acesso à documentação são:
- Scalar UI:
/docs – Interface interativa para exploração e testes da API.
- Swagger Reference:
/reference – Referência completa com detalhes de endpoints, parâmetros e respostas.
A documentação é projetada para facilitar futuras integrações com ERPs e outros sistemas externos, permitindo que usuários com perfil de gerente possam gerar API tokens diretamente pelo painel administrativo, garantindo segurança e controle de acesso granular.
Como Executar o Projeto
Para rodar o Fixr localmente, você precisará ter instalados em sua máquina:
Passos
- Clone o repositório:
git clone https://github.com/fixrfam/fixr
cd fixr
- Instale as dependências de todos os apps e pacotes:
bun install
- Prepare o ambiente local com um único comando:
bun run setup
O setup faz tudo o que antes era manual:
- cria o
.env na raiz a partir do .env.example, gerando JWT_SECRET, API_KEY_SECRET e COOKIE_ENCRYPTION_SECRET (se você ainda tiver os .env antigos por pasta, os valores deles são reaproveitados);
- sobe o MySQL e o Redis via Docker e espera ficarem saudáveis;
- cria ou atualiza o schema do banco;
- popula o banco com dados de demonstração e imprime os logins.
Use bun run setup --reset para apagar os dados e popular de novo, ou --no-seed para pular o seed.
- Inicie server, web e workers em modo desenvolvimento:
bun run dev
- (Opcional) Inicie o painel admin, separadamente (precisa das chaves do Clerk no
.env):
bun run dev:admin
Os serviços estarão disponíveis em:
- API REST:
http://localhost:3333
- Web App:
http://localhost:3000
- Admin Panel:
http://localhost:6969 (requer bun run dev:admin)
- Documentação API (Scalar):
http://localhost:3333/docs
- Drizzle Studio: Execute
bun run db:studio para acessar
Variáveis de Ambiente
Em desenvolvimento existe um único .env na raiz, lido por todos os apps e pacotes. O .env.example é a referência: ele agrupa as variáveis por serviço e já traz valores que funcionam localmente (senhas docker/fixr, chaves de teste do Cloudflare Turnstile e placeholders para Google OAuth e Cloudflare R2). Para usar esses serviços de verdade, ou o painel admin (Clerk), troque os placeholders pelas chaves geradas nos respectivos painéis.
Em produção nada muda: o deploy (GitHub Actions + Alchemy e Coolify) injeta as variáveis diretamente, sem arquivo .env.
Nota: As variáveis são validadas automaticamente pelo pacote @fixr/env usando Zod, garantindo que todas as configurações necessárias estejam presentes antes da inicialização dos apps.
Dados de demonstração
O seed (packages/db/src/seed) cria duas empresas (alfa e beta), um usuário para cada cargo na alfa, clientes, fabricantes e modelos de aparelhos e ordens de serviço em vários status. Todas as contas usam a senha Fixr!Dev123, por exemplo [email protected], [email protected] ou [email protected]. O setup imprime a lista completa.
Scripts Disponíveis
# Desenvolvimento
bun run setup # Prepara .env, Docker, schema e dados de demonstração
bun run dev # Inicia server, web e workers em modo desenvolvimento
bun run dev:admin # Inicia o painel admin em modo desenvolvimento
bun run check-types # Executa verificação de tipos em todos os projetos
bun run test # Testes unitários de todos os projetos
bun run test:watch # Testes unitários em modo watch
# Build
bun run build # Build completo (pacotes + apps)
bun run build:packages # Build apenas dos pacotes
bun run build:apps # Build apenas dos apps
# Banco de Dados
bun run db:start # Inicia containers Docker (MySQL + Redis)
bun run db:stop # Para os containers
bun run db:migrate # Executa migrations
bun run db:generate # Gera migrations a partir dos schemas
bun run db:studio # Abre Drizzle Studio (GUI do banco)
bun run db:push # Push direto do schema (desenvolvimento)
bun run db:seed # Popula o banco com dados de demonstração (--reset apaga antes)
# Formatação e Lint
bun run format # Formata código com Ultracite
bun run lint # Executa linting
bun run lint:write # Corrige problemas de lint automaticamente
Os scripts locais (dev, build, test, lint, check-types) rodam via Turborepo: cada pacote ganha seu próprio painel no terminal e resultados sem mudanças vêm do cache. Os scripts com sufixo :ci continuam usando bun run --filter, então CI e deploy não dependem do Turborepo.
Pre-commit Hooks
O projeto possui hooks automáticos que são executados antes de cada commit:
- Formatação automática com Ultracite
- Verificação de tipos com TypeScript
- ❌ Commits são bloqueados se houver erros de tipo
Para configurar os hooks após clonar o repositório:
bun install # Husky será configurado automaticamente
Equipe, Artigos e Referências
Equipe
Artigos da Revista FAM
O desenvolvimento do Fixr acompanha os trabalhos realizados nos semestres da disciplina de Projeto Integrador, publicados na revista da Faculdade das Américas (FAM):
O artigo referente ao 4º semestre** ainda será publicado e atualizado neste README assim que disponível.
Referências
- KOIVISTO, Elma. Implementation of an Internal Order Management System. Bachelor of Engineering Industrial. 2023 março. Disponível aqui.
- Equipe TOTVS, et al. Software de controle de estoque, o que é, tipos e como escolher. 2022. Disponível aqui.
- DUMAS, Marlon; LA ROSA, et al. Fundamentals of Business Process Management. 2. ed. Berlin: Springer, 2013. Disponível aqui.
- GARCIA-MOLINA, Hector; ULLMAN, et al. Database Systems: The Complete Book. 2. ed. Upper Saddle River: Pearson Prentice, 2001. Disponível aqui.
- REIS, Claudio Francisco dos. Sistema de Ordem de Serviço. Assis: Fundação Educacional do Município de Assis – FEMA, 2010. Trabalho de Conclusão de Curso (Graduação). Disponível aqui.
- FU, Jamie; LIU, Katherine; LIU, Richard; WONG, Anna. JWT Web Security: 6.857 Final Project. Cambridge, MA: MIT, 2022. Disponível aqui.
- TOTVS. Saiba tudo sobre sistema para assistência técnica. 15 jun. 2020. Disponível aqui.
- HARSH, Kumar. O que é Arquitetura de Aplicativos Web? Quebrando um aplicativo da Web. Kinsta, 17 jan. 2025. Disponível aqui.
- MICROSOFT. Estilo de arquitetura Queue-Worker Web. Azure Architecture Center, 2025. Disponível aqui.
Contribuindo
Contribuições são bem-vindas! Veja o CONTRIBUTING.md para instruções de setup, convenções de branch/commit e o processo de pull request. Este projeto segue o Código de Conduta.
Licença
Este projeto está licenciado sob a Licença MIT.
