📚 Librix

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.

📌 Índice

Funcionalidades
Tecnologias Utilizadas
Estrutura do Projeto
Pré-requisitos
Clonando o Projeto
Instalando as Dependências
Configuração do Ambiente
- Backend
- Frontend
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

🚀 Funcionalidades

Implementadas no estado atual

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

Em progresso ou parcialmente disponível

Área de favoritos (página existente, sem persistência no backend)
Relatórios administrativos: endpoint /reports/dashboard implementado e rota administrativa disponível
Cadastro aberto (/register) usa atualmente o fluxo de ativação por convite

🧰 Tecnologias Utilizadas

Frontend

React 19
TypeScript
React Router DOM v7
SCSS Modules
Lucide React
Vite

Backend

Node.js
Express 5
TypeScript
Sequelize ORM
JWT (jsonwebtoken)
Zod (validação)
Multer (uploads)
Resend (e-mail)

Banco de dados

PostgreSQL

Outros

Docker
Docker Compose
ESLint
npm Workspaces (monorepo)

🗂 Estrutura do Projeto

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

✅ Pré-requisitos

Node.js 20+
npm 10+
PostgreSQL 14+ (local) ou Docker + Docker Compose
Git

Opcional:

VS Code com extensões de TypeScript/ESLint/SCSS

📥 Clonando o Projeto

git clone https://github.com/jvopinho/librix.git
cd librix

📦 Instalando as Dependências

Este projeto é um monorepo com npm workspaces.

npm install

Isso instala as dependências de:

apps/api
apps/web
packages/flags
packages/types

⚙️ Configuração do Ambiente

Backend

Arquivo: apps/api/.env

Você pode copiar de apps/api/.env.example:

cp apps/api/.env.example apps/api/.env

Exemplo completo:

PORT=3001

POSTGRES_USER=postgres
POSTGRES_PASSWORD=password
POSTGRES_DB=postgres
POSTGRES_PORT=5432
POSTGRES_ENDPOINT=localhost:5432

RESEND_API_KEY=re_xxxxxxxxxxxxxxxxxxxxx

JWT_SESSION_SECRET=supersecretkey
JWT_FIRST_ACCESS_SECRET=supersecretkey
PASSWORD_SALT_ROUNDS=10

WEB_URL=http://localhost:5173

Significado das variáveis

PORT: porta lógica da API (observação: atualmente o servidor inicia fixo em 7654 no código)
POSTGRES_USER: usuário do banco PostgreSQL
POSTGRES_PASSWORD: senha do banco PostgreSQL
POSTGRES_DB: nome do banco
POSTGRES_PORT: porta do PostgreSQL
POSTGRES_ENDPOINT: host:porta do PostgreSQL
RESEND_API_KEY: chave da API de envio de e-mails (ativação e recuperação)
JWT_SESSION_SECRET: segredo para token de sessão
JWT_FIRST_ACCESS_SECRET: segredo adicional de primeiro acesso
PASSWORD_SALT_ROUNDS: custo do hash bcrypt
WEB_URL: URL da aplicação frontend para CORS e links de e-mail

Frontend

Arquivo: apps/web/.env (opcional)

VITE_API_URL=http://localhost:7654

Significado

VITE_API_URL: base URL da API consumida no frontend.
Se não for definido, o frontend usa http://localhost:7654 por padrão.

🗄 Banco de Dados

1) Criar banco via Docker (recomendado para dev)

npm run compose:dev:up

Comando acima sobe o PostgreSQL com base no arquivo docker-compose.dev.yml e no .env do backend.

2) Rodar migrations

npm run db:migrate --workspace @librix/api

3) Gerar nova migration

Há 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_migration

4) Atualizar schema com novas migrations

npm run db:migrate --workspace @librix/api

5) Resetar banco (desenvolvimento)

cd apps/api
npx dotenv -e .env -- sequelize-cli db:migrate:undo:all
npx dotenv -e .env -- sequelize-cli db:migrate

6) Seed

Atualmente não há script de seed versionado no projeto.

Para popular dados, use os endpoints administrativos após autenticação.

▶️ Rodando o Projeto

Backend

npm run dev --workspace @librix/api

API disponível em: http://localhost:7654

Frontend

npm run dev --workspace @librix/web

Frontend disponível em: http://localhost:5173 (padrão Vite)

