DEV Community

Cover image for NeuroCloak: Cognitive Digital Twin (CDT) for AI Systems
Thanvik931
Thanvik931

Posted on

NeuroCloak: Cognitive Digital Twin (CDT) for AI Systems

#python #ai #webdev #mongodb

We Built a Production AI Governance Platform as Students — Using Only MongoDB's Free Tier

Authors: Sama Thanvik Reddy,P. Akash, K. Abhinav,M. Srihith

The Question That Started Everything

Picture this: an AI system just denied someone's loan application. The bank's compliance officer walks in and asks — "Why, exactly, did that happen?"

Not "what score did the model return?" Not "which threshold did it miss?" Why — step by step, traceable, auditable, defensible in front of a regulator.

In most AI deployments today, that question has no good answer. The decision happened inside a model that runs too fast to observe and persists too little to audit. The compliance officer goes away empty-handed.

This is the problem we set out to solve. Not as a toy demo. As a production platform, built by four students with no budget and no cloud credits.

The urgency is real. Cumulative GDPR penalties have surpassed €5.8 billion, with AI decisions increasingly in scope. Gartner projects that 75% of global economies will enforce formal AI oversight by the end of 2026, yet only 25% of firms have governance programs in place to comply. IBM research found that 97% of organizations experiencing AI breaches lacked model-level audit controls.

NeuroCloak is our answer. It is live, deployed on Render and Vercel, and built entirely on MongoDB Atlas M0 free tier with native Atlas Charts integration.

What NeuroCloak Actually Does

NeuroCloak is a Cognitive AI Digital Twin Monitor. It reconstructs AI reasoning into structured inference chains across four cognitive layers — Perception, Reasoning, Symbolic, and Metacognitive — and persists every step as a timestamped, queryable document in MongoDB Atlas.

When an auditor asks why an AI denied a loan application six months ago, every inference step that contributed to that decision is retrievable in milliseconds. The platform detects bias and ethical drift in real time, broadcasts anomaly alerts via Socket.io, and surfaces compliance analytics through embedded MongoDB Atlas Charts dashboards — all on the M0 free tier.

"Every reasoning step persisted as a timestamped MongoDB document — retrievable in milliseconds, months later."

The Tech Stack

Layer Technology
UI Framework React 18 + TypeScript + Tailwind CSS
State Management Zustand + TanStack Query
Real-Time Client Socket.io-client
Frontend Auth Firebase Auth (Google) + Internal JWT
Charts & Visuals Recharts + react-calendar-heatmap
Report Export jsPDF + jspdf-autotable
Frontend Deploy Vercel
API Server Flask + Express + TypeScript
Core Database MongoDB Atlas (M0 Free Tier)
ODM Mongoose 7
Analytics Engine MongoDB Aggregation Pipelines (native)
Dashboards MongoDB Atlas Charts (embedded iFrame)
Real-Time Server Socket.io
Cache Redis (cache-aside, 5-min TTL)
Backend Deploy Render

MongoDB Atlas is not "part of the stack" in NeuroCloak — it is the stack. No separate analytics database. No ETL pipeline. No visualization backend. MongoDB replaced four categories of infrastructure that would have taken months to wire together.

The Frontend: Making Governance Visible

The most technically correct audit system is worthless if compliance officers cannot use it. The frontend was not an afterthought — it was a product decision.

Five frontend decisions defined the product.

1. Streaming reasoning traces at 150ms per step

The reasoning trace streams at 150ms per step rather than loading all at once. Each step appears sequentially — simulating the AI thinking in real time. TanStack Query fetches the full decision from Atlas. React state controls which steps are visible. A useEffect with setTimeout releases each step in sequence.

The result is that a compliance officer watching a decision replay feels like they are watching the AI think, not reading a static log.

2. Multi-System Battle Mode

Battle Mode runs the same scenario through all three AI systems simultaneously using Promise.all(). Three columns stream their reasoning steps independently. A winner banner compares compliance rates, transparency indices, and decision speed across systems.

This required three concurrent Atlas writes, three Socket.io broadcasts, and three independent streaming state machines running in parallel.

3. Client-Side PDF Export

Every decision can be exported as a five-page PDF using jsPDF, generated entirely client-side. The report includes:

  • A cover page with decision metadata
  • A CDT performance metrics table
  • The full reasoning trace
  • Governance compliance checks
  • A bias detection report

No server round trip. No file storage. No Atlas write.

4. 365-Day Compliance Heatmap

The heatmap runs on MongoDB aggregation pipeline output grouped by date and averaged by compliance rate. The frontend maps compliance ranges to a color scale — dark green for excellent, red for critical — giving compliance teams an instant visual signal without requiring them to interpret numbers. A red patch in the heatmap means something happened that week worth investigating.

