• Sobre o Projeto
• Tecnologias
• Arquitetura do banco de dados
• Pré-requisitos
• Instalação
• Configuração do Ambiente
• Executando o Projeto
• Docker
• Banco de Dados
• Estrutura do Projeto
• Padrões de Código
• API Endpoints
• Autenticação
• Variáveis de Ambiente

Backend RESTful desenvolvido com Node.js e Express para gerenciar dados de saúde, implementando autenticação JWT e integração com banco de dados PostgreSQL via Prisma ORM.

• Node.js v20.19.4 ou superior
• npm 11.6.0 ou superior
• Docker e Docker Compose (para execução containerizada)
• Git para versionamento

• Node.js e npm v20.19.4 ou superior

  • Windows - NodeJS Download
  • Mac - brew install node@24
  • Linux/ubuntu - brew install node@24

• Docker e Docker Compose (para execução containerizada)

  • Windows - utilizar Docker Desktop
  • Mac - Docker Engine
  • Linux/ubuntu - Docker Engine

• Git para versionamento

  • Windows - https://git-scm.com/install/windows
  • Mac - https://git-scm.com/install/mac
  • Linux/ubuntu - https://git-scm.com/install/linux

• python

  • Windows - https://www.python.org/downloads/windows/
  • Mac - https://www.python.org/downloads/macos/
  • Linux/ubuntu - https://www.python.org/downloads/source/

git clone https://github.com/designsystematomic-blip/dados-saude-backend
cd ./dados-saude-backend

npm install

1. Copie o arquivo .env.example para .env:

cp .env.example .env

• Inicialize o docker
• Na raiz do projeto, rodar o comando docker compose up -d

Será utilizado o localstack para configurar o S3 Bucket da AWS localmente, esse serviço permite o armazenamento de imagens em um storage e disponibiliza as URLs da imagem, o que é mais recomendado para lidar do que realizar a subida dos arquivos diretamente no banco de dados Postgres. Documentação referencia para o processo de subida de arquivos: https://github.com/dockersamples/todo-list-localstack-docker

python3 -m venv .venv

	source .venv/bin/activate

	pip3 install awscli-local

	awslocal --version

Sempre que for trabalhar com o projeto, é necessário ativar o ambiente virtual primeiro usando:

  source .venv/bin/activate

awslocal configure

Configurar os valores solicitados como:

• AWS Access Key ID: test
• AWS Secret Access Key: test
• Default region name: us-east-1

python -m venv .venv

.venv\Scripts\activate

pip install awscli

	aws --version

Sempre que for trabalhar com o projeto, é necessário ativar o ambiente virtual primeiro usando:

	.venv\Scripts\activate

  aws configure

Configurar os valores solicitados como:

• AWS Access Key ID: test
• AWS Secret Access Key: test
• Default region name: us-east-1

Uma vez que a CLI da AWS está instalada e configurada, assim como o docker inicializado, para criar o bucket basta seguir:

		awslocal s3 mb s3://dados-saude-bucket-exames

		aws s3 mb s3://dados-saude-bucket-exames --endpoint-url=http://localhost:4566

		awslocal s3 ls

		aws s3 ls

Caso tenha erro de permissão ao rodar o docker. Para dar permissão para criar o volume da localstack

		mkdir -p localstack && chmod 755 localstack

5. Configure as variáveis conforme seu ambiente (desenvolvimento, teste, produção):

5.1 Gere uma chave de segurança criptografada para a variável JWT_SECRET

Você pode gerar uma chave secreta forte usando o comando abaixo:

node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"

Arquivo .env

# Banco de Dados
DATABASE_URL="postgresql://postgres:postgres@localhost:5444/dados_saude_db"

# JWT
JWT_SECRET="sua-chave-secreta-super-segura"
JWT_EXPIRATION="24h"

# Server
PORT=8000
NODE_ENV="development"

# AWS S3 (Opcional)
AWS_REGION="us-east-1"
AWS_ACCESS_KEY_ID="sua-chave-id"
AWS_SECRET_ACCESS_KEY="sua-chave-secreta"
AWS_S3_BUCKET_NAME="seu-bucket-name"

npx prisma generate

As migrations gerenciam o versionamento do banco de dados.

npx prisma migrate dev

npx prisma studio

npm run dev

O servidor estará disponível em: http://localhost:8000

• Desenvolvimento: .env (local)
• Docker: .env.docker (containerizado)
• Exemplo: .env.example (template)

docker-compose up -d

Isso irá:

• Iniciar o container PostgreSQL na porta 5444
• Preparar o banco de dados

Caso resulte em algum erro de permissão na pasta localstack_data, executar:

chmod 755 localstack_data

docker build -t dados-saude-backend:latest .

docker-compose down

docker-compose logs -f

docker-compose down -v

npx prisma generate

