📚 Biblioteca Fullstack

Sistema web para gerenciamento de biblioteca, com catálogo de títulos, acompanhamento de progresso, dashboard administrativo, autenticação e integração com dados externos.

🛠️ Stack

Frontend

Backend

Banco de Dados & Infraestrutura

✨ Funcionalidades

📚 Catálogo

• Gerenciamento de títulos
• Cadastro e edição de informações
• Organização do catálogo
• Consulta de títulos
• Controle de temporadas e episódios
• Integração com dados do TMDB

▶️ Progresso

• Acompanhamento do progresso de séries
• Controle de episódios assistidos
• Controle de temporadas
• Seção de conteúdos em andamento
• Exibição de progresso agregado

📊 Dashboard

• Indicadores gerais da biblioteca
• Estatísticas de progresso
• Dados agregados do catálogo
• Consultas otimizadas para evitar N+1

👥 Usuários

O sistema possui diferentes níveis de acesso:

Perfil	Permissões
USER	Acesso às funcionalidades da biblioteca
ADMIN	Gerenciamento administrativo e catálogo

🔐 Autenticação

• Login e cadastro
• Autenticação baseada em JWT
• Access Tokens
• Refresh Tokens
• Cookies HTTP-only
• Controle de acesso por perfil
• Proteção das rotas administrativas

🔎 Integração TMDB

• Importação de informações de títulos
• Importação de temporadas
• Busca de dados externos
• Processamento transacional
• Consultas paralelas de temporadas
• Cache das consultas utilizando Redis

⚡ Performance

• Redis para cache
• Cache de dados externos com TTL
• Rate limiting baseado em IP
• Queries agregadas
• Redução de consultas desnecessárias
• Paginação com limite de até 100 registros

📁 Estrutura

biblioteca/
│
├── backend/
│   ├── app/
│   │   ├── main.py
│   │   ├── core/
│   │   │   ├── config/
│   │   │   ├── security/
│   │   │   ├── redis/
│   │   │   └── errors/
│   │   │
│   │   ├── models/
│   │   ├── schemas/
│   │   ├── services/
│   │   ├── api/
│   │   │   └── routers/
│   │   └── scripts/
│   │
│   ├── alembic/
│   │   └── versions/
│   │
│   ├── tests/
│   └── requirements-dev.txt
│
├── frontend/
│   ├── src/
│   │   ├── app/
│   │   ├── components/
│   │   ├── lib/
│   │   └── proxy.ts
│   │
│   └── package.json
│
├── docker-compose.yml
└── README.md

🐳 Como executar com Docker

Configure as variáveis de ambiente:

cp .env.example .env

Defina um JWT_SECRET seguro e execute:

docker compose up --build

🌐 Acessos

Frontend:

http://localhost:3000

API e Swagger:

http://localhost:8080/docs

👑 Criando o primeiro administrador

O cadastro cria inicialmente usuários com o perfil USER.

Para promover um usuário a administrador:

docker compose exec backend \
python -m app.scripts.promote_admin seu@email.com

💻 Execução local

Pré-requisitos

• Node.js 20.9+
• Python 3.12+
• PostgreSQL
• Redis

PostgreSQL e Redis podem ser iniciados utilizando:

docker compose up postgres redis

Backend

cd backend

python -m venv .venv
source .venv/bin/activate

pip install -r requirements-dev.txt

cp .env.example .env

alembic upgrade head

uvicorn app.main:app --reload --port 8080

Frontend

Em outro terminal:

cd frontend

cp .env.example .env.local

npm install

npm run dev

Configure:

API_URL=http://localhost:8080

🧪 Testes

Os testes de integração utilizam PostgreSQL e Redis.

Banco de testes:

biblioteca_test

Redis:

Database 15

Para executar:

createdb -h localhost -U biblioteca biblioteca_test

pytest

🔐 Segurança

A aplicação utiliza:

• JWT
• Bcrypt
• Cookies HTTP-only
• Controle de acesso baseado em perfil
• Rate limiting por IP
• Refresh Tokens
• Redis para gerenciamento de sessões e cache

O JWT_SECRET é obrigatório e deve possuir no mínimo 32 caracteres.

Exemplo para gerar uma chave:

openssl rand -base64 64

⚙️ Regras de Negócio

Administração

Funcionalidades administrativas são disponibilizadas exclusivamente para usuários ADMIN.

Catálogo

Usuários administrativos podem adicionar, editar e excluir títulos, temporadas e episódios.

Progresso

O sistema calcula o progresso utilizando consultas agregadas para evitar consultas individuais desnecessárias.

Importação

A importação de dados externos é realizada de forma transacional. Falhas durante a comunicação com o serviço externo são tratadas pela API.

Continuação

A área de conteúdos em andamento apresenta uma entrada por série, evitando duplicação.

🔧 Variáveis de Ambiente

Backend

Arquivo:

backend/.env.example

Principais variáveis:

DATABASE_URL=
REDIS_URL=
JWT_SECRET=
JWT_EXPIRATION_MS=
JWT_REFRESH_EXPIRATION_MS=
APP_CORS_ALLOWED_ORIGINS=
APP_COOKIE_SECURE=
APP_RATE_LIMIT_WINDOW_MS=
APP_RATE_LIMIT_MAX_ATTEMPTS=
APP_TRUST_FORWARDED_FOR=
TMDB_API_KEY=

A TMDB_API_KEY aceita chave da API v3 ou token v4.

Frontend

API_URL=

A variável API_URL é utilizada durante o build do frontend para configurar as rotas da API.

🚀 Deploy

A aplicação pode ser implantada utilizando:

• Railway
• Render
• PostgreSQL gerenciado
• Redis gerenciado

A arquitetura de produção utiliza serviços separados para:

Frontend
   ↓
Backend
   ↓
PostgreSQL
   +
Redis

No frontend, configure API_URL como variável de build apontando para o backend.

No backend:

APP_COOKIE_SECURE=true

📌 Status

Projeto em desenvolvimento, com arquitetura fullstack baseada em Next.js, Python e FastAPI, focada em gerenciamento de biblioteca, autenticação, catálogo, acompanhamento de progresso e dashboard administrativo.