5. Real-Time Anomaly Alerts Under 200ms

When the anomaly detector writes an AnomalyAlert document to Atlas, the backend immediately emits a Socket.io event. The frontend receives it and prepends a new alert card with a red flash animation. The Browser Notification API fires if the tab is not focused. The notification bell increments its badge count. All of this happens in under 200ms from Atlas write to visible UI update.

The 7-Collection Data Model

Collection Purpose Key Index
decisions Primary audit record {aiSystemId:1, createdAt:-1}
reasoningsteps One doc per CDT layer step {decisionId:1}
biasflags Detected bias patterns {decisionId:1, severity:1}
anomalyalerts 3-check post-write detection {aiSystemId:1}
governancerules Per-system compliance rules {aiSystemId:1, isActive:1}
ethicschecks Rule evaluation per governance {decisionId:1}
aisystems Registered AI model registry {_id:1}

MongoDB Features: What We Used and Why It Mattered

1. Powerful Aggregation Pipelines

The entire executive analytics layer runs on MongoDB's native Aggregation Pipeline framework. No data warehouse. No ETL jobs. No sync processes. Just Atlas querying compound-indexed collections and returning results that feed directly into the dashboard.

KPI Summary Pipeline — uses $group and $cond to calculate ethics compliance and transparency indices across the entire dataset in a single request, regardless of how many decisions the audit log contains.

const [summary] = await Decision.aggregate([
  {
    $group: {
      _id: null,
      totalDecisions: { $sum: 1 },
      avgCompliance: { $avg: '$ethicalComplianceRate' },
      avgTransparency: { $avg: '$transparencyIndex' },
      flaggedCount: {
        $sum: {
          $cond: [{ $in: ['$status', ['FLAGGED', 'BLOCKED']] }, 1, 0]
        }
      }
    }
  }
]);
Enter fullscreen mode Exit fullscreen mode

Time-Series Trends Pipeline — uses $dateToString to bucket high-resolution audit data into daily compliance trends, feeding the 30-day LineChart on the analytics dashboard with no additional processing.

const metrics = await Decision.aggregate([
  { $match: { createdAt: { $gte: thirtyDaysAgo } } },
  {
    $group: {
      _id: { $dateToString: { format: '%Y-%m-%d', date: '$createdAt' } },
      avgCompliance: { $avg: '$ethicalComplianceRate' },
      count: { $sum: 1 },
    }
  },
  { $sort: { '_id': 1 } }
]);
Enter fullscreen mode Exit fullscreen mode

Categorical Analysis Pipeline — uses $group and $sort to identify which bias categories appear most frequently across all systems, powering the bias distribution donut chart.

Calendar Heatmap Pipeline — groups daily compliance averages across 365 days with $dateToString and $round, producing the exact data shape the frontend heatmap component expects with no transformation required.

"Four charts, four aggregation pipelines, zero data warehouse, zero ETL, zero sync jobs."

2. Performance-Optimized Compound Indexes

As the audit trail grows, query performance becomes the difference between a usable compliance tool and an unusable one. Every collection in NeuroCloak carries indexes designed for its specific access pattern.

The compound index { aiSystemId: 1, createdAt: -1 } on the decisions collection optimizes the Recent Decisions feed — the most frequently executed query in the entire application. Every dashboard load hits this index rather than scanning the collection.

Without compound indexes, the heatmap and time-series pipelines would run full collection scans on every dashboard load. With them, the same pipelines complete in milliseconds regardless of audit log depth.

3. Native Integration with MongoDB Atlas Charts

We did not build a chart library integration for the primary compliance dashboards. We did not write a visualization service. We pointed Atlas Charts at our live collections, configured three chart types, and embedded the iFrame URLs directly into the React frontend.

The moment a new Decision document is written to Atlas, every embedded dashboard reflects it — with no polling, no sync job, and no intermediate layer.

export const getAtlasChartEmbedUrl = (
  projectId: string,
  id: string,
  type: 'chart' | 'dashboard'
): string => {
  const base = `https://charts.mongodb.com/${projectId}/embed`;
  const endpoint = type === 'chart' ? 'charts' : 'dashboards';
  return `${base}/${endpoint}?id=${id}&theme=dark&autoRefresh=true`;
};
Enter fullscreen mode Exit fullscreen mode

War story: Atlas Charts assigns separate identifiers for dashboards and individual charts. They are not interchangeable. Using a Dashboard ID against /embed/charts returns a silent empty iFrame — no error, no console output, nothing. We lost hours on this. The fix: a type parameter that constructs the correct URL at runtime, making the mismatch architecturally impossible. It is in the Atlas Charts documentation, but easy to miss.

