Nexura OS

A connected healthcare operating system for hospitals, clinics, pharmacies, and patients.

Built on Next.js 16 with a real, auditable backend. 190 API routes, 165 Postgres models, 344 unit tests, and a unified platform layer connecting 15 distinct healthcare surfaces.

Evaluating the codebase? Start with PRODUCTION_STATUS.md — the current, single source of truth on production readiness.

Healthcare is severely fragmented. Hospitals, clinics, independent doctors, patients, pharmacies, and diagnostic laboratories often operate entirely disconnected systems. Administrative systems do not talk to patient-facing applications; AI tools operate in isolated silos without clinical context; and patient records are scattered across different platforms.

Nexura OS is designed to address this fragmentation by connecting these healthcare workflows through a common, auditable platform layer. It is not just an AI healthcare app—it is an entire ecosystem where intelligence is a native capability built into a broader healthcare operating structure.

Nexura OS is a multi-product healthcare ecosystem. It provides distinct product surfaces for different users (clinicians, pharmacists, patients, operations teams) that all share the same centralized platform infrastructure.

The distinction is clear:

• 🚀 Product Surfaces: Hospital OS, Clinic OS, Pharmacy, Patient Portal, and consumer applications.
• 🛡️ Shared Platform Infrastructure: Identity, authentication, authorization (RBAC/ABAC), patient scope, audit trails, AI governance, background jobs, money integrity, and API observability.

Nexura OS is composed of several integrated products, all running from this repository and interacting with the same underlying platform core.

Hospital OS

Clinic & Pharmacy

Patient & Intelligence Surfaces

Consumer & Public Surfaces:

Nexura Predictive

Nexura Care Circle

Nexura DIY

The codebase scale and complexity as of the latest commit:

• 🛣️ 190 API Routes: Covering the core platform and all product modules.
• 🗄️ 165 Database Models: Covering complex relationships, integer money columns, and audit trails.
• 🧪 344 Unit Tests: Comprehensive test suite over 22 files using real PostgreSQL and Redis.
• 🔄 8 Prisma Migrations: Ordered, robust history with strict constraints.
• 🧠 30+ AI Call Sites: All funneled through a central governance layer.

Every product mentioned above is a first-class surface in this repository.

Running live right now: the published platform preview serves this exact codebase at n13xb70qvnr0-d.space-z.ai — same routes, same demo logins (password Demo@12345, staff PIN 2468).

✨ View the entire homepage design (Click to expand)

The shared platform core is the engine of Nexura OS. It ensures consistency, security, and scalability across all product surfaces.

• 🔒 Authentication & Identity: JWT session auth with HttpOnly cookies, distinct verifiers for staff vs. patients, session revocation, and device tracking.
• 👮 RBAC & ABAC: Granular role-based access control combined with attribute-based patient/department scoping.
• 📜 Auditability: Tamper-evident, hash-chained audit trails (NxEventLog) using ON DELETE RESTRICT.
• ⚖️ AI Governance: A central gateway metering usage, enforcing consent, tracking identity, and validating structure.
• 💰 Money Integrity: Deterministic integer-paise logic; no Float values in transactional data.
• ⏱️ Durable Jobs: PostgreSQL-backed job queue with FOR UPDATE SKIP LOCKED claiming and stale-claim reaping.
• 📡 Observability: Rate limiting, request IDs (x-request-id), structured JSON logging, and edge burst guards.

       [ Users / Healthcare Organizations ]
                       │
                       ▼
       [ Nexura Product Surfaces ]
    (Hospital, Clinic, Pharmacy, Portal)
                       │
                       ▼
   [ Nexura Platform Core (Edge & API Layer) ]
     [ x-request-id / rate limits / auth gate ]
                       │
                       ▼
[ Identity / Authorization / Audit / AI Governance ]
[ Events / Jobs / Money Integrity / Interoperability ]
                       │
                       ▼
 [ Data + Infrastructure + External Integrations ]
