nexus-core

name	nexus-core
description	Kernel skill — ALWAYS loaded before any other skill. Provides project topology, type gotchas, conventions, file zones, skill registry, and anti-patterns for the Ecossistema NEXUS. Every skill and pipeline depends on this context.

NEXUS Core — Kernel (Layer 0)

This is the kernel of the NEXUS skill ecosystem. Every other skill MUST load this first. It provides the shared context that prevents repeated mistakes and ensures consistency across all operations.

---

1. Project Topology

Scale

Category	Count	Location
Zustand stores	31	src/stores/ (27 root + 4 pharma/)
Firestore services	43	src/services/firestore/
Cloud Functions	24	functions/src/ (13 HTTP + 3 triggers + 4 cron + 4 email)
Common UI components	24	src/ui/components/common/
Routes	35	src/App.tsx (13 public + 22 protected)
Data files	27	src/data/ (pharmacopeia, lab, sample, therapeutics, protocol)
Agent TS files	10	src/agents/ (CORTEX pipeline: 9 agents + index)
Module pages	7	src/ui/pages/modules/
Tests	1680	src/tests/ (77 files)

Module Map

Module	Route	Store	Service	Data files
EndoInject	/endoinject	useSessionStore	endoinject.service	injectionSiteCatalog, aesthetics.constants
iMeddis	/imeddis	useMedicationStore	medications.service	pharmacopeia/* (8 files)
LabPro	/labpro	useLabStore	labResults.service	examCatalog, examEncyclopedia, examPanels, examCategories
Pharma	/pharma	4 pharma stores	pharmaStock, pharmaBatches, pharmaMovements, pharmaPurchaseOrders, pharmaSuppliers	—
BodyScan	/bodyscan	useBodyScanStore	bodyScan.service	—
Lifestyle	/lifestyle	useLifestyleStore	lifestyle.service	—
Sample	/sample	useSampleQueueStore, useSampleComplianceStore, useSampleInventoryStore	sampleQueue, sampleCompliance, sampleInventory, sampleLabBridge, sampleStorage, sampleAudit	samplePriorityConfig, samplePops, sampleAlertProtocols
Agenda	/agenda	useAgendaStore	appointments.service	—
Protocols	/protocols	useProtocolStore, useProtocolTemplateStore	protocols.service, protocolTemplates.service, protocolOutcomes.service	m1m7Templates, protocolIntelligenceMatrix, objectiveConvergenceRules
Patients	/patients	usePatientStore	patients.service	—

Cross-Module Bridges

• sampleLabBridge.service.ts — Sample dispatch → LabResult creation
• StatusSyncService.ts — Lab complete → protocol readiness; Protocol cancel → meds pause
• PatientContextAggregator.ts — Parallel fetch from 4 modules → PatientFullContext
• ProtocolDispatcher.ts — Protocol save → medications + sessions + lab requests

Guard Layers (route protection)

RoleGuard (ADMIN | DOCTOR) → ModuleGuard (module access check) → ModuleErrorBoundary (error isolation)

---

2. Type System Gotchas

These cause bugs if forgotten. ALWAYS check before touching patient/protocol code:

Gotcha	Detail
Patient type	Single source: src/types/PatientTypes.ts — NEVER redefine
Patient.allergies	Is Allergy[] — display with a.allergen, NOT a directly
Patient.consent	Is { given: boolean; date?: Date } or undefined — ALWAYS use ?.given
Patient.conditions	Optional array — ALWAYS (patient.conditions || [])
Patient.modulesLinked	Optional array — ALWAYS (patient.modulesLinked || [])
Modus Operandi	= Module selection ('endoinject' | 'imeddis' | 'labpro'), NOT therapeutic objective
NEXUS ID	Format: NXID-XXXXX (5 digits). Legacy: NX + 4 digits
Protocol.status	DRAFT → PENDING → APPROVED → ACTIVE → COMPLETED | CANCELLED — strict transitions
Prescription.medication vs .name	aiContent uses .medication, iMeddis uses .name — normalization needed
Prescription.dosage vs .dose	Same dual-field issue — ProtocolDispatcher normalizes both
EndoInjectSession.adverseReactions	Plural string[], NOT .adverseReaction
ExamEncyclopediaEntry.fullName	Use .fullName, NOT .name. The .id is number — use String(exam.id)
EXAM_PANELS	UPPERCASE export name
Button icon prop	Expects ReactNode (<Icon /> not Icon)
ProgressBar	Has NO label prop
jsPDF	ALWAYS lazy-load via import('jspdf') — NEVER top-level import
Patient service	Use services/firestore/patients.service — NOT modules/Patient/PatientService

---

3. Convention Rules

Naming

• Components: PascalCase (ProtocolCard.tsx)
• Hooks: camelCase with use prefix (useProtocolGeneration.ts)
• Services: camelCase with .service.ts suffix
• Stores: use{Name}Store.ts
• Types/Interfaces: PascalCase, I prefix for interfaces
• UI text: Portuguese (pt-BR)
• Code/variables: English

Imports

• Patient type: ALWAYS from src/types/PatientTypes.ts
• Firestore services: from src/services/firestore/
• Common components: from src/ui/components/common/
• Never import from node_modules paths directly

Patterns

• Functional components with hooks only (no classes)
• Zustand stores with selectors (not full store subscriptions)
• Error boundaries on every module root
• Zod for all form validation
• SHA-256 hash on all protocols and audit entries
• TypeScript strict mode, no any types

Git

• Commits: feat(module):, fix(module):, refactor(module):, docs:, security:
• Branch: feature/MODULE-description, fix/MODULE-description
• Pre-commit: tsc --noEmit + vite build must pass

---

4. File Zones (Risk Classification)

RED ZONE — DO NOT modify without protocol-integrity + regression-shield

src/services/ProtocolOrchestrator.ts
src/services/ProtocolDispatcher.ts
src/services/PatientContextAggregator.ts
src/services/StatusSyncService.ts
src/hooks/useProtocolGeneration.ts
src/types/PatientTypes.ts
src/types/ProtocolTypes.ts
src/services/firestore/protocols.service.ts
src/services/firestore/patients.service.ts
src/services/firestore/clinicPlan.service.ts
functions/src/http/geminiProxy.ts
functions/src/http/stripeWebhook.ts
functions/src/http/stripeCheckout.ts

YELLOW ZONE — Test before AND after changes

src/services/firestore/*.service.ts (all other services)
src/stores/*.ts (all stores)
src/hooks/*.ts (all other hooks)
src/agents/*.ts (all agents)
src/services/firestore/sampleLabBridge.service.ts
firestore.rules

GREEN ZONE — Safe to modify

src/utils/*.ts
src/ui/components/common/*.tsx
src/ui/pages/modules/**/*.tsx (UI-only changes)
src/data/*.ts (static data)
src/services/protocol/protocolEnricher.ts
src/services/protocol/doseValidator.ts
src/services/protocol/genderFilter.ts
Pure functions without side-effects

---

5. Skill Registry

Layer 1 — Action Skills (do work)

Skill	When to use	Loads after core
nexus-design-system	UI/UX creation, design fixes, visual work	Yes
nexus-slop-killer	Dead code removal, cleanup, imports audit	Yes
nexus-deploy	Pre-flight checks, build, deploy, health check	Yes

Layer 2 — Quality Gates (validate)

Skill	When activates	Blocks if
protocol-integrity	Protocol/AI code changed	Safety gate removed, hash broken
regression-shield	Any code changed	Existing test fails
firestore-rules-audit	Rules/collections changed	Data exposed, LGPD violated
safe-refactor	Service/store/hook refactored	Red zone touched, signature changed

Layer 3 — Orchestration (pipelines via commands)

Command	Pipeline
/deploy-ready	core → slop-killer(audit) → regression-shield → protocol-integrity → deploy
/refactor	core → safe-refactor → [change] → regression-shield
/design-audit	core → design-system → [scan all pages] → report
/design-fix	core → design-system → [apply fixes] → tsc + build

---

6. Anti-Patterns (NEVER do these)

Anti-Pattern	Why it breaks things
Import Patient from anywhere except PatientTypes.ts	Creates type drift, breaks aggregator
Top-level import jsPDF	Adds 560KB to initial bundle
Use any type	Bypasses TypeScript safety net
Modify Firestore collection names	Hardcoded in 50+ locations
Change NEXUS ID format	Universal key across all collections
Remove safety gates (consent, allergy, interaction checks)	Clinical safety violation
Skip SHA-256 on protocols	Breaks audit trail chain
Put secrets in code (use .env)	Security breach
Use console.log with patient data	PII leakage (LGPD violation)
Modify protocol status enum order	Breaks strict transition logic
Create new store without paired service	Breaks store-service bridge pattern
Create inline UI when common component exists	Visual inconsistency
Use shadow-[...] arbitrary values	Design system violation
Forget dark: classes	Broken dark mode

---

7. Current State

• Sprint: 16
• Branch pattern: sprint-{N}/{feature-name}
• Firebase project: nexus-72034052-d80bc (Blaze plan)
• Domain: nexushealthtech.com.br
• Stripe: 4 plans LIVE (Starter R$0, Essential R$297, Pro R$497, Enterprise R$797)
• Status: Ready for launch
• Gemini model: gemini-2.5-flash (temperature 0.1)

Deploy Commands

# Everything
cd nexus-app && npx firebase-tools deploy --only functions,hosting --project nexus-72034052-d80bc

# Hosting only
npx firebase-tools deploy --only hosting --project nexus-72034052-d80bc

# Functions only
npx firebase-tools deploy --only functions --project nexus-72034052-d80bc

# Pre-deploy checks
npx tsc --noEmit && npx vite build