LatesOS

Plataforma de gestao operacional para clinicas de Pilates e Fisioterapia.

Página institucional: https://latesos.netlify.app

Sumario

• Visao Executiva
• Problema de Negocio
• Solucoes Entregues pelo LatesOS
• Arquitetura da Plataforma
• Fluxo de Agendamentos com Kafka e Banco
• Modelo de Dados Principal
• Modulos do Sistema
• Tecnologias
• Como Executar Localmente
• Ambientes e Configuracoes
• Qualidade e Observabilidade
• Seguranca
• Roadmap Tecnico
• Documentacao Complementar

Visao Executiva

O LatesOS e uma plataforma de gestao completa para operacao clinica, integrando atendimento, agenda, financeiro e analise gerencial em uma unica solucao.

A proposta e reduzir retrabalho operacional e aumentar previsibilidade de receita, organizando o ciclo completo da clinica:

• captacao e cadastro,
• agendamento e execucao,
• cobranca e recorrencia,
• analise de eficiencia e auditoria.

Problema de Negocio

Clinicas de Pilates e Fisioterapia frequentemente enfrentam os seguintes gargalos:

• Dados espalhados em ferramentas diferentes (agenda, planilha, WhatsApp, anotacoes locais).
• Falta de rastreabilidade sobre cancelamentos, no-show e remarcacoes.
• Dificuldade em controlar mensalidades, planos e recebimentos recorrentes.
• Ausencia de indicadores confiaveis para tomada de decisao da gestao.
• Dependencia de processos manuais para orcamentos e comunicacao entre equipes.

Impactos diretos:

• perda de receita,
• baixa produtividade de recepcao,
• experiencia inconsistente para cliente,
• visibilidade limitada para crescimento sustentavel.

Solucoes Entregues pelo LatesOS

O sistema resolve esses pontos com uma arquitetura orientada a dominio clinico:

• Fonte unica de verdade para clientes, profissionais, agenda e financeiro.
• Agenda inteligente com validacoes de conflito, remarcacao e cancelamento tipado.
• Financeiro recorrente com status de mensalidade/plano e baixa automatica de pagamento.
• Relatorios gerenciais de eficiencia por profissional e auditoria de abertura de agendamento.
• Orcamento em PDF padronizado para acelerar fechamento comercial.
• Eventos assincronos via Kafka para evolucao de notificacoes e integracoes.

Arquitetura da Plataforma

flowchart LR
    FE[Frontend Angular] -->|JWT| API[Backend NestJS]
    API --> DB[(PostgreSQL)]
    API --> KAFKA[(Kafka)]
    API --> RABBIT[(RabbitMQ - opcional)]

Loading

Fluxo de Agendamentos com Kafka e Banco

sequenceDiagram
    autonumber
    participant U as Usuario (Recepcao/Admin)
    participant FE as Frontend
    participant API as Schedulings API
    participant DB as PostgreSQL
    participant K as Kafka
    participant N as Servico de Notificacao

    U->>FE: Criar agendamento
    FE->>API: POST /schedulings (JWT)
    API->>DB: Validar cliente/profissional/disponibilidade
    API->>DB: Persistir scheduling
    API->>K: Publicar evento scheduling.created
    API-->>FE: Retorna agendamento criado
    K-->>N: Entrega evento para processamento assincrono
    N->>N: Envio de notificacoes / automacoes

Loading

Modelo de Dados Principal