[ PostgreSQL 17 / Redis 7 / OpenRouter / Next.js ]

Product Architecture: The capabilities exposed to the user. Includes the Hospital OS command center, Clinic queue, Pharmacy POS, Patient Portal, Care Circle, Predictive Intelligence, and Connect.

Technical Architecture: The underlying infrastructure.

• Frontend: Next.js 16 App Router (Turbopack), Tailwind 4, shadcn/ui.
• Backend: Next.js API Routes, heavily modularized service files, strict idempotency keys.
• Data Access: Prisma Client singleton.
• System of Record: PostgreSQL 17.
• Ephemeral State: Redis 7 for rate limits, event bus relay, and sync leases.
• AI Gateway: OpenRouter + direct z-ai SDK fallback.

Nexura is an AI-native healthcare platform. Intelligence is structured as a controlled capability, not a random frontend call.

[ User / Clinical Workflow ]
          ↓
  [ AI Capability ]
          ↓
[ AI Governance (Consent enforced: LATEST-EVENT-WINS) ]
          ↓
[ Authorization (Actor Attribution via AsyncLocalStorage) ]
          ↓
[ Model Gateway (OpenRouter / Fallbacks) ]
          ↓
[ Validation / Structured Output (JSON contracts) ]
          ↓
[ Audit / Observability / Metering (Token & Micro-USD ledger) ]
          ↓
    [ Application ]

• 📉 Metering: Cost and token accounting tracked by tokenSource and costSource.
• 🧑‍⚕️ Identity: Every request records the verified actor. Null is only used for true system calls.
• 🚫 No Prompt Storage: Prompt content is not stored in the database, only operational metadata.

Nexura OS includes numerous AI-assisted features integrated directly into clinical and consumer workflows:

• Implemented: Voice SOAP notes, prescription OCR, natural-language inventory query, symptom triage (demo), lab report interpretation.
• Implemented (Consumer Tools): 15 specific tools including disease risk, BP analyzer, sleep quality, and diet planner.
• Integration-dependent: Some clinical fallback models and multimodal deep scans rely on external provider readiness.

AI operations follow a strict, auditable governance model:

• ✅ Consent Enforcement: AI usage requires DPDP consent. Withdrawing consent in the Patient Portal immediately revokes access, resulting in a real 403 ai_consent_required block.
• 🏷️ Capability-Level Controls: Each AI call site is labeled.
• 🔁 HITL Loop: Human-in-the-loop loops available for overrides and feedback (NxAiFeedback).
• 🚦 Thresholds: Per-hospital thresholds for allowed, human-fallback, or blocked requests.

Intelligence in Nexura OS is framed carefully:

• Decision Support & Information: Lab report decoding, AI-assisted charting, and risk trajectory models.
• ⚠️ No Automated Diagnosis: Nexura OS consumer tools operate strictly with "educational, not a diagnosis" framing. Triage features are explicitly labeled as keyword-triage, not clinical triage engines.

Nexura OS is architected for integration, rather than being a closed ecosystem.

• Implemented boundaries: Support for HL7/FHIR interfaces exists in the architecture (src/lib/nx/fhir.ts, hl7.ts).
• Integration-dependent: ABDM/ABHA identity lookup is synthetically mocked in demo mode and clearly returns 501 Not Implemented outside demo mode until actual registries are wired.

Security is treated as infrastructure:

• 🔐 Authentication: JWT session auth with HttpOnly cookies; legacy /api/auth login paths were deliberately removed.
• 🚧 Authorization boundaries: Central requirePermission enforcer. patientInScope checks cross-family boundaries.
• 🖥️ Environment Validation: Boot sequence refuses to start production if secrets (PostgreSQL, JWT, Redis) are missing.
• 🛑 IDOR prevention: Tenant boundaries and hospital contexts enforced failing-closed across the system.