4. Flexible Document Modeling with Mongoose

NeuroCloak audits AI systems across fundamentally different domains, each with completely different input payloads.

  • Healthcare: { patientAge: 47, diagnosisCode: "J18.9", riskScore: 0.83 }
  • Defence: { threatLevel: "HIGH", geofence: "zone-7", escalationPriority: 2 }
  • Fintech: { creditScore: 710, loanAmount: 50000, debtRatio: 0.34 }

In SQL, each new domain requires a new table, a new migration, and a new join in every analytics query. In MongoDB, the inputData field is declared as Schema.Types.Mixed — onboarding a new AI domain requires changing exactly nothing in the schema or the pipelines.

Beyond flexible payloads, the document model made the Cognitive Reasoning Trace possible. Instead of normalizing reasoning steps into a separate relational table with foreign keys, MongoDB allows the full four-layer trace to be stored as structured nested documents within the decision record. This is what makes the trace animation on the frontend technically feasible — the complete reasoning chain arrives in a single Atlas read, with no joins, no N+1 queries, and no reconstruction logic on the application layer.

TypeScript: Not a Style Choice — A Correctness Requirement

A compliance score of "0.95" (string) is not the same as 0.95 (number). In plain JavaScript, that silent coercion corrupts analytics without raising a single error — until bad data is already in the production Atlas cluster. TypeScript catches it at compile time.

export interface IDecision extends Document {
  aiSystemId: mongoose.Types.ObjectId;
  userId?: string;
  inputData: Record<string, unknown>;
  outputDecision: string;
  confidenceScore: number;
  cognitiveConsistency: number;
  transparencyIndex: number;
  ethicalComplianceRate: number;
  adaptationSpeed: number;
  selfRepairEfficiency: number | null;
  status: 'PENDING' | 'APPROVED' | 'FLAGGED' | 'BLOCKED';
  createdAt: Date;
}
Enter fullscreen mode Exit fullscreen mode

That status union literal means assigning status: 'PENDING_REVIEW' is physically impossible — the IDE rejects it and tsc blocks the build. For a platform where every status value can trigger a regulatory escalation, that is not a convenience. It is the product.

The Simulation Engine: Four-Collection Atlas Write

Every simulation produces four sequential Atlas writes — a primary Decision document, the full reasoning trace as ReasoningStep documents, detected BiasFlag documents, and EthicsCheck evaluation results against every active governance rule.

const decision = await Decision.create({
  aiSystemId, userId: req.user?.userId, inputData,
  outputDecision: simResult.outputDecision,
  confidenceScore: simResult.confidenceScore,
  ethicalComplianceRate: simResult.ethicalComplianceRate,
  transparencyIndex: simResult.transparencyIndex,
  status: simResult.status,
});

await ReasoningStep.insertMany(
  simResult.reasoningTrace.map(step => ({ decisionId: decision._id, ...step }))
);

await BiasFlag.insertMany(
  simResult.biasFlags.map(flag => ({ decisionId: decision._id, ...flag }))
);

await EthicsCheck.insertMany(
  ethicsChecks.map(e => ({ decisionId: decision._id, ...e }))
);
Enter fullscreen mode Exit fullscreen mode

Asynchronous Anomaly Detection: 3 Independent Checks

After every Atlas write, a non-blocking background service runs three independent behavioral checks with zero added latency to the audit endpoint.

Check 1 — Compliance Drop: Computes a rolling baseline from the last 20 decisions. If the new decision's compliance rate falls more than 15 points below baseline, it fires a compliance_drop critical alert.

Check 2 — Bias Spike: If the last 5 decisions had zero bias flags but the new decision is FLAGGED, it fires a bias_spike high-severity alert.

Check 3 — Unexpected Block: If the last 10 decisions were all APPROVED but the new decision is BLOCKED, it fires an unexpected_block critical alert.

Note for production: Migrating this to a MongoDB Atlas Trigger would provide serverless, guaranteed execution on every document write — regardless of API server state. It is on the roadmap.

Redis Cache-Aside: Critical Path Protected 

if (redis?.status === 'ready') {
  const cached = await redis.get('analytics:summary');
  if (cached) return res.json(JSON.parse(cached));
}

const [summary] = await Decision.aggregate([...summaryPipeline]);
const result: SummaryResult = shapeResult(summary);

await redis?.setex('analytics:summary', 300, JSON.stringify(result));
Enter fullscreen mode Exit fullscreen mode

On every simulation write, both analytics:summary and analytics:metrics cache keys are invalidated immediately via Promise.all([redis.del(...), redis.del(...)]).

The War Stories: What Actually Went Wrong

1. Multi-Document Transactions Silently Fail on M0

