Multi-Tenant SaaS Platform | TypeScript

Plataforma de backend SaaS multilocatário

Visão geral do projeto

Um backend robusto e pronto para produção orientado por API desenvolvido com NestJS, projetado para aplicativos de software como serviço de nível empresarial.

Primeiros passos

Guia rápido para configurar e executar a plataforma.

Visão geral da arquitetura

Ciclo de vida da solicitação visual

graph TD
    A[Client Request] --> B[Global Guards: JWT & RBAC]
    B --> C[Global Interceptors: Logging/Transform]
    C --> D[Feature Module: Controller]
    D --> E[Service Layer: Business Logic]
    E --> F[Repository Layer: Prisma ORM]
    F --> G[(PostgreSQL: Row Level Isolation)]
    
    subgraph Async Operations
        E --> H[BullMQ / Redis]
        H --> I[Worker: Email/Billing]
    end

Impacto de engenharia e interesse nacional

Padrões de arquitetura central

• Arquitetura Limpa: Separação clara entre camadas de apresentação, negócios e dados
• Injeção de Dependência: Sistema NestJS DI para código testável e de manutenção
• Organização do Módulo: Módulos baseados em recursos para escalabilidade
• Padrão de repositório: Acesso a dados abstraídos através do Prisma
• Validação DTO: Validação e transformação abrangente de entrada
• Tratamento de erros: Tratamento centralizado de erros com códigos de status HTTP adequados

Stack tecnológica

• Idioma: TypeScript 5.0+
• Tempo de execução: Node.js 18+
• Estrutura: NestJS 10+ (estrutura de backend de nível empresarial)
• Banco de dados: PostgreSQL 15+ (conformidade com ACID, segurança em nível de linha)
• ORM: Prisma 5+ (acesso ao banco de dados com segurança de tipo)
• Autenticação: JWT com Passport.js (autenticação sem estado)
• Autorização: Controle de acesso baseado em função (RBAC)
• Sistema de filas: Redis + BullMQ (processamento de trabalho em segundo plano)
• Validação: validador de classe + transformador de classe
• Conteinerização: Docker 24+ com compilações em vários estágios
• Teste: Jest 29+ com Supertest para testes E2E
• Registro: registro estruturado Winston

Recursos

Autenticação e Autorização

• Cadastro e login do usuário
• Autenticação baseada em JWT
• Controle de acesso baseado em função (Administrador/Usuário)
• Hash de senha com bcrypt

Multi-tenant

• Isolamento de dados baseado na organização
• Multi-tenant em nível de linha
• Os usuários pertencem a organizações

Módulos CRUD

• Usuários: Gerenciar usuários da organização
• Organizações: Gerenciamento somente de administrador
• Projetos: Projetos específicos da organização
• Tarefas: Tarefas específicas do projeto com atribuição

Todos os módulos incluem:

• Paginação
• Filtragem
• Classificando
• Validação de entrada
• Tratamento de erros

Processamento em segundo plano

• Simulação de envio de e-mail assíncrono (registrado no console)
• Novas tentativas de trabalho e tratamento de falhas (simplificado)
• Registro

Integração Externa

• Processamento de pagamento mocked Stripe
• Endpoint de webhook para eventos de pagamento

Teste

• Testes unitários para serviços
• Teste e2e básico para autenticação

Variáveis de ambiente

Crie um .env arquivo no diretório raiz:

# Database
DATABASE_URL="postgresql://username:password@localhost:5432/portfolio_saas?schema=public"

# JWT
JWT_SECRET="your-secret-key"
JWT_EXPIRES_IN="1h"

# Redis
REDIS_URL="redis://localhost:6379"

# Email (simulation)
EMAIL_HOST="smtp.gmail.com"
EMAIL_PORT=587
EMAIL_USER="[email protected]"
EMAIL_PASS="your-password"

# Payment (Stripe sandbox)
STRIPE_SECRET_KEY="sk_test_..."
STRIPE_WEBHOOK_SECRET="whsec_..."

Como executar localmente

Pré-requisitos

• Node.js (v18+)
• PostgreSQL
• Redis
• Docker (opcional)

Configuração local

1. Clonar o repositório

   git clone <repository-url>
   cd portfolio-saas-backend
   

2. Instalar dependências

   npm install
   