• 🛡️ Architecture designed with consideration for: DPDP consent tracking, append-only consent ledgers, granular auditability, and data minimization.
• ✅ Controls currently implemented: Technical controls such as immutable signed records, TLS support, session revocation, and explicit self-service consent workflows.
• 🛑 Certification / Approval not yet claimed: The codebase provides the technical foundation but does NOT by itself make an organization HIPAA, DPDP, or ABDM compliant.

• Fail Closed: The system defaults to denying access if a condition (such as hospital context) cannot be verified.
• Explicit Authorization: Enforced by the guard() wrapper.
• Idempotent Mutations: Uses NxIdempotency (claim-then-execute) to prevent double-charging or duplicate writes.
• Deterministic Money Handling: Transactions settle in PostgreSQL with integer paise and cents, never floating-point decimals.
• No Silent Fake Integrations: Missing credentials or offline services do not simulate success in production.

This repository represents a sophisticated, active development state:

• ✅ Implemented: Next.js App Router API, PostgreSQL schemas, RBAC, API rate limiting, AI governance funnel, deterministic money handling, test suite, and hospital/clinic/pharmacy frontend capabilities.
• 🚢 Production-ready / validated: The technical boundaries, authentication, authorization, database concurrency, and CI testing pipeline.
• 🔌 Integration-dependent: SMS/OTP providers, actual ABDM/ABHA registries, IRP/e-invoicing, and real payment gateways.
• 🚧 In active development: Deep API endpoints for edge-case billing, read-replica routing (plumbed, but routes to primary).

See PRODUCTION_STATUS.md for full implementation details.

Nexura OS operates with strict honest boundaries. The system will fail loudly rather than faking integration in a production environment:

• Unavailable external systems are represented honestly.
• Demo adapters (DEMO_MODE=true) are clearly distinguishable from production integrations and explicitly gated.
• Seed scripts refuse to run in NODE_ENV=production without explicit overrides.

• Application: Next.js 16 (App Router), React, Tailwind CSS 4, shadcn/ui.
• Backend / API: Node.js, TypeScript.
• Database: PostgreSQL 17 (System of Record), Prisma (Data Access).
• Real-time / Infrastructure: Redis 7 (Distributed limiter, SSE bus, Jobs).
• AI: OpenRouter, z-ai SDK.
• Testing: Vitest, Playwright.
• Deployment: Vercel, Docker Compose.

• Modular Monolith: One Next.js 16 process allows any request to be debugged end-to-end without chasing microservices.
• PostgreSQL as System of Record: Ensures ACID compliance for transactional data (e.g., pharmacy inventory decrements).
• Centralized AI Gateway: Prevents uncontrolled prompt spraying; enables global metering, fallback routing, and DPDP consent enforcement.
• Integer Money: Eliminates floating-point rounding errors in GST calculations and financial ledgers.

