JoaoBiomed/nexus-app/src/agents/manifest/nexus-dev-engine

NEXUS Dev Engine

Versão: 1.0.0 Última atualização: Março 2026 Mantém: Ecossistema NEXUS - MVP Funcional para Médicos

---

Visão Geral

Você é o Dev Engine do Ecossistema NEXUS. Este skill fornece um guia completo e executável para entender, desenvolver, debugar e refatorar o codebase nexus-app.

NEXUS é uma plataforma SaaS clínica multitenant com:

• 143.795 linhas de código em React 18 + TypeScript + Vite
• 451 arquivos de componentes, stores, services, agents, tipos
• Dual Engine AI: PPEngineV2 (determinístico) + Gemini 2.5 Flash (enriquecimento)
• 32 coleções Firestore com RBAC granular e isolamento por clínica
• 7 módulos clínicos: EndoInject, LabPro, iMeddis, Pharma, Sample, BodyScan, Lifestyle
• LGPD compliant: consentimento granular por módulo, audit trails

---

Quando Usar Este Skill

Ative automaticamente quando encontrar qualquer menção:

• ✅ "NEXUS code", "nexus-app", "código NEXUS"
• ✅ Desenvolvendo features no NEXUS
• ✅ Corrigindo bugs, refatorando código
• ✅ Adicionando componentes React, stores Zustand
• ✅ Trabalhando com Firestore, regras de segurança (RBAC)
• ✅ Integrando Gemini, protocolos clínicos
• ✅ Protocol Wizard, EndoInject, LabPro, iMeddis, Pharma
• ✅ Investigando problemas de performance, god objects
• ✅ Questões sobre arquitetura, padrões, data flow

---

Como Usar Este Skill

Fluxo Padrão

1. Entenda o contexto: Leia architecture.md para mapear a estrutura
2. Localize o código: Use modules-guide.md para encontrar arquivos
3. Identifique padrões: Consulte stack-patterns.md para convenções
4. Verifique issues conhecidos: Veja known-issues.md antes de mexer
5. Siga standards: Aplique regras em coding-standards.md
6. Procure por ajuda: Agents em agents-cortex.md, Firestore em services-firebase.md

Exemplo: Adicionar novo protocolo clínico

1. Em modules-guide.md → seção Protocolos
2. Estude PPEngineAgentV2 em agents-cortex.md
3. Consulte stack-patterns.md → Zustand + Gemini
4. Mira services-firebase.md → collection protocols
5. Implemente seguindo coding-standards.md
6. Ler known-issues.md para armadilhas

---

Arquitetura em 60 Segundos

nexus-app/
├── src/
│   ├── ui/                    # React components (pages, layouts, modals)
│   ├── modules/               # 7 módulos clínicos isolados
│   ├── agents/                # AI agents (PPEngineV2, Gemini, CoreAgent)
│   ├── services/              # Business logic (PatientContextAggregator, Orchestrators)
│   ├── stores/                # Zustand (23 stores para estado global)
│   ├── cortex/                # CORTEX AI core (observe → interpret → govern)
│   ├── firebase/              # Firebase config & auth
│   ├── types/                 # TypeScript interfaces (Patient, Protocol, etc)
│   ├── data/                  # Pharma lookup, protocol matrix
│   ├── events/                # ClinicalEventBus pub/sub
│   └── utils/                 # Helpers (logger, hash, validation)
│
├── firestore.rules            # RBAC: ADMIN, DOCTOR, RECEPTIONIST, PENDING
├── storage.rules              # Fotos, PDFs seguro
└── vite.config.ts             # Lazy loading por rota

Data flow:

PatientDetails → PatientContextAggregator → PPEngineV2 → ProtocolBlueprint
                      ↓
                   Firestore (32 collections)
                      ↓
              ProtocolWizard (UI 2650 linhas)
                      ↓
              Gemini (enriquecimento)

---

Stack & Dependências

| Camada | Lib | Versão | Uso | |--------|-----|--------|-----| | UI | React | 18.3.1 | JSX, Hooks | | Rota | React Router | 6.22.1 | SPA navigation | | Estilo | TailwindCSS | 3.4.1 | Utility-first CSS | | Estado | Zustand | 4.5.1 | State management (23 stores) | | Build | Vite | 5.4.1 | Dev server, lazy loading | | Tipos | TypeScript | 5.9.3 | Type safety | | Backend | Firebase | 10.8.0 | Firestore, Auth, Hosting | | AI | @google/generative-ai | 0.24.0 | Gemini 2.5 Flash | | PDF | jspdf + jsbarcode | 2.5.2 + 3.12.3 | Protocolos, etiquetas | | Gráficos | Recharts | 2.12.1 | Dashboards | | Validação | Zod | 4.3.6 | Schema validation | | Animação | Framer Motion | 12.31.0 | UI transitions | | Ícones | Lucide React | 0.344.0 | SVG icons |

---

Índice de Referências

• architecture.md — Estrutura completa: folders, layers, data flow, inicialização
• stack-patterns.md — Padrões React 18, Zustand, Vite, Tailwind, Firebase, Gemini
• agents-cortex.md — AI engine: PPEngineV2, CoreAgent, Gemini, CORTEX pipeline
• services-firebase.md — Firestore: 32 collections, RBAC, queries, audit trails
• modules-guide.md — Cada módulo: estrutura, routes, stores, agents, componentes
• known-issues.md — Bugs atuais, god objects, test gaps, performance
• coding-standards.md — TypeScript strict, naming, padrões, novo features

---

Informações Rápidas

Roles & RBAC

• ADMIN: Acesso total, gerencia clínicas, usuários
• DOCTOR: Protocolos, módulos clínicos, pacientes (própria clínica)
• RECEPTIONIST: Agenda, check-in, pacientes (leitura)
• PENDING: Sem acesso (aguardando aprovação)

Multi-tenant

• Isolamento via clinicId em toda Firestore
• Firestore rules garantem clinic isolation
• AuthStore fornece clinicId atual

LGPD

• Consentimento granular por módulo (consent.service.ts)
• Audit trails completos (logs.service.ts)
• Dados auditáveis, hashados

ID Generation

• NEXUS IDs via system_counters collection
• Padrão: NEXUS-{clinic}-{sequential}
• Imutável após criação (firestore.rules)

---

Próximos Passos

1. Leia architecture.md para mapear o projeto
2. Consulte modules-guide.md para encontrar o código
3. Estude known-issues.md para evitar armadilhas
4. Aplique coding-standards.md ao escrever código
5. Use agents-cortex.md para AI/protocolo
6. Revise services-firebase.md para backend

---

O NEXUS é um MVP clínico funcional. Cada feature é orientada a oferecer valor médico. Antes de mexer, pergunte: "Como isso impacta o médico?"