3. Configurar banco de dados

   # Start PostgreSQL and Redis locally or via Docker
   docker run --name postgres -e POSTGRES_USER=username -e POSTGRES_PASSWORD=password -e POSTGRES_DB=portfolio_saas -p 5432:5432 -d postgres:15
   docker run --name redis -p 6379:6379 -d redis:7-alpine
   

4. Configurar ambiente

   cp.env.example.env
   # Edit.env with your values
   

5. Execute migrações de banco de dados

   npm run prisma:migrate
   npm run prisma:generate
   

6. Inicie o aplicativo

   npm run start:dev
   

A API estará disponível em http://localhost:3000.

Configuração do Docker

1. Crie e execute com Docker Compose

   docker-compose up --build
   

Isso iniciará o aplicativo, PostgreSQL e o Redis.

API Documentação

Autenticação

Cadastre-se

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

{
  "email": "[email protected]",
  "password": "password123",
  "firstName": "John",
  "lastName": "Doe",
  "organizationId": "org-id"
}

Entrar

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

{
  "username": "[email protected]",
  "password": "password123"
}

Resposta:

{
  "access_token": "jwt-token-here"
}

Organizações (somente administrador)

Criar organização

POST /organizations
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "My Company"
}

Listar organizações

GET /organizations?page=1&limit=10&name=search
Authorization: Bearer <token>

Projetos

Criar projeto

POST /projects
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Website Redesign",
  "description": "Redesign company website"
}

Listar projetos

GET /projects?page=1&limit=10&name=search
Authorization: Bearer <token>

Tarefas

Criar tarefa

POST /tasks
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Design homepage",
  "description": "Create new homepage design",
  "projectId": "project-id"
}

Listar tarefas

GET /tasks?page=1&limit=10&status=pending
Authorization: Bearer <token>

Pagamentos

Criar intenção de pagamento

POST /payments/create-intent
Content-Type: application/json

{
  "amount": 1000,
  "currency": "usd"
}

Webhook

POST /payments/webhook
Content-Type: application/json
Stripe-Signature: <signature>

{
  "type": "payment_intent.succeeded",
  "data": {... }
}

Decisões de projeto

Multi-tenant

• Multi-tenant baseada em linha: Cada tabela inclui organizationId para isolamento de dados
• Prós: Simples, escalável, sem duplicação de esquema
• Contras: requer filtragem de consulta cuidadosa

Autenticação

• JWT com passaporte: Padrão da indústria, sem estado
• Baseado em funções: Funções simples de ADMIN/USUÁRIO
• Hash de senha: bcrypt para segurança

Trabalhos em segundo plano

• BullMQ com Redis: Sistema de fila confiável
• Simulação de e-mail: Registros em vez de envio real para demonstração

Integração de Pagamento

• Listra zombada: Simula o processamento de pagamento real
• Manipulação de webhook: Processamento básico de eventos

Banco de dados

• PostgreSQL: Robusto, compatível com ACID
• Prisma: ORM de tipo seguro, migrações, gerenciamento de esquema

Arquitetura

• Módulos NestJS: Organização baseada em recursos
• Injeção de dependência: Código testável e sustentável
• Validação: validador de classe para validação de entrada

Nota Técnica sobre Isolamento de Dados

A plataforma implementa uma estratégia de banco de dados compartilhado e esquema compartilhado. O isolamento de dados é aplicado no nível de serviço por meio de filtros OrganizationId obrigatórios em cada consulta. Esta abordagem equilibra a relação custo-benefício com a escalabilidade necessária para startups de alto crescimento.

Teste

# Unit tests
npm run test

# E2E tests
npm run test:e2e

# Coverage
npm run test:cov

Implantação

Este aplicativo é conteinerizado com Docker e pode ser implantado em qualquer plataforma de nuvem que suporte contêineres Docker (AWS ECS, Google Cloud Run, Azure Container Instances, etc.).

Para produção:

1. Use configurações específicas do ambiente
2. Configure migrações de banco de dados adequadas
3. Configurar monitoramento e registro
4. Implementar limitação de taxa
5. Adicionar versionamento de API
6. Configurar pipeline de CI/CD

Contribuindo

1. Siga o estilo de código existente
2. Escreva testes para novos recursos
3. Atualizar documentação
4. Use mensagens de commit significativas

Autor

Patrick Araujo - Engenheiro de Computação Para visualizar outros projetos e detalhes do portfólio, visite: https://pklavc.com/projects/

Este projeto demonstra recursos avançados de desenvolvimento de backend para aplicativos SaaS corporativos.