• Organization: 190 routes under src/app/api/** (e.g., /api/nx, /api/clinic, /api/pharmacy).
• Wrapper: Legacy handlers have been wrapped in withRoute to enforce request IDs, latency logs, safe JSON 500s, and rate limits.
• Rate Limiting: Distributed rate-limit budget managed via Redis.
• Documentation: OpenAPI 3.1 available at /api/nx/openapi.

For full details, see the API documentation.

• System of record: PostgreSQL.
• Prisma schema: prisma/schema.prisma contains 165 models.
• Migrations: 8 applied migrations (including strict AI ledger additions and integer money migrations).
• Audit: NxEventLog hash-chains audited events.

The codebase is tested and continuously verifiable.

• Unit Tests: 344 unit tests across 22 files using real PostgreSQL and Redis datastores.
• Integration / API Tests: A 58-check API smoke suite validates live API behaviors.
• E2E Tests: Playwright role journeys validate frontend interactions.

• Request IDs: Propagated via x-request-id headers for end-to-end tracing.
• Logging: Structured JSON errors prevent leaking sensitive internal stack traces to the client.
• Resilience: The durable job queue uses exponential backoff and a stale-claim reaper. The AI gateway incorporates a 45-second abort mechanism and model fallbacks.

Nexura-OS/
├── src/
│   ├── app/
│   │   ├── hospital/ clinic/ pharmacy/ portal/ # Product surfaces
│   │   ├── connect/ know-your-health/ global/
│   │   └── api/                        # 190 API routes
│   ├── components/                     # Shared UI & Product-specific trees
│   ├── lib/
│   │   ├── nx/                         # PLATFORM CORE
│   │   │   ├── api.ts                  # withRoute wrapper
│   │   │   ├── session.ts              # auth verification / requirePermission
│   │   │   ├── ai-guard.ts             # AI governance
│   │   │   └── jobs/                   # Durable queue runner
│   │   ├── money.ts                    # Integer paise/cents boundary
│   │   ├── db.ts                       # Prisma singleton
│   │   └── openrouter.ts               # Canonical AI client
│   ├── proxy.ts                        # Edge middleware
│   └── instrumentation.ts              # Boot validation + background workers
├── prisma/
│   ├── schema.prisma                   # 165 models
│   └── migrations/                     # Real, ordered migration history
├── tests/
│   ├── unit/                           # 344 unit tests
│   ├── api-smoke.sh                    # API smoke suite
│   └── e2e/                            # Playwright testing
└── docs/                               # Extensive architecture & deployment docs

cp .env.example .env        # fill in DATABASE_URL / JWT_SECRET / REDIS_URL
npm install                 # install dependencies
npx prisma migrate deploy   # apply schema (PostgreSQL required)
npm run seed:suite          # complete demo dataset
npm run dev                 # Start dev server on http://localhost:3000

Note: Seed scripts refuse to run under NODE_ENV=production without explicit overrides.

The .env.example file contains all required configurations.

• Required: DATABASE_URL (PostgreSQL), REDIS_URL (Redis 7), JWT_SECRET (Secure secret ≥ 16 chars).
• Optional: OPENROUTER_API_KEY (AI models), DEMO_MODE (Controls demo adapters, secure default false).

Three supported paths:

• Vercel: Deploy with one click. Automatic setup for Edge middleware and Serverless functions.
• Docker: docker compose up --build -d provisions Next.js, Postgres 17, and Redis 7.
• Self-hosted: Build via npm run build:standalone.

See DEPLOYMENT.md for rollback, backup, and release-gate steps.

• 📖 API - Full API reference.
• 🏛️ Architecture - System design and logic flow.
• 🚦 Production Status - Honest review of current implementation state.
• 🚀 Deployment - Environment, Vercel, and Docker guides.
• 🔒 Security - Access controls and remaining compliance needs.
• 🗺️ Roadmap - Future directions.

Nexura OS is expanding across three fronts:

• Current Capabilities: Fortifying the existing core (completed integer-money migrations and AI ledger tracking).
• Near-term Work: Bridging the integration-dependent gaps (payment gateways, real OTP providers).
• Future: Advanced healthcare interoperability endpoints (FHIR compliance).

For the full detailed plan, view ROADMAP.md.

PRs are welcome—especially around our documented integration limitations.

1. Fork and branch from main.
2. Ensure you keep the verification gates green: npm run typecheck && npm run lint && npm run test.
3. Format with Prettier before committing.
4. Follow the PR template to maintain our "fail loudly" honesty checklist.

Active development / pre-production

The architectural foundation (database schema, authentication, API routes, RBAC, CI tests) is robust and heavily tested. However, certain capabilities (like real medical interoperability layers and third-party SMS/Payment providers) remain integration-dependent. See PRODUCTION_STATUS.md for the exact boundary of what is currently implemented.

Nexura OS is a healthcare technology platform. Any AI features, risk trajectories, or symptom checkers included in this repository are intended for decision support and educational purposes only. They do not constitute an automated medical diagnosis or treatment plan. Implementing organizations are responsible for clinical validation, regulatory compliance, and obtaining appropriate patient consents before deploying to a production environment.