As migrations gerenciam o versionamento do banco de dados.

npx prisma migrate dev --name nome_da_migration

npx prisma migrate status

npx prisma migrate reset

Para visualizar e gerenciar dados graficamente:

npx prisma studio

Acesse: http://localhost:5555

src/
├── app.ts                 # Configuração principal do Express
├── config/
│   └── database.ts        # Configuração do Prisma
├── controllers/           # Lógica de requisição/resposta
│   ├── health.controller.ts
│   └── user.controller.ts
├── middlewares/           # Middlewares personalizados
│   └── auth.middleware.ts
├── repository/            # Camada de dados (Data Access)
│   ├── exam/
│   └── user/
├── routes/                # Definição de rotas
│   ├── health.routes.ts
│   └── ...
├── types/                 # Tipos TypeScript
└── utils/                 # Funções utilitárias
prisma/
├── schema.prisma          # Modelo de dados
└── migrations/            # Histórico de mudanças do BD

Este projeto segue a arquitetura MVC (Model-View-Controller) com padrão Repository para acesso a dados:

• Models: Definidos em prisma/schema.prisma
• Controllers: Lógica de negócio em src/controllers/
• Routes: Endpoints em src/routes/
• Repository: Acesso a dados em src/repository/
• Middlewares: Autenticação e validação em src/middlewares/

{
  "success": boolean,
  "statusCode": number,
  "data": object | null,
  "message": string,
  "timestamp": string
}

O projeto utiliza JWT (JSON Web Token) para autenticação.

1. Usuário faz login com email e senha
2. Backend valida credenciais
3. Backend gera JWT com informações do usuário
4. Cliente armazena JWT (cookie/localStorage)
5. Cliente envia JWT em requisições subsequentes no header Authorization

Authorization: Bearer seu_token_jwt_aqui

GET /health

Resposta:

{
  "status": "ok",
  "timestamp": "2025-01-15T10:30:00Z"
}

POST /users/register
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "senha123",
  "name": "João Silva"
}

Resposta (201):

{
  "success": true,
  "statusCode": 201,
  "data": {
    "id": "uuid",
    "email": "[email protected]",
    "name": "João Silva"
  },
  "message": "Usuário criado com sucesso"
}

POST /users/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "senha123"
}

Resposta (200):

{
  "success": true,
  "statusCode": 200,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": "uuid",
      "email": "[email protected]",
      "name": "João Silva"
    }
  },
  "message": "Login realizado com sucesso"
}

Para desenvolvimento local, usamos LocalStack para emular os serviços AWS, incluindo S3.

• Docker e Docker Compose rodando
• AWS CLI instalado localmente
• awslocal (wrapper da AWS CLI para LocalStack)

Windows (PowerShell Admin):

choco install awslocal

macOS/Linux:

pip install awslocal

Ou via npm:

npm install -g awslocal

docker-compose up -d

O LocalStack será iniciado na porta 4566.

Crie ou edite ~/.aws/credentials:

[default]
aws_access_key_id = test
aws_secret_access_key = test

Crie ou edite ~/.aws/config:

[default]
region = us-east-1
output = json

awslocal s3 mb s3://dados-saude-bucket

Verificar buckets criados:

awslocal s3 ls

Adicione no .env:

# AWS LocalStack (Desenvolvimento)
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=test
AWS_SECRET_ACCESS_KEY=test
AWS_S3_BUCKET_NAME=dados-saude-bucket
AWS_S3_ENDPOINT=http://localhost:4566

# Criar arquivo teste
echo "Teste de arquivo" > test.txt

# Upload para S3 local
awslocal s3 cp test.txt s3://dados-saude-bucket/

# Listar arquivos no bucket
awslocal s3 ls s3://dados-saude-bucket/

# Download do arquivo
awslocal s3 cp s3://dados-saude-bucket/test.txt ./downloaded.txt

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";

const s3Client = new S3Client({
  region: process.env.AWS_REGION,
  endpoint: process.env.AWS_S3_ENDPOINT, // http://localhost:4566
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  },
});

// Exemplo: Upload de arquivo
const params = {
  Bucket: process.env.AWS_S3_BUCKET_NAME,
  Key: "exames/exame-123.pdf",
  Body: fileContent,
  ContentType: "application/pdf",
};

await s3Client.send(new PutObjectCommand(params));

Para produção, altere as variáveis de ambiente:

AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=sua-chave-real
AWS_SECRET_ACCESS_KEY=sua-chave-secreta-real
AWS_S3_BUCKET_NAME=seu-bucket-real
# Remova AWS_S3_ENDPOINT ou deixe em branco

Para mais informações: Documentação LocalStack

Certifique-se de que o Docker está rodando:

docker-compose up -d

Regenere o Prisma Client:

npx prisma generate

Execute:

npx prisma migrate dev

MIT