Projeto Portaria
Portaria virtual para prédios residenciais e comerciais. O visitante escaneia um QR na entrada, o morador valida por videochamada e autoriza a entrada — com operador humano de retaguarda para quando ninguém atende.
Este repositório contém, por enquanto, a especificação e os prompts de implementação. Nenhum código de aplicação foi escrito ainda.
Como usar
Leia docs/ na ordem, depois execute prompts/ fase por fase. Cada prompt referencia as seções dos documentos que precisa respeitar — os documentos são a fonte de verdade, os prompts são o roteiro.
Não pule fases e não junte duas num prompt só. O fatiamento existe porque as áreas de maior risco (WebRTC, notificação de chamada no iOS, LGPD) são exatamente as que um prompt monolítico implementa pela metade.
Documentos
| Documento | Conteúdo |
|---|---|
00-VISAO-E-PRODUTO |
Problema, personas, jornadas, planos comerciais, escopo, métricas |
01-ARQUITETURA |
Espinha. Stack, monorepo, os 7 padrões de robustez, ADRs |
02-MODELO-DE-DADOS |
Schema Postgres, outbox, fila, retenção, RLS preparada |
03-FLUXOS-E-CONTRATOS |
Máquinas de estado, REST, WebSocket, idempotência |
04-DESIGN-SYSTEM-UX |
Tokens, telas, movimento, acessibilidade |
05-INFRA-DOCKER |
Compose, LiveKit, portas, banda, observabilidade, CI/CD |
06-LGPD-E-SEGURANCA |
Bases legais, modelo de ameaças, direitos do titular |
07-REQUISITOS-DE-CAMPO |
Pré-requisitos contratuais de instalação, não backlog |
Fases
| Fase | Entrega |
|---|---|
| 0 — Bootstrap | Monorepo, Docker, CI verde |
| 1 — Domínio e dados | shared/ KMP, schema, outbox, fila, auth |
| 2 — API | REST, WebSocket, mídia, ciclo de vida da visita |
| 3 — Web do visitante | PWA, ambos os funis, espera narrada |
| 4 — Chamada | LiveKit, tokens, degradação graciosa |
| 5 — App do morador | Compose MP, FCM, PushKit/CallKit |
| 6 — Painel admin | Auditoria, gestão, reconciliação |
| 7 — Escalonamento | Fila de operador, app do operador, recado |
| 8 — Planos e LGPD | Feature flags, retenção, direitos, SLOs |
| 9 — Hardening | E2E, carga, falhas, segurança, piloto |
Stack
Backend Spring Boot 3 + Kotlin · PostgreSQL 17 + PostGIS · jOOQ · Flyway Apps Compose Multiplatform (Android + iOS) · Web Vite + React + TS Compartilhado Kotlin Multiplatform (DTOs + máquina de estados) Mídia LiveKit self-hosted + coturn · Objetos MinIO/S3 Infra Docker Compose + Traefik · OpenTelemetry + Prometheus + Grafana + Loki
As decisões que mais importam
O modelo é híbrido, não autônomo. O morador é chamado primeiro — é a tese do produto. Mas a taxa de atendimento nunca é 100%, e o mercado consolidado usa operador humano 24h justamente por isso. Por isso vendemos dois planos, com o operador como retaguarda paga.
Entrega tem funil próprio. É a maioria do volume, e o entregador não espera videochamada. Foto do pacote, um toque, meta de 10s.
A busca de unidade é cega. A API nunca confirma se uma unidade existe — nem pelo corpo da resposta, nem pelo tempo. Sem isso, qualquer pessoa com o QR mapeia quem mora onde.
A base legal é legítimo interesse, não consentimento. Consentimento sob "aceite ou não entre" não é livre, e portanto não é válido. O que se faz é informar com clareza e arquivar a LIA.
Sem reconhecimento facial. Elevaria os dados a sensíveis, sem base legal disponível. Decisão jurídica, não limitação técnica.
iOS exige PushKit + CallKit. Notificação comum não faz o telefone tocar como chamada. Sem isso, o app não funciona como portaria.
Wi-Fi e botão físico são contratuais. Hall blindado não pega 4G, e nem todo visitante tem smartphone com bateria. Nenhum código resolve isso.
Primeiro passo
Antes da FASE 4, derrube o maior risco técnico: suba livekit-server + coturn e feche uma chamada entre um navegador móvel em 4G real e um Android, medindo o tempo até o primeiro frame. É barato de testar e caro de descobrir tarde.