erDiagram
    USERS ||--o| CLIENTS : "perfil cliente"
    USERS ||--o| PROFESSIONALS : "perfil profissional"
    USERS ||--o{ SCHEDULINGS : "createdBy"

    CLIENTS ||--o{ SCHEDULINGS : "possui"
    PROFESSIONALS ||--o{ SCHEDULINGS : "atende"
    PROFESSIONALS ||--o{ AVAILABILITIES : "define"

    CLIENTS ||--o{ CLIENT_BILLINGS : "gera recorrencia"
    CLIENTS ||--o{ FINANCIAL_TRANSACTIONS : "referencia"

    USERS {
      uuid id PK
      string name
      string email UK
      string passwordHash
      enum role
      bool isActive
      datetime createdAt
    }

    CLIENTS {
      uuid id PK
      uuid userId FK
      enum plan
      int creditsRemaining
      date birthDate
      string emergencyContact
      text anamnesis
    }

    PROFESSIONALS {
      uuid id PK
      uuid userId FK
      string specialty
      string bio
    }

    AVAILABILITIES {
      uuid id PK
      uuid professionalId FK
      enum dayOfWeek
      time startTime
      time endTime
      int maxConcurrentClients
    }

    SCHEDULINGS {
      uuid id PK
      uuid clientId FK
      uuid professionalId FK
      uuid createdById FK
      datetime startAt
      datetime endAt
      enum status
      enum cancellationType
      string cancellationReason
      string notes
    }

    FINANCIAL_TRANSACTIONS {
      uuid id PK
      uuid clientId FK
      string description
      numeric amount
      enum type
      enum paymentMethod
      enum cardBrand
      int installments
      string category
      datetime occurredAt
    }

    CLIENT_BILLINGS {
      uuid id PK
      uuid clientId FK
      enum cycle
      date referencePeriod
      date dueDate
      enum status
      numeric amount
      datetime paidAt
    }

Loading

Modulos do Sistema

• Auth
  • Login, refresh token e logout.
  • Controle por perfis (ADMIN, RECEPTIONIST, PROFESSIONAL, CLIENT).
• Clientes
  • CRUD completo, plano, creditos e anamnese.
  • Busca e manutencao de dados clinicos.
• Profissionais
  • CRUD, especialidades e disponibilidade semanal.
  • Base para calculo de slots disponiveis.
• Agenda
  • Criacao, check-in manual de presenca, remarcacao, conclusao e cancelamento com motivo.
  • Regras para evitar conflito e horario invalido.
• Financeiro
  • Entradas/saidas e dashboard de fluxo.
  • Assinaturas recorrentes (mensal, trimestral, anual).
• Relatorios
  • Eficiencia por profissional.
  • Auditoria de abertura e resultado dos agendamentos.
• Servicos e Orcamento
  • Catalogo de servicos.
  • Geracao de orcamento em PDF.

Tecnologias

Backend

• NestJS 11
• TypeORM
• PostgreSQL
• JWT
• Kafka
• RabbitMQ (habilitavel)
• Swagger/OpenAPI

Frontend

• Angular 21 (standalone)
• TypeScript
• SCSS
• RxJS

Como Executar Localmente

1) Infraestrutura

Opcional com Docker:

docker compose up -d postgres rabbitmq kafka

2) Backend

cd backend
npm install
npm run migration:run
npm run start:dev

API: http://localhost:3000
Swagger: http://localhost:3000/api

3) Frontend

cd frontend
npm install
npm run start

Aplicacao: http://localhost:4200

Ambientes e Configuracoes

Variaveis sensiveis ficam no .env do backend.

Credenciais seed padrao (conforme ambiente local):

• Email: admin@pilatesos.com
• Senha: admin123

Marca visual:

• frontend/public/assets/logo.png

Qualidade e Observabilidade

• Validacao de entrada com class-validator.
• Interceptor global para padronizacao de resposta.
• Estrutura preparada para evoluir monitoramento (logs, metricas e alertas).
• Testes unitarios presentes em modulos criticos (ex.: seeds e agenda).

Testes Automatizados

• Backend: cd backend && npm run test:ci
• Frontend: cd frontend && npm run test:ci
• Mobile: cd mobile-app && npm run test:ci
• Suite completa (todos os projetos): powershell -ExecutionPolicy Bypass -File .\scripts\run-all-tests.ps1

Seguranca

• Autenticacao JWT com refresh token.
• Guardas por role para controle de autorizacao.
• CORS configuravel por ambiente.
• Recomendado para producao:
  • rotacao de segredos,
  • HTTPS,
  • rate limit,
  • politicas de backup e restore.

Documentacao Complementar

• Backend README
• Frontend README