The original simulation write wrapped four collections in a Mongoose session transaction. It worked on M10 in development. It failed silently on M0 in production — because M0 runs single-node and does not support multi-document transactions.

Fix: Sequentially idempotent writes. For an append-only audit log, partial writes are detectable and safely replayable.

Lesson: Always verify Atlas tier capabilities before designing transactional patterns.

2. Firebase UIDs Are Strings. ObjectIds Are Not Strings.

The initial schema declared userId as Schema.Types.ObjectId. Firebase assigns string UIDs. Mongoose threw a CastError the moment a Firebase user triggered a simulation.

TypeScript surfaced the mismatch immediately in the IDE.

Fix: One type change to String. Without TypeScript, this would have been silent production data corruption.

3. Dashboard IDs and Chart IDs Are Not Interchangeable

Using a Dashboard Embedding ID against /embed/charts returns a silent empty iFrame. No error. No console output. Just nothing.

Fix: A type parameter on the embedding endpoint that routes to the correct URL format at the call site, making the mismatch architecturally impossible.

What MongoDB Replaced — An Honest Accounting

What We Needed Would Have Built Atlas Gave Us
Flexible payloads 4 domain tables + migrations per domain Schema.Types.Mixed, 0 migrations
Compliance KPIs Analytics DB + ETL + chart library Native aggregation pipelines
Live dashboards WebSocket polling + sync service Atlas Charts iFrame — built in
Post-write hooks (roadmap) Worker process + message queue Atlas Triggers (roadmap)
Audit archiving (roadmap) S3 + separate query layer Atlas Online Archive

The Research Behind the Platform

NeuroCloak is not just a project — it is a working implementation of original academic research. The four-layer CDT architecture is documented in our co-authored paper:

"NeuroCloak: Cognitive Digital Twin (CDT) for AI Systems"

Sama Thanvik Reddy, P. Akash, K. Abhinav, M. Srihith

KL University (KLH), Hyderabad, 2025

The paper formalizes the cognitive state-space representation, defines the five evaluation metrics, and situates the CDT framework within the existing literature on neuro-symbolic AI, explainable AI, and digital twin architectures.

MongoDB was chosen after the research architecture was defined, not before. A reasoning step is a document. A bias flag is a document. An ethics check is a document. The schema emerged from the research. The document model mapped directly to the CDT's cognitive state representation — something a relational schema would have required extensive normalization to approximate.

What Is Next

  • Atlas Vector Search — semantic audit queries such as "retrieve all past decisions involving high patient risk" without keyword matching across the full audit log.
  • Atlas Data Federation — query five years of compliance history across the live cluster and S3 archives through a single interface.
  • Atlas App Services RBAC — document-level role enforcement at the database layer rather than application middleware.
  • Atlas Online Archive — automatic cold-storage tiering as the audit log scales to years of data.
  • Atlas Search — natural-language queries across audit records: "find all FLAGGED decisions mentioning demographic correlation."

Try It Yourself 

git clone https://github.com/Thanvik931/NeuroCloak
cp .env.example .env
npm install && npm run dev
Enter fullscreen mode Exit fullscreen mode

Login with: admin@neurocloak.ai / Admin123!

Three open challenges for contributors:

  1. Add a fifth aggregation pipeline — ethics check pass/fail ratio by governance rule category. Open a pull request.
  2. Migrate anomaly detection to an Atlas Trigger — measure latency against the current background process implementation and share your numbers.
  3. Implement Atlas Vector Search on inputData — enable semantic similarity queries across audit records from different domains.

What We Actually Learned

When you choose the right persistence layer, whole categories of infrastructure disappear. We did not choose MongoDB because we were advocates — we chose it because we had no budget, no cloud credits, and needed a database that would handle analytics, dashboards, flexible schemas, and real-time updates without requiring us to also build an analytics database, a visualization backend, a schema migration service, and an ETL pipeline. Atlas on M0 handled all of it.

For systems where data correctness is the product — audit logs, compliance records, governance artefacts — MongoDB's flexible persistence model paired with TypeScript's strict compile-time contracts produces a codebase that is simultaneously adaptable and trustworthy. Those two properties are genuinely hard to hold together. This project is evidence that the pairing works.

Special Thanks

We would like to extend our heartfelt gratitude to our mentor, @chanda_rajkumar , for his invaluable guidance and continuous support throughout the development of NeuroCloak. His technical insights, critical feedback, and encouragement helped us shape this project into a robust, production-grade AI governance platform. We are truly grateful for his mentorship and the time he dedicated to helping us succeed.

Resources

Happy to answer any questions or provide additional context in the comments.

— Sama Thanvik Reddy, P. Akash, K. Abhinav, M. Srihith

Top comments (0)