sr-cardoso-backend

yurikrat's avatarfrom yurikrat

Backend Cloud Run/Express/Firestore do Sr Cardoso. Use quando criar ou alterar endpoints, auth JWT, regras de agenda, financeiro, branding, WhatsApp, cron jobs, ou modelagem Firestore.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 3, 2026⬇️1downloads
[Code Generation]

When & Why to Use This Skill

This Claude skill is a specialized backend development assistant designed for the Sr Cardoso platform, built on Express, Google Cloud Run, and Firestore. It streamlines the entire backend lifecycle, from architecting RESTful API endpoints and implementing JWT-based RBAC security to managing complex business logic for scheduling, finance, and automated WhatsApp notifications.

Use Cases

  • Developing and updating Express.js endpoints with integrated Zod validation and shared TypeScript contracts across the codebase.
  • Implementing complex Firestore data modeling and transaction-safe operations for barbershop scheduling, including slot validation and timezone management.
  • Configuring secure Role-Based Access Control (RBAC) using JWT claims to protect administrative and master-level backend routes.
  • Automating background processes and system maintenance through protected Cron jobs and managing cloud-based branding assets via GCP Storage.
  • Integrating third-party services like the Evolution API for automated WhatsApp notifications and financial tracking systems.
namesr-cardoso-backend
descriptionBackend Cloud Run/Express/Firestore do Sr Cardoso. Use quando criar ou alterar endpoints, auth JWT, regras de agenda, financeiro, branding, WhatsApp, cron jobs, ou modelagem Firestore.

Sr Cardoso Backend

Overview

Executar tarefas no backend Express/Cloud Run com Firestore, respeitando regras de negocio e contratos com o frontend.

Entradas e estrutura

  • Iniciar por apps/server/src/index.ts e apps/server/src/app.ts.
  • Usar apps/server/src/routes/public.ts para rotas publicas.
  • Usar apps/server/src/routes/admin.ts para rotas admin e RBAC.
  • Usar apps/server/src/lib/* para auth, finance, branding e Evolution API.
  • Usar apps/server/src/services/whatsappNotifications.ts para envios automaticos.

Auth e RBAC

  • Usar requireAdmin e requireMaster de apps/server/src/lib/adminAuth.ts.
  • Manter claims: role, username, barberId.
  • Manter token JWT HS256 com ADMIN_JWT_SECRET.

Modelagem Firestore (resumo)

  • barbers, bookings, customers, adminUsers.
  • Subcolecao barbers/{barberId}/slots.
  • Configs em settings/finance, settings/branding, settings/whatsapp-notifications.
  • Filas em whatsappMessageQueue e whatsappOutbound.

Regras de agenda

  • Usar timezone America/Sao_Paulo.
  • Validar slots em 30 minutos e domingo fechado.
  • Respeitar schedule configurado do barbeiro.

Quando criar/alterar endpoints

  • Validar input com Zod (preferir schemas de packages/shared).
  • Atualizar tipos/contratos em packages/shared se necessario.
  • Atualizar apps/web/src/lib/api.ts para refletir novos endpoints.
  • Verificar necessidade de index em firebase/firestore.indexes.json.

Transacoes Firestore

  • Ler documentos antes de escrever dentro da transacao.
  • Usar FieldValue.serverTimestamp() para createdAt/updatedAt.

Cron

  • Proteger /api/cron/* com CRON_SECRET.
  • Aceitar x-cron-secret ou x-cron-key.

Branding e upload

  • Usar apps/server/src/lib/branding.ts.
  • Requer GCP_STORAGE_BUCKET e permissao da service account.

Observacoes

  • Evitar Firebase SDK no frontend; toda escrita deve passar pelo backend.
  • apps/functions e legado; nao usar como fonte de verdade.