👤 Usuário Administrador

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.

📜 Scripts Disponíveis

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

🔄 Fluxo da Aplicação

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)

🔐 Controle de Permissões

O sistema usa feature flags com bitfield em @librix/flags.

Administrador

Pode:

gerenciar usuários
gerenciar livros
gerenciar empréstimos
acessar relatórios
acessar dashboard administrativo

Bibliotecário / Gestor (perfil intermediário)

Pode:

gerenciar livros
gerenciar empréstimos
visualizar/editar usuários (conforme features atribuídas)

Leitor

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.

🧭 Rotas Principais

Públicas

/
/home
/books
/books/:id
/login
/register
/forgot-password
/reset-password/:token
/activate-account
/users/activate
/users/activate/invalid

Protegidas (usuário autenticado)

/profile
/my-loans
/favorites

Administrativas

/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.

🌐 API

Base local padrão:

http://localhost:7654

Documentação Swagger local:

http://localhost:7654/api-docs
http://localhost:7654/swagger.json

Frontend consome API via helper (getApiUrl) em:

apps/web/src/helpers/api-url.ts

🖼 Uploads

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

Limites e formatos

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.)

🔑 Recuperação de Senha

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

📄 Paginação

Padrão implementado em endpoints list:

GET /books/all?page=1&limit=20
GET /users?page=1&limit=10
GET /loans?page=1&limit=10
GET /loans/my-loans?page=1&limit=10

Resposta segue formato semelhante:

{
  "data": [],
  "page": 1,
  "limit": 10,
  "total": 0,
  "totalPages": 0
}

🔎 Busca

Exemplos reais:

GET /books/all?search=harry
GET /users?search=joao
GET /loans?search=maria

🧪 Filtros

Exemplos disponíveis hoje:

GET /books/all?author=Machado
GET /books/all?category=Romance
GET /books/all?isbn=978
GET /books/all?availability=true

GET /users?status=ACTIVE

GET /loans?status=BORROWED
GET /loans?status=LATE
GET /loans?status=RETURNED

Ordenação também disponível em listagens:

GET /books/all?sortBy=title&sortOrder=ASC
GET /users?sortBy=name&sortOrder=DESC

🛠 Desenvolvimento

Fluxo 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

📐 Boas Práticas

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 any que podem ser gradualmente eliminados.

📄 Licença

Projeto licenciado sob MIT.

Consulte o arquivo LICENSE na raiz para o texto completo.

📬 Contato

Responsável atual pelo repositório:

João Pinho — jvopinho.contato@gmail.com

Repositório:

https://github.com/jvopinho/librix

Name		Name	Last commit message	Last commit date
Latest commit History 21 Commits
apps		apps
migrations		migrations
packages		packages
public		public
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
docker-compose.dev.yml		docker-compose.dev.yml
package.json		package.json
tsconfig.eslint.json		tsconfig.eslint.json
yarn.lock		yarn.lock

Folders and files

Latest commit

History

Repository files navigation

📚 Librix

📌 Índice

🚀 Funcionalidades

Implementadas no estado atual

Em progresso ou parcialmente disponível

🧰 Tecnologias Utilizadas

Frontend

Backend

Banco de dados

Outros

🗂 Estrutura do Projeto

✅ Pré-requisitos

📥 Clonando o Projeto

📦 Instalando as Dependências

⚙️ Configuração do Ambiente

Backend

Significado das variáveis

Frontend

Significado

🗄 Banco de Dados

1) Criar banco via Docker (recomendado para dev)

2) Rodar migrations

3) Gerar nova migration

4) Atualizar schema com novas migrations

5) Resetar banco (desenvolvimento)

6) Seed

▶️ Rodando o Projeto

Backend

Frontend

👤 Usuário Administrador

📜 Scripts Disponíveis

🔄 Fluxo da Aplicação

🔐 Controle de Permissões

Administrador

Bibliotecário / Gestor (perfil intermediário)

Leitor

🧭 Rotas Principais

Públicas

Protegidas (usuário autenticado)

Administrativas

🌐 API

🖼 Uploads

Limites e formatos

🔑 Recuperação de Senha

📄 Paginação

🔎 Busca

🧪 Filtros

🛠 Desenvolvimento

📐 Boas Práticas

📄 Licença

📬 Contato

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages