Librix é um sistema web para gerenciamento de bibliotecas, com controle de usuários, livros, empréstimos, autenticação JWT, permissões granulares e área administrativa.
- Funcionalidades
- Tecnologias Utilizadas
- Estrutura do Projeto
- Pré-requisitos
- Clonando o Projeto
- Instalando as Dependências
- Configuração do Ambiente
- Banco de Dados
- Rodando o Projeto
- Usuário Administrador
- Scripts Disponíveis
- Fluxo da Aplicação
- Controle de Permissões
- Rotas Principais
- API
- Uploads
- Recuperação de Senha
- Paginação
- Busca
- Filtros
- Desenvolvimento
- Boas Práticas
- Licença
- Contato
- Login com JWT (
/auth/sign-in) - Recuperação de senha com token (
/auth/forgot-password,/auth/reset-password/:token,/auth/reset-password) - Ativação de conta por convite (
/users/activate_account) - Dashboard/Home com indicadores e atalhos
- Catálogo público de livros
- Detalhes de livro
- Gestão de livros (CRUD administrativo)
- Upload de capa de livro
- Gestão de usuários (CRUD administrativo)
- Edição de perfil do usuário e troca de senha
- Empréstimos (criação, devolução, edição e exclusão)
- Histórico de empréstimos (com paginação e status)
- Autocompletes (autores, editoras, tags, livros disponíveis e todos os livros)
- Controle de permissões por feature flag
- Rotas protegidas para autenticação e autorização
- Layout público e layout administrativo responsivos
- Área de favoritos (página existente, sem persistência no backend)
- Relatórios administrativos: endpoint
/reports/dashboardimplementado e rota administrativa disponível - Cadastro aberto (
/register) usa atualmente o fluxo de ativação por convite
- React 19
- TypeScript
- React Router DOM v7
- SCSS Modules
- Lucide React
- Vite
- Node.js
- Express 5
- TypeScript
- Sequelize ORM
- JWT (
jsonwebtoken) - Zod (validação)
- Multer (uploads)
- Resend (e-mail)
- PostgreSQL
- Docker
- Docker Compose
- ESLint
- npm Workspaces (monorepo)
librix/
├── apps/
│ ├── api/ # Backend (Express + Sequelize)
│ │ ├── src/
│ │ │ ├── controllers/ # Regras de negócio e endpoints
│ │ │ ├── database/ # Modelos e conexão Sequelize
│ │ │ ├── http/ # App Express e rotas
│ │ │ ├── middleware/ # Auth, validação de body, upload
│ │ │ └── schemas/ # Schemas Zod
│ │ └── thumbnails/ # Uploads de capas no backend
│ └── web/ # Frontend (React + Vite)
│ └── src/
│ ├── components/ # Componentes reutilizáveis
│ ├── contexts/ # Context API (usuário)
│ ├── layouts/ # Layout público e administrativo
│ ├── pages/ # Páginas públicas, privadas e admin
│ └── styles/ # Variáveis e estilos globais
├── migrations/ # Migrations Sequelize (monorepo root)
└── packages/
├── flags/ # Bitflags de permissões
└── types/ # Tipos compartilhados entre apps
- Node.js 20+
- npm 10+
- PostgreSQL 14+ (local) ou Docker + Docker Compose
- Git
Opcional:
- VS Code com extensões de TypeScript/ESLint/SCSS
git clone https://github.com/jvopinho/librix.git
cd librixEste projeto é um monorepo com npm workspaces.
npm installIsso instala as dependências de:
apps/apiapps/webpackages/flagspackages/types
Arquivo: apps/api/.env
Você pode copiar de apps/api/.env.example:
cp apps/api/.env.example apps/api/.envExemplo completo:
PORT=3001POSTGRES_USER=postgresPOSTGRES_PASSWORD=passwordPOSTGRES_DB=postgresPOSTGRES_PORT=5432POSTGRES_ENDPOINT=localhost:5432RESEND_API_KEY=re_xxxxxxxxxxxxxxxxxxxxxJWT_SESSION_SECRET=supersecretkeyJWT_FIRST_ACCESS_SECRET=supersecretkeyPASSWORD_SALT_ROUNDS=10WEB_URL=http://localhost:5173PORT: porta lógica da API (observação: atualmente o servidor inicia fixo em7654no código)POSTGRES_USER: usuário do banco PostgreSQLPOSTGRES_PASSWORD: senha do banco PostgreSQLPOSTGRES_DB: nome do bancoPOSTGRES_PORT: porta do PostgreSQLPOSTGRES_ENDPOINT: host:porta do PostgreSQLRESEND_API_KEY: chave da API de envio de e-mails (ativação e recuperação)JWT_SESSION_SECRET: segredo para token de sessãoJWT_FIRST_ACCESS_SECRET: segredo adicional de primeiro acessoPASSWORD_SALT_ROUNDS: custo do hash bcryptWEB_URL: URL da aplicação frontend para CORS e links de e-mail
Arquivo: apps/web/.env (opcional)
VITE_API_URL=http://localhost:7654VITE_API_URL: base URL da API consumida no frontend.- Se não for definido, o frontend usa
http://localhost:7654por padrão.
npm run compose:dev:upComando acima sobe o PostgreSQL com base no arquivo docker-compose.dev.yml e no .env do backend.
npm run db:migrate --workspace @librix/apiHá script no backend, mas em ambiente de shell o fluxo mais previsível é:
cd apps/api
npx dotenv -e .env -- sequelize-cli migration:generate --name nome_da_migrationnpm run db:migrate --workspace @librix/apicd apps/api
npx dotenv -e .env -- sequelize-cli db:migrate:undo:all
npx dotenv -e .env -- sequelize-cli db:migrateAtualmente não há script de seed versionado no projeto.
- Para popular dados, use os endpoints administrativos após autenticação.
npm run dev --workspace @librix/api- API disponível em:
http://localhost:7654
npm run dev --workspace @librix/web- Frontend disponível em:
http://localhost:5173(padrão Vite)
O usuário administrador possui id 1, quando a api iniciar ela verifica se existe o usuário cadastrado, caso não possua ela irá criar e em seguida enviar o login e senha no terminal.
| Escopo | Script | Comando | Descrição |
|---|---|---|---|
| root | compose:dev:up | npm run compose:dev:up | Sobe PostgreSQL via Docker Compose |
| root | compose:dev:start | npm run compose:dev:start | Inicia containers já criados |
| api | dev | npm run dev --workspace @librix/api | Desenvolvimento backend com watch |
| api | build | npm run build --workspace @librix/api | Build TypeScript backend |
| api | start | npm run start --workspace @librix/api | Inicia backend compilado |
| api | db:migrate | npm run db:migrate --workspace @librix/api | Executa migrations |
| api | db:generate | npm run db:generate --workspace @librix/api | Gera migration (depende do shell) |
| web | dev | npm run dev --workspace @librix/web | Desenvolvimento frontend |
| web | build | npm run build --workspace @librix/web | Build frontend |
| web | preview | npm run preview --workspace @librix/web | Preview do build frontend |
| web | lint | npm run lint --workspace @librix/web | Lint frontend |
| flags | build | npm run build --workspace @librix/flags | Build do pacote de permissões |
Usuário
↓
Login / Ativação de Conta
↓
Autenticação (JWT)
↓
Resolução de Permissões (feature flags)
↓
Dashboard / Home
↓
Operações (livros, usuários, empréstimos, administração)
O sistema usa feature flags com bitfield em @librix/flags.
Pode:
- gerenciar usuários
- gerenciar livros
- gerenciar empréstimos
- acessar relatórios
- acessar dashboard administrativo
Pode:
- gerenciar livros
- gerenciar empréstimos
- visualizar/editar usuários (conforme features atribuídas)
Pode:
- visualizar catálogo
- visualizar detalhes de livros
- visualizar próprios empréstimos
- realizar operações restritas ao próprio contexto (dependendo das features)
Observação importante:
- permissões efetivas dependem das features atribuídas ao usuário na base.
/
/home
/books
/books/:id
/login
/register
/forgot-password
/reset-password/:token
/activate-account
/users/activate
/users/activate/invalid
/profile
/my-loans
/favorites
/admin
/admin/dashboard
/admin/books
/admin/books/create
/admin/books/new
/admin/books/edit/:id
/admin/users
/admin/loans
/admin/loans/new
---- NÃO IMPLEMENTADAS ----
/admin/authors
/admin/publishers
/admin/categories
/admin/reports
/admin/settings
Observação:
- algumas rotas administrativas apontam para páginas placeholder no frontend.
Base local padrão:
http://localhost:7654
Documentação Swagger local:
http://localhost:7654/api-docshttp://localhost:7654/swagger.json
Frontend consome API via helper (getApiUrl) em:
apps/web/src/helpers/api-url.ts
- Armazenamento local em:
apps/api/thumbnails - Servido estaticamente em:
GET /thumbnails/:filename - Middleware: Multer (
apps/api/src/middleware/upload-middleware.ts) - Nome do arquivo: hash aleatório + extensão original
- Não há limite de tamanho configurado atualmente no Multer.
- Não há validação explícita de MIME type/extensão no backend atual.
Recomendação para produção:
- adicionar limite de tamanho
- validar MIME type
- mover armazenamento para bucket (S3, GCS, etc.)
Fluxo implementado:
- Solicitar recuperação:
POST /auth/forgot-password - API gera token e envia e-mail via Resend
- Frontend valida token:
GET /auth/reset-password/:token - Frontend envia nova senha:
POST /auth/reset-password
Padrão implementado em endpoints list:
GET /books/all?page=1&limit=20GET /users?page=1&limit=10GET /loans?page=1&limit=10GET /loans/my-loans?page=1&limit=10Resposta segue formato semelhante:
{
"data": [],
"page": 1,
"limit": 10,
"total": 0,
"totalPages": 0
}Exemplos reais:
GET /books/all?search=harryGET /users?search=joaoGET /loans?search=mariaExemplos disponíveis hoje:
GET /books/all?author=MachadoGET /books/all?category=RomanceGET /books/all?isbn=978GET /books/all?availability=trueGET /users?status=ACTIVEGET /loans?status=BORROWEDGET /loans?status=LATEGET /loans?status=RETURNEDOrdenação também disponível em listagens:
GET /books/all?sortBy=title&sortOrder=ASCGET /users?sortBy=name&sortOrder=DESCFluxo recomendado para contribuição:
- Criar branch de feature:
git checkout -b feat/nome-da-feature- Implementar alterações
- Rodar lint/build localmente
- Commitar com mensagens claras
- Abrir Pull Request com contexto e evidências
Exemplo de verificação local:
npm run lint --workspace @librix/web
npm run build --workspace @librix/api
npm run build --workspace @librix/web- TypeScript em frontend e backend
- SCSS Modules para isolamento de estilos
- Componentização de UI
- Uso de hooks para estado/contexto
- Organização por domínio (controllers, pages, components)
- Validação de entrada com Zod
- Linting com ESLint
Observação:
- ainda existem pontos do frontend/backend com
anyque podem ser gradualmente eliminados.
Projeto licenciado sob MIT.
Consulte o arquivo LICENSE na raiz para o texto completo.
Responsável atual pelo repositório:
- João Pinho —
jvopinho.contato@gmail.com
Repositório: