FastInBox | Documento tecnico de arquitetura
Arquitetura UML da Plataforma
Versao: 2.0 | Status: Aprovado para apresentacao academica | Data-base: 2026-04-10
Este documento descreve a arquitetura logica e comportamental do FastInBox por meio de visoes UML textuais, cobrindo fronteiras de contexto, contratos entre modulos, classes de dominio e sequencias operacionais criticas.
1. Objetivo arquitetural
O objetivo principal da arquitetura e garantir rastreabilidade ponta a ponta no fluxo de pedido white label: cadastro de paciente, configuracao de marmita, confirmacao, pagamento, encaminhamento para fabrica e atualizacao de entrega. A modelagem UML foi desenhada para reduzir ambiguidade entre front-end, back-end e operacao.
A arquitetura adota uma abordagem orientada a dominios de negocio com separacao funcional por perfil de usuario, o que facilita a evolucao por sprint e reduz acoplamento entre interface de uso e regra transacional.
2. Visao de contexto
2.1 Fronteiras de sistema
- Contexto Clinico: nutricionista, cadastro de pacientes, composicao de pedido.
- Contexto Comercial: calculo de valor final, comissao e confirmacao do pedido.
- Contexto Financeiro: validacao de pagamento e liberacao para producao.
- Contexto Operacional: fila da fabrica, status e consolidacao de entrega.
- Contexto de Governanca: monitoramento, auditoria e administracao global.
Decisao de arquitetura: nenhum evento de producao e aceito sem evento financeiro valido. Essa regra esta representada em todos os diagramas de sequencia de pedido.
3. Modelo de classes de dominio
3.1 Classes nucleares
| Classe | Responsabilidade | Atributos criticos |
|---|---|---|
| User | Identidade e perfil de acesso | id, role, email, permissions |
| Patient | Identificacao clinica do cliente final | id, nutritionGoal, restrictions, contactInfo |
| Order | Agregador principal do fluxo comercial | id, code, status, totalPrice, deliveryDate |
| OrderItem | Composicao de marmita no pedido | id, ingredients, packaging, quantity |
| Payment | Evento financeiro de autorizacao | id, method, status, approvedAt |
| ProductionEvent | Trilha operacional da fabrica | id, orderId, status, actorId, timestamp |
3.2 Relacoes chave
- User (nutricionista) 1:N Patient.
- Patient 1:N Order.
- Order 1:N OrderItem.
- Order 1:1 Payment (versao MVP) com possibilidade de N eventos no futuro.
- Order 1:N ProductionEvent para trilha historica completa.
4. Diagramas de sequencia (visao textual)
4.1 Criacao de pedido
- Nutricionista autentica e seleciona paciente.
- Interface coleta itens, ingredientes e parametros de entrega.
- Servico de dominio gera codigo unico e persiste Order + OrderItem.
- Sistema retorna codigo de acesso para jornada do paciente.
4.2 Confirmacao e pagamento
- Paciente acessa pedido por codigo e revisa composicao.
- Ao confirmar, pedido muda para aguardando pagamento.
- Gateway valida transacao e retorna autorizacao.
- Sistema registra Payment aprovado e muda Order para pago.
4.3 Producao
- Painel da fabrica lista apenas pedidos com Payment.status = approved.
- Operador move o pedido no kanban por estagios de fabrica.
- Cada mudanca gera ProductionEvent com autor e timestamp.
- Paciente e nutricionista visualizam status consolidado.
5. Principios de engenharia adotados
- Segregacao por responsabilidade: telas nao carregam regra de negocio sensivel.
- Persistencia orientada a estado: entidades transacionais possuem ciclo de vida explicito.
- Evolucao incremental: contratos de dominio preparados para migracao de store local para API.
- Auditabilidade: toda transicao critica de status possui trilha recuperavel.
- Resiliencia de apresentacao: aplicacao demonstravel sem dependencia externa para Sprint 1.
A modelagem foi priorizada para manter estabilidade de demonstracao hoje e baixo custo de migracao para arquitetura distribuida em sprint futura.
6. Riscos e mitigacoes
| Risco | Impacto | Mitigacao arquitetural |
|---|---|---|
| Acoplamento UI-regra | Alto | Centralizacao da regra em camada de dominio e contratos tipados. |
| Inconsistencia de status | Alto | State machine simples com transicoes controladas e eventos. |
| Escalabilidade futura | Medio | Estrutura de entidades pronta para persistencia server-side. |
| Rastreabilidade fraca | Alto | Modelo de ProductionEvent e historico de pagamento. |
7. Visao de componentes e responsabilidade
| Componente | Entrada principal | Saida principal | Dependencias |
|---|---|---|---|
| Modulo de autenticacao | Credenciais e perfil | Sessao de acesso e escopo | Store de sessao, regras de role |
| Modulo de pedidos | Paciente e itens | Order com codigo unico | Catalogo de itens, validacoes de dominio |
| Modulo de pagamento | Order em estado valido | Evento financeiro aprovado/rejeitado | Gateway financeiro e regras de transicao |
| Modulo de producao | Pedidos pagos | Timeline de status operacional | Kanban de fabrica e eventos de auditoria |
| Modulo administrativo | Dados consolidados | Indicadores e alertas de governanca | Pedidos, pagamentos e eventos operacionais |
8. Mapeamento RF -> componente
| Requisito | Componente primario | Componente de suporte |
|---|---|---|
| RF-001 Login por perfil | Modulo de autenticacao | Modulo administrativo |
| RF-003 Criacao de pedido | Modulo de pedidos | Modulo de autenticacao |
| RF-007 Pagamento e liberacao | Modulo de pagamento | Modulo de pedidos |
| RF-010 Fluxo da fabrica | Modulo de producao | Modulo de pagamento |
| RF-011 Status para paciente | Modulo de producao | Modulo de pedidos |
9. Estrategia de evolucao arquitetural
- Fase 1: consolidar contrato de dominio e estado transacional no front.
- Fase 2: mover persistencia e validacao critica para API server-side.
- Fase 3: introduzir observabilidade de eventos por componente.
- Fase 4: separar contexto financeiro e operacional para escala controlada.
A evolucao prevista preserva a semantica dos casos de uso e minimiza quebra de contrato entre interface e dominio.
10. Maquina de estados do pedido
| Estado | Origem | Proximo estado valido | Responsavel primario |
|---|---|---|---|
| rascunho | Pedido em composicao | aguardando_confirmacao | Nutricionista |
| aguardando_confirmacao | Codigo gerado e compartilhado | aguardando_pagamento | Paciente |
| aguardando_pagamento | Pedido revisado e confirmado | pago / cancelado | Paciente + gateway |
| pago | Evento financeiro aprovado | em_producao | Sistema / cozinha |
| em_producao | Fila operacional iniciada | pronto | Cozinha |
| pronto | Preparo concluido | em_entrega | Cozinha |
| em_entrega | Expedicao iniciada | entregue | Cozinha / operacao |
| entregue | Entrega confirmada | estado final | Sistema |
Esse encadeamento foi alinhado ao fluxo real do MVP e deve ser preservado em qualquer migracao futura para API e banco relacional.
11. Contratos de interface e navegacao
| Entrada de interface | Contrato esperado | Saida arquitetural |
|---|---|---|
| /login | Credenciais + papel de acesso | Sessao ativa e redirecionamento por role |
| /nutricionista/pedidos/novo | Paciente valido + itens + data de entrega | Order criado com codigo unico |
| /paciente/pedido/:code | Codigo de pedido valido | Pedido carregado para revisao |
| /paciente/pedido/:code/pagamento | Pedido confirmado | Evento Payment com resposta aprovada ou rejeitada |
| /cozinha/dashboard | Pedidos pagos e priorizados por etapa | Kanban operacional com mudanca auditavel |
| /admin/dashboard | Usuarios, pedidos e indicadores consolidados | Visao de governanca e excecoes |
12. Decisoes arquiteturais registradas
| ADR | Decisao | Motivacao | Impacto |
|---|---|---|---|
| ADR-01 | Store local no front na Sprint 1 | Garantir demonstracao publica sem dependencia externa | Entrega estavel para banca com plano de migracao posterior |
| ADR-02 | Rotas segregadas por perfil | Reduzir ambiguidade de permissao e contexto | Navegacao mais clara e menor risco de exposicao indevida |
| ADR-03 | Codigo unico para acesso do paciente | Simplificar onboarding e acelerar conversao | Entrada mais direta no trecho revisao -> pagamento |
| ADR-04 | Fila de cozinha restrita a pedidos pagos | Eliminar retrabalho e inconsistencias operacionais | Producao mais previsivel